Widgets

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

  • Structure d'autres widgets, comme des fiches et des sections
  • Informations destinées à l'utilisateur, telles que du texte et des images
  • Options associées aux actions telles que les boutons, les champs de saisie de texte ou les cases à cocher.

Les ensembles de widgets ajoutés aux sections de fiches définissent l'interface utilisateur globale des modules complémentaires. Les widgets ont la même apparence et le même fonctionnement sur le Web et sur les appareils mobiles. La documentation de référence décrit plusieurs méthodes permettant de créer des ensembles de widgets.

Types de widgets

Les widgets de modules complémentaires sont généralement classés dans trois groupes: les widgets de structure, les widgets d'information et les widgets d'interaction utilisateur.

Widgets de structure

Les widgets de structure 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 dans une ligne horizontale.
  • Fiche : fiche de contexte unique contenant une ou plusieurs sections de fiche. Pour définir la façon dont les utilisateurs peuvent passer d'une fiche à une autre, configurez la navigation par fiche.
  • En-tête de la 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 sur les fiches et les actions universelles apparaissent dans l'en-tête de la fiche si le module complémentaire les utilise.
  • Section des fiches : groupe de widgets collecté, divisé des autres sections de fiches par une règle horizontale et éventuellement un en-tête de section. Chaque fiche doit comporter au moins une section de fiche. Vous ne pouvez pas ajouter de cartes ni d'en-têtes de carte à une section de carte.

Widgets de structure

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

Vous pouvez désormais ajouter une rangée 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 carte. 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();
      

 

Exemple de widget de pied de page corrigé

Aperçu des cartes

Exemple de fiche récapitulative

Lorsqu'un nouveau contenu contextuel est déclenché par une action de l'utilisateur, comme l'ouverture d'un message Gmail, vous pouvez l'afficher immédiatement (comportement par défaut) ou afficher une notification en aperçu au bas de la barre latérale. Si un utilisateur clique sur Retour 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, au lieu d'afficher immédiatement le nouveau contenu contextuel, ajoutez .setDisplayStyle(CardService.DisplayStyle.PEEK) à votre classe CardBuilder. Une fiche d'aperçu n'apparaît que si un seul objet carte est renvoyé avec votre déclencheur contextuel. Sinon, les cartes renvoyées remplacent immédiatement la carte actuelle.

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

Le code suivant, basé sur le guide de démarrage rapide du module complémentaire Cats Google Workspace, informe les utilisateurs du nouveau contenu contextuel à l'aide d'une fiche "Peek" et personnalise l'en-tête de cette fiche pour afficher l'objet du fil de message 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);
      

 

Exemple de fiche d'aperçu personnalisée

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 que vous fournissez.
  • DecoratedText : chaîne de contenu textuel que vous pouvez associer à d'autres éléments, tels que des étiquettes de texte en haut et en bas, ainsi qu'une image ou une icône. Les widgets DecoratedText peuvent également inclure un widget Button (Bouton) ou Switch (Bouton bascule). Les commutateurs ajoutés peuvent être des boutons d'activation/de désactivation ou des cases à cocher. Le texte du contenu du widget DecoratedText peut utiliser la mise en forme HTML. Les libellés supérieur et inférieur doivent utiliser du texte brut.
  • Paragraphe de texte : paragraphe de texte pouvant inclure des éléments au format HTML.

Widgets d'information

Widgets d'interaction utilisateur

Les widgets d'interaction utilisateur permettent au module complémentaire de répondre aux actions effectuées par les utilisateurs. Vous pouvez configurer 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 : widgets qui 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 ci-dessous.
  • Bouton "Image" : bouton qui utilise une image au lieu de texte. Vous pouvez utiliser l'une des nombreuses icônes prédéfinies ou une image hébergée publiquement indiquée par son URL.
  • Entrée de sélection : champ de saisie représentant un ensemble d'options. Les widgets de saisie de sélection se présentent sous la forme de cases à cocher, de cases d'option ou de cases de sélection déroulantes.
  • Bouton bascule : widget d'activation/de désactivation. Vous ne pouvez utiliser des commutateurs qu'avec un widget DecoratedText. Par défaut, ils s'affichent sous la forme d'un bouton bascule, mais vous pouvez les faire apparaître sous la forme d'une case à cocher.
  • Bouton Texte : bouton avec un libellé de texte. Vous pouvez spécifier un remplissage avec une couleur 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 titre, une indication et un texte multiligne. Le widget peut déclencher des actions lorsque la valeur textuelle change.
  • Grille : mise en page à plusieurs colonnes qui représente un ensemble d'éléments. Vous pouvez représenter des éléments avec une image, un titre, un sous-titre et différentes options de personnalisation, telles que des styles de bordure et de recadrage.
Widget d'action sur la fiche Widgets d'interaction utilisateur

DecoratedText cases à cocher

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

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

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

 

Exemple de widget de case à cocher avec texte décoré

Sélecteurs de date et d'heure

Vous pouvez définir des widgets qui permettent aux utilisateurs de sélectionner une heure, une date ou les deux. Vous pouvez utiliser setOnChangeAction() pour attribuer une fonction de gestionnaire de widgets à exécuter lorsque la valeur du sélecteur change.

L'extrait de code suivant montre comment définir un sélecteur de date, d'heure et de date, que vous pouvez ensuite 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"));
      

 

Exemple de fiche d'aperçu personnalisée

Voici un exemple de fonction de gestionnaire de widget de sélecteur de date et d'heure. Ce gestionnaire formate et consigne simplement une chaîne représentant la date et l'heure choisie par l'utilisateur dans un widget de sélection 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/apps-script/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 ci-dessous présente des exemples d'interfaces utilisateur permettant de sélectionner un sélecteur sur ordinateur et sur appareil mobile. Lorsque cette option est sélectionnée, le sélecteur de date ouvre une interface utilisateur de calendrier mensuelle permettant à l'utilisateur de sélectionner rapidement une nouvelle date.

Lorsque l'utilisateur sélectionne le sélecteur d'heure sur un ordinateur de bureau, un menu déroulant s'ouvre et affiche une liste d'heures séparées par incréments 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
exemple de sélection du sélecteur de date exemple de sélection du sélecteur de date mobile
exemple de sélection de l'outil de sélection de l'heure exemple de sélection de l'outil de sélection de l'heure sur mobile

Grille

Affichez les éléments selon une mise en page à plusieurs colonnes avec le widget 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.

Vous pouvez configurer un élément de grille avec un identifiant qui est renvoyé en tant que paramètre pour l'action définie dans 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"));
      

 

Exemple de widget de grille

Mise en forme du texte

Certains widgets texte peuvent accepter une mise en forme HTML de texte simple. Lorsque vous définissez le contenu textuel de ces widgets, incluez simplement les balises HTML correspondantes.

Les balises compatibles et leur fonction sont présentées dans le tableau suivant:

Format Exemple Résultat affiché
Gras "This is <b>bold</b>." Ceci est en gras.
Italique "This is <i>italics</i>." Ce texte est en italique.
Underline "This is <u>underline</u>." C'est du souligné.
Barrer "This is <s>strikethrough</s>." Elle est barrée.
Couleur de la police "This is <font color=\"#FF0000\">red font</font>." Il s'agit d'une police rouge.
Lien hypertexte "This is a <a href=\"https://www.google.com\">hyperlink</a>." Ceci est un lien hypertexte.
Heure "This is a time format: <time>2023-02-16 15:00</time>." Voici un format d'heure: .
Retour à la ligne "This is the first line. <br> This is a new line. pouces Ceci est la première ligne.
Ceci est une nouvelle ligne.