Widgets

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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, telles que du texte et des images
  • Avantages de l'action (boutons, champs de saisie de texte ou cases à cocher, par exemple).

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 fonctionnent sur les Web et les appareils mobiles. La documentation de référence décrit plusieurs méthodes de création d'ensembles de widgets.

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

Pour gagner du temps lors de la conception des widgets d'un module complémentaire, les concepteurs peuvent utiliser le kit de conception d'interface utilisateur de 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 de structure

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

Widgets de structure

  • Bouton défini : ensemble d'un ou de plusieurs boutons d'image ou de texte regroupés sur une ligne horizontale.
  • Fiche : une fiche de contexte contenant une ou plusieurs sections de fiches. Vous pouvez définir la façon dont les utilisateurs peuvent passer d'une fiche à l'autre en configurant la navigation dans les fiches.
  • En-tête de la carte : en-tête d'une fiche donnée. Les en-têtes de fiche peuvent contenir des titres, des sous-titres et une image. Les actions associées à 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é, divisé par les autres sections des fiches 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 de cartes à une section de fiche.

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

Vous pouvez désormais ajouter une rangée fixe de boutons au bas de votre fiche. Cette ligne ne bouge pas et ne fait pas défiler 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 fixe

Aperçu des cartes

Exemple de fiche de présentation

Lorsqu'un nouveau 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 de carte de présentation au bas de la barre latérale. Si un utilisateur clique sur Retour pour revenir à votre page d'accueil lorsqu'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 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, 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 Cats pour Google Workspace, informe les utilisateurs de nouveaux contenus contextuels avec une carte Peek et personnalise l'en-tête de la fiche 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);
      

 

Exemple de fiche d'aperçu personnalisée

Widgets d'information

Widgets d'information

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

  • Image : image qu'une URL hébergée et publique d'accès que vous indiquez peut indiquer.
  • DecoratedText : chaîne de contenu texte que vous pouvez associer à d'autres éléments, tels que des étiquettes textuelles en haut et en bas, ainsi qu'une image ou une icône. Les widgets TextdecorationatedText peuvent également inclure un widget Button ou Switch. Les contacteurs ajoutés peuvent être des boutons bascules ou des cases à cocher simples. Vous pouvez utiliser la mise en forme HTML pour le contenu du widget TextatedTextText. Les libellés du haut et du bas 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 d'Apps Script. Pour en savoir plus, consultez le guide Créer des fiches interactives.

Widgets d'interaction utilisateur

  • Action de la 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 en tant qu'actions universelles, qui s'affichent sur chaque carte 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 nombreuses icônes prédéfinies ou une image hébergée publiquement qui est indiquée par son URL.
  • Entrée de sélection : champ de saisie qui représente un ensemble d'options. Les widgets de sélection d'entrée sont présentés sous forme de cases à cocher, de cases d'option ou de boîtes déroulantes de sélection.
  • Switch : widget d'activation/de désactivation. Vous ne pouvez utiliser des contacteurs qu'avec un widget DecoratedText. Par défaut, elles s'affichent sous la forme d'un bouton d'activation, mais vous pouvez les afficher sous forme de case à cocher.
  • Bouton Texte : bouton avec une étiquette 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 "transparent"). Vous pouvez également désactiver le bouton si nécessaire.
  • Saisie de texte : champ de saisie de texte. Le widget peut contenir un titre, du texte d'aide ou du texte multiligne. Le widget peut déclencher des actions lorsque la valeur textuelle 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 à cocher "Décoré"

Vous pouvez définir un widget DecoratedText associé à une case à cocher, plutôt qu'un bouton ou un bouton d'activation binaire. Comme pour les commutateurs, la valeur de la case à cocher est incluse dans l'objet d'événement d'action transmis à la Action associée à cet DecoratedText par la méthode setOnClickAction(action).

L'extrait de code suivant montre comment définir une case à cocher DecoratedText, 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 de case en forme de 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 uniquement, ainsi qu'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"));
      

 

Exemple de fiche d'aperçu personnalisée

Voici un exemple de fonction de gestionnaire de widgets de sélecteur de date/heure. Ce gestionnaire met simplement en forme et consigne 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 de sélecteurs sur les ordinateurs et les appareils mobiles. Lorsque cette option est sélectionnée, le sélecteur de date ouvre une interface utilisateur d'agenda basée sur un mois pour permettre à l'utilisateur de choisir 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'intervalles séparés par incréments de 30 minutes. L'utilisateur peut également saisir une heure spécifique. Sur les appareils mobiles, le sélecteur de temps intégré ouvre le sélecteur de temps intégré.

Ordinateur Mobile
exemple de sélection de sélecteur de date exemple de sélection de date pour le mobile
exemple de sélection du sélecteur de temps exemple de sélection du sélecteur de temps d'utilisation des appareils mobiles

Grille

Afficher les é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 grille.

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

 

Exemple de widget Grille

Mise en forme du texte

Certains widgets de type texte 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 formats suivants sont acceptés :

Format Exemple Résultat affiché
Gras <b>test</b> Test
Italique <i>test</i> Test
Souligné <u>test</u> Test
Barrer <s>test</s> Test
Couleur de la police <font color="#ea9999">test</font> Test
Lien hypertexte <a href="http://www.google.com">google</a> google
Durée <time>2020-02-16 15:00</time> 16-02-2020 15:00
Retour à la ligne test <br> test test
test