Cette page a été traduite par l'API Cloud Translation.

Widgets

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

Structure d'autres widgets tels que les fiches et les sections
Informations destinées à l'utilisateur (textes et images, par exemple)
Avantages pour l'action, comme les boutons, les champs de saisie de texte ou les cases à cocher.

Les ensembles de widgets ajoutés aux sections de fiche définissent l'UI globale du module complémentaire. Les widgets ont la même apparence et fonctionnent à la fois 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.

Utiliser le kit de conception des modules complémentaires Google Workspace

Pour gagner du temps lors de la conception de widgets d'un module complémentaire, les graphistes peuvent utiliser le kit de conception d'UI des modules complémentaires Google Workspace disponible sur Figma. Vous pouvez créer un compte Figma ou demander une licence à l'administrateur de votre organisation.

Parcourez les composants et utilisez des modèles intégrés pour créer et visualiser des widgets.

Télécharger le kit de conception

Types de widgets

Les widgets complémentaires sont généralement classés en trois groupes: les widgets structurels, les widgets informatifs et les widgets d'interaction utilisateur.

Widgets structurels

Les widgets structurels fournissent des conteneurs et une organisation aux autres widgets utilisés dans l'IA.

Widgets structurels

Ensemble de boutons : ensemble d'un ou de plusieurs boutons d'image, regroupés dans une ligne horizontale.
Card : fiche de contexte unique contenant une ou plusieurs sections de fiche. Vous définissez la manière dont les utilisateurs peuvent passer d'une fiche à l'autre en configurant la navigation par carte.
Header card : 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 la fiche et les actions universelles apparaissent dans l'en-tête de la fiche si le module complémentaire les utilise.
Section fiche : groupe de widgets collectés, divisé par les autres sections de la fiche par une règle horizontale et é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 à une section de fiche.

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

Pied de page fixe

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 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("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

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

Exemple de widget de pied de page corrigé

Aperçu des cartes

Exemple de carte en aperçu

Lorsque du nouveau contenu contextuel est déclenché par une action de l'utilisateur (par exemple, l'ouverture d'un message Gmail), vous pouvez afficher le nouveau contenu contextuel immédiatement (comportement par défaut) ou afficher une notification de la fiche d'aperçu en 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 aider les utilisateurs à 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 ne s'affiche que si une seule carte est renvoyée 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, un en-tête de carte Peek contient uniquement le nom de votre module complémentaire.

Le code suivant, basé sur le guide de démarrage rapide du module complémentaire Google Workspace pour Cats, informe les utilisateurs sur le nouveau contenu contextuel à l'aide d'une fiche Peek et personnalise l'en-tête 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 informatifs présentent des informations à l'utilisateur.

Image : image indiquée par une URL hébergée publiquement et accessible publiquement que vous fournissez.
DecoratedText : chaîne de contenu de texte que vous pouvez associer à d'autres éléments tels que les libellés de texte en haut et en bas, et à une image ou une icône. Les widgets DecoratedText peuvent également inclure un widget Button ou Switch. Les commutateurs ajoutés peuvent être des boutons d'activation/de désactivation simples 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 simple qui peut inclure des éléments au format HTML.

Widgets d'interaction utilisateur

Widget d'action de la fiche

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 ou exécuter d'autres fonctions Apps Script. Pour en savoir plus, consultez le guide Créer des cartes interactives.

Widgets d'interaction utilisateur

Action liée à la fiche : élément de menu placé dans le menu de la barre d'en-tête de module complémentaire. Le menu de la barre d'en-tête peut également contenir des éléments définis en tant qu'actions universelles, qui apparaissent sur chaque fiche définie par le module complémentaire.
Sélecteurs de date et heure : widgets permettant 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 icônes prédéfinies ou une image hébergée publiquement accessible via son URL.
Saisie de la sélection : champ de saisie qui représente 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 zones de sélection déroulantes.
Switch : widget d'activation/de désactivation. Vous ne pouvez utiliser les contacteurs qu'avec un widget DecoratedText. Par défaut, ils s'affichent en tant que bouton d'activation, 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 de 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 contenir un titre, un indice et un texte multiligne. Le widget peut déclencher des actions lorsque la valeur de texte change.
Grille : mise en page à plusieurs colonnes représentant un ensemble d'éléments. Vous pouvez représenter des éléments avec une image, un titre, un sous-titre et toute une gamme d'options de personnalisation, telles que des styles de bordure et de recadrage.

Cases décorées

Vous pouvez définir un widget DecoratedText associé à une case à cocher, au lieu d'un bouton d'activation/de désactivation 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é à cet 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 carte:

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

Exemple de widget en case de texte décoré

Sélecteurs de date et d'heure

Vous pouvez définir des widgets pour permettre 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 et d'heure, et un sélecteur de date et d'heure, que vous pouvez ensuite ajouter à une fiche:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the 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 the 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 the date and time in EDT 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 widgets de sélecteur d'heure. Ce gestionnaire met simplement en forme et enregistre une chaîne représentant la date et l'heure choisies par l'utilisateur dans un widget de sélection de l'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 de sélection des sélecteurs sur les ordinateurs et les appareils mobiles. Lorsque cette option est sélectionnée, le sélecteur de date ouvre une UI de calendrier basée sur le mois pour permettre à l'utilisateur de choisir rapidement une nouvelle date.

Lorsque l'utilisateur sélectionne le sélecteur d'heure sur les ordinateurs de bureau, un menu déroulant s'ouvre avec une liste d'heures séparées par incréments de 30 minutes. L'utilisateur peut également saisir une heure précise. Sur les appareils mobiles, l'outil de sélection de l'heure ouvre le sélecteur de temps intégré.

Ordinateur	Mobile

Grille

Affichez des éléments dans 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 la grille.

Vous pouvez configurer un élément de la 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("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

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

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

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

Mise en forme du texte

Certains widgets textuels acceptent une mise en forme HTML simple. Lorsque vous définissez le contenu textuel de ces widgets, il vous suffit d'inclure 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>."`	C'est gras.
Italique	`"This is <i>italics</i>."`	C'est en italique.
Souligné	`"This is <u>underline</u>."`	C'est souligné.
Barrer	`"This is <s>strikethrough</s>."`	C'est ~~barré~~.
Couleur de la police	`"This is <font color=\"#FF0000\">red font</text>."`	C'est une police rouge.
Lien hypertexte	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	Ceci est un lien hypertexte.
Durée	`"This is a time format: <time>2023-02-16 15:00</time>."`	Il est au format 2023-05-10 15:00.
Retour à la ligne	`"This is the first line. <br> This is a new line.`"	Il s'agit de la première ligne. Il s'agit d'une nouvelle ligne.