Widgets

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

  • Structure des autres widgets, comme les fiches et les sections
  • Informations destinées à l'utilisateur, telles que du texte et des images
  • Affrontements pour l'action, comme les boutons, les champs de saisie de texte ou les cases à cocher

Les ensembles de widgets ajoutés aux sections des 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 de création d'ensembles de widgets.

Types de widgets

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

Widgets de structure

Les widgets structurels fournissent des conteneurs et de l'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 de contexte unique contenant une ou plusieurs sections de carte. Vous définissez la manière dont les utilisateurs peuvent passer d'une fiche à l'autre en configurant la navigation dans les fiches.
  • En-tête de la fiche : en-tête d'une fiche donnée. Les en-têtes de carte 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 la fiche si le module complémentaire les utilise.
  • Section de la fiche : groupe de widgets collecté, divisé des autres sections de la fiche par une règle horizontale et comportant éventuellement un en-tête de section. Chaque fiche doit comporter au moins une section de carte. Vous ne pouvez pas ajouter de cartes ni de titres de carte à une section de carte.

Widgets de structure

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

Vous pouvez 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.

Exemple de widget de pied de page corrigé

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

Exemple de fiche d'aperçu

Lorsque le 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 lorsqu'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 de 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 d'aperçu ne contient que le nom de votre module complémentaire.

Exemple de fiche d'aperçu personnalisée

Le code suivant, basé sur le guide de démarrage rapide du module complémentaire Google Workspace Cats, 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 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 que vous fournissez.
  • DecoratedText : chaîne de contenu textuelle 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 (Switch). Les commutateurs peuvent être des boutons d'activation/de désactivation ou des cases à cocher. Le texte de contenu du widget DecoratedText peut utiliser la mise en forme HTML. Les étiquettes du haut et du bas 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 sur 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 apparaissent sur chaque fiche définie par le module complémentaire.
  • Sélecteurs de date et d'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 et indiquée par son URL.
  • Entrée de 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 cases de sélection déroulantes.
  • Switch (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 du texte 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 diverses 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 est associée une case à cocher, plutôt qu'un bouton ou un interrupteur binaire. Comme pour les commutateurs, la valeur de la case à cocher est incluse dans l'objet d'événement d'action transmis au Action associé à ce DecoratedText par la méthode setOnClickAction(action).

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

L'extrait de code suivant montre comment définir un widget de case à cocher DecoratedText, 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));

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.

Exemple de fiche d'aperçu personnalisée

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"));

Voici un exemple de fonction de gestionnaire de widgets de sélecteur de date et d'heure. Ce gestionnaire met en forme et consigne 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 suivant présente des exemples d'interfaces utilisateur permettant de sélectionner un sélecteur sur un ordinateur de bureau et sur un appareil mobile. Lorsque cette option est sélectionnée, le sélecteur de date ouvre une interface utilisateur de calendrier mensuelle pour permettre à 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 avec 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 de l'heure ouvre le sélecteur intégré d'horloge mobile.

Ordinateur Mobile
exemple de sélection du sélecteur de date exemple de sélection du sélecteur de date sur mobile
exemple de sélection du sélecteur de temps exemple de sélection de l'outil de sélection de l'heure sur 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 grille.

Vous pouvez configurer un élément de grille avec un identifiant qui est renvoyé en tant que paramètre de l'action définie sur la grille.

Exemple de widget sous forme de 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 textuels sont compatibles avec la mise en forme HTML simple du texte. Lorsque vous définissez le contenu textuel de ces widgets, n'incluez que 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>." Ce texte est en gras.
Italique "This is <i>italics</i>." Ce texte est en italique.
Underline "This is <u>underline</u>." C'est un souligné.
Barré "This is <s>strikethrough</s>." Il est barré.
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>." Il s'agit d'un lien hypertexte.
Heure "This is a time format: <time>2023-02-16 15:00</time>." Le format de l'heure est le suivant: .
Retour à la ligne "This is the first line. <br> This is a new line. pouces Il s'agit de la première ligne.
Ceci est une nouvelle ligne.