Widgets

Un widget est un élément d'interface utilisateur qui fournit un ou plusieurs des éléments suivants :

• Structure pour d'autres widgets tels que des fiches et des sections
• Informations à l'utilisateur telles que du texte et des images
• Possibilités d'action telles que des boutons, des champs de saisie de texte ou des cases à cocher

Les ensembles de widgets ajoutés aux sections de la fiche définissent l'interface utilisateur globale du module complémentaire. Les widgets ont la même apparence et la même fonction sur le Web et sur les appareils mobiles. La documentation de référence décrit plusieurs méthodes pour créer des ensembles de widgets.

Types de widgets

Les widgets de module complémentaire sont généralement classés en trois groupes : les widgets structurels, les widgets d'information et les widgets d'interaction utilisateur.

Widgets structurels

Les widgets structurels fournissent des conteneurs et une organisation pour les autres widgets utilisés dans l'interface utilisateur.

• Ensemble de boutons : ensemble d'un ou de plusieurs boutons de texte ou d'image, regroupés sur une ligne horizontale.
• Fiche : fiche contextuelle unique contenant une ou plusieurs sections. Définissez la façon dont les utilisateurs passent d'une fiche à l'autre en configurant la navigation entre les fiches.
• En-tête de fiche : en-tête d'une fiche donnée. Les en-têtes de fiche peuvent comporter des titres, des sous-titres et une image. Les actions de fiche et les actions universelles apparaissent dans l'en-tête de fiche si elles sont utilisées.
• Section de fiche : groupe de widgets collectés, séparés des autres sections de fiche par une règle horizontale et comportant éventuellement un en-tête de section. Chaque fiche doit comporter au moins une section. Vous ne pouvez pas ajouter de fiches ni d'en-têtes de fiche à une section de fiche.

Lorsque vous ajoutez un widget à l'un des conteneurs, vous créez et ajoutez une copie de ce widget. Si vous modifiez le widget après l'avoir ajouté, la modification n'est pas reflétée dans l'interface. Assurez-vous que le widget est complet avant de l'ajouter. Si vous devez modifier un widget après l'avoir ajouté, recréez l'intégralité de la section de fiche ou de la fiche. Pour en savoir plus, consultez la section Créer des fiches.

En plus de ces widgets structurels de base, dans un module complémentaire Google Workspace, vous pouvez utiliser le service de fiche pour créer des structures qui se chevauchent avec la fiche actuelle : pieds de page fixes et aperçus de fiches :

Pied de page fixe

Vous pouvez ajouter une ligne fixe de boutons au bas de votre fiche. Cette ligne ne se déplace pas et ne défile pas avec le reste du contenu de la fiche.

L'extrait de code suivant montre comment définir un exemple de pied de page fixe et l'ajouter à une fiche :

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

Aperçu des cartes

Lorsqu'un nouvel élément de contenu contextuel est déclenché par une action de l'utilisateur, par exemple l'ouverture d'un message Gmail, vous pouvez afficher immédiatement le nouveau contenu contextuel (comportement par défaut) ou afficher une notification d'aperçu de fiche en bas de la barre latérale. Si un utilisateur clique sur Retour arrow_back pour revenir à votre page d'accueil alors qu'un déclencheur contextuel est actif, une fiche d'aperçu s'affiche pour l'aider à retrouver le contenu contextuel.

Pour afficher une fiche d'aperçu lorsqu'un nouveau contenu contextuel est disponible, ajoutez .setDisplayStyle(CardService.DisplayStyle.PEEK) à votre CardBuilder classe. Une fiche d'aperçu ne s'affiche que si un seul objet de fiche est renvoyé avec votre déclencheur contextuel. Sinon, les fiches renvoyées remplacent la fiche actuelle.

Pour personnaliser l'en-tête de la fiche d'aperçu, ajoutez la .setPeekCardHeader méthode avec un objet CardHeader standard lorsque vous créez votre fiche contextuelle. Par défaut, un en-tête de fiche d'aperçu ne contient que le nom de votre module complémentaire.

En s'appuyant sur le démarrage rapide du module complémentaire Cats Google Workspace, le code suivant informe les utilisateurs du nouveau contenu contextuel à l'aide d'une fiche d'aperçu et personnalise l'en-tête de la fiche d'aperçu pour afficher l'objet du fil de discussion Gmail sélectionné.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);

Widgets d'information

Les widgets d'information présentent des informations à l'utilisateur.

• Image : image indiquée par une URL hébergée et accessible au public.
• DecoratedText Les widgets DecoratedText peuvent également inclure un widget Button ou un widget Switch. Les commutateurs ajoutés peuvent être des boutons d'activation/de désactivation ou des cases à cocher. Le texte du contenu peut utiliser la mise en forme HTML. Les libellés en haut et en bas doivent utiliser du texte brut.
• Paragraphe de texte : paragraphe de texte pouvant inclure des éléments mis en forme en HTML.

Widgets d'interaction utilisateur

Les widgets d'interaction utilisateur permettent au module complémentaire de répondre aux actions de l'utilisateur. Configurez ces widgets avec des réponses d'action pour afficher différentes fiches, ouvrir des URL, afficher des notifications, rédiger des brouillons d'e-mails ou exécuter d'autres fonctions Apps Script. Pour en savoir plus, consultez le guide Créer des fiches interactives.

• Action de fiche : élément de menu placé dans le menu de la barre d'en-tête du module complémentaire. Le menu de la barre d'en-tête peut également contenir des éléments définis comme des actions universelles, qui apparaissent sur chaque fiche définie par le module complémentaire.
• Sélecteurs de date et d'heure : les widgets permettent aux utilisateurs de sélectionner une date, une heure ou les deux. Pour en savoir plus, consultez la section Sélecteurs de date et d'heure.
• Bouton d'image : bouton qui utilise une image au lieu de texte. Utilisez l'une des nombreuses icônes prédéfinies ou une image hébergée publiquement.
• Entrée de sélection : champ d'entrée représentant une collection d'options. Les widgets d'entrée de sélection se présentent sous forme de cases à cocher, de cases d'option ou de zones de sélection déroulantes.
• Commutateur : widget d'activation/de désactivation utilisé avec un widget DecoratedText. Par défaut, ils s'affichent sous forme de commutateur, mais vous pouvez les afficher sous forme de case à cocher.
• Bouton Texte : bouton avec un libellé de texte. Spécifiez une couleur de remplissage d'arrière-plan pour les boutons de texte (la valeur par défaut est transparente). Vous pouvez également désactiver le bouton si nécessaire.
• Saisie de texte : champ de saisie de texte. Le widget peut comporter un texte de titre, un texte d'aide et un texte multiligne. Le widget peut déclencher des actions lorsque la valeur du texte change.
• Grille : mise en page à plusieurs colonnes. Représentez les éléments avec une image, un titre, un sous-titre et des options de personnalisation telles que les styles de bordure et de recadrage.

Cases à cocher DecoratedText

Vous pouvez définir un DecoratedText widget auquel est associée une case à cocher, au lieu d'un bouton ou d'un commutateur binaire. Comme pour les commutateurs, la valeur de la case à cocher est incluse dans l' objet d'événement d'action transmis à l'Action associé à ce DecoratedText par la méthode setOnClickAction.

L'extrait de code suivant montre comment définir un widget DecoratedText de case à cocher à ajouter à une fiche :

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

Sélecteurs de date et d'heure

Définissez des widgets permettant aux utilisateurs de sélectionner une heure, une date ou les deux. Utilisez setOnChangeAction pour attribuer une fonction de gestionnaire de widget à exécuter lorsque la valeur du sélecteur change.

L'extrait de code suivant montre comment définir un sélecteur de date uniquement, un sélecteur d'heure uniquement et un sélecteur de date et d'heure à ajouter à une fiche :

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a date")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter a time")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter a date and time")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));

Voici un exemple de fonction de gestionnaire de widget de sélecteur de date et d'heure. Ce gestionnaire met en forme et enregistre une chaîne représentant la date et l'heure choisies par l'utilisateur dans un widget de sélecteur de date et d'heure avec l'ID myDateTimePickerWidgetID :

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See:
  // https://developers.google.com/workspace/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

Le tableau suivant présente des exemples d'interfaces utilisateur de sélection de sélecteur sur des ordinateurs et des appareils mobiles. Lorsqu'il est sélectionné, le sélecteur de date ouvre une interface utilisateur de calendrier mensuel pour permettre à l'utilisateur de sélectionner une nouvelle date.

Lorsque l'utilisateur sélectionne le sélecteur d'heure sur les ordinateurs, un menu déroulant s'ouvre avec une liste d'heures séparées par intervalles de 30 minutes. L'utilisateur peut également saisir une heure spécifique. Sur les appareils mobiles, la sélection d'un sélecteur d'heure ouvre le sélecteur d'heure "horloge" mobile intégré.

Ordinateur	Mobile

Grille

Affichez les éléments dans une mise en page à plusieurs colonnes avec le widget de grille. Chaque élément peut afficher une image, un titre et un sous-titre. Utilisez des options de configuration supplémentaires pour définir le positionnement du texte par rapport à l'image dans un élément de grille.

Configurez un élément de grille avec un identifiant renvoyé en tant que paramètre à l'action définie sur la grille.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

var grid = CardService.newGrid()
  .setTitle("Recently viewed")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

Mise en forme du texte

Certains widgets basés sur du texte sont compatibles avec la mise en forme HTML de base. Lorsque vous définissez le contenu textuel de ces widgets, incluez les balises HTML correspondantes.

Les balises compatibles et leur objectif sont présentés dans le tableau suivant :