Un widget est un élément d'interface utilisateur qui fournit une ou plusieurs des fonctionnalités suivantes:
- Structure pour d'autres widgets tels que les fiches et les sections
- Informations destinées à l'utilisateur, telles que du texte et des images, ou
- Fonctionnalité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 cartes définissent l'interface utilisateur globale du module complémentaire. Les widgets ont la même apparence et la même fonctionnalité 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 en trois groupes: les widgets structurels, les widgets d'informations 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'UI.
- Ensemble de boutons : ensemble d'un ou de plusieurs boutons textuels ou imagés, regroupés dans une ligne horizontale.
- Carte : carte de contexte unique contenant une ou plusieurs sections. Vous définissez la façon dont les utilisateurs peuvent passer d'une fiche à l'autre en configurant la navigation entre les fiches.
- 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 de la fiche et les actions universelles s'affichent dans l'en-tête de la fiche si le module complémentaire les utilise.
- Section de la fiche : groupe de widgets regroupés, séparé des autres sections de la fiche par une ligne horizontale et éventuellement doté d'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 fiches à une section de fiches.
En plus de ces widgets structurels de base, dans un module complémentaire Google Workspace, vous pouvez utiliser le service de carte pour créer des structures qui se chevauchent avec la carte actuelle : pieds de page fixes et fiches aperçu:
Pied de page fixe
Vous pouvez ajouter une ligne fixe de boutons en 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 nouveau contenu contextuel est déclenché par une action de l'utilisateur, comme l'ouverture d'un message Gmail, vous pouvez afficher le nouveau contenu contextuel immédiatement (comportement par défaut) ou une notification de carte d'aperçu en bas de la barre latérale. Si un utilisateur clique sur Précédent pour revenir à votre page d'accueil alors qu'un déclencheur contextuel est actif, une fiche Aperçu s'affiche pour aider les utilisateurs à retrouver le contenu contextuel.
Pour afficher une fiche 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 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 immédiatement la fiche actuelle.
Pour personnaliser l'en-tête de la fiche 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 Aperçu ne contient que le nom de votre module complémentaire.
Le code suivant, basé sur le démarrage rapide du module complémentaire Cats Google Workspace, informe les utilisateurs de nouveaux contenus contextuels à l'aide d'une fiche Peek et personnalise l'en-tête de la fiche Peek 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'informations
Les widgets d'informations 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 libellés de texte en haut et en bas, ainsi qu'une image ou une icône. Les widgets DecoratedText peuvent également inclure un widget Bouton ou Bouton d'activation/de désactivation. Les boutons d'activation/de désactivation 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 en haut et en bas doivent utiliser du texte brut.
- Paragraphe de texte : paragraphe de texte pouvant inclure des éléments formatés en HTML.
Widgets d'interaction utilisateur
Les widgets d'interaction utilisateur permettent au module complémentaire de répondre aux actions des 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 e-mails d'envoi différé ou exécuter d'autres fonctions Apps Script. Pour en savoir plus, consultez le guide Créer des fiches interactives.
- 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 comme des actions universelles, qui s'affichent 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 du texte. Vous pouvez utiliser l'une des 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 menus déroulants.
- Switch (Bouton) : widget d'activation/de désactivation. Vous ne pouvez utiliser des boutons bascule qu'avec un widget DecoratedText. Par défaut, ils s'affichent sous forme de bouton d'activation/de désactivation, mais vous pouvez les afficher sous forme de case à cocher à la place.
- Bouton de texte : bouton avec un libellé textuel. Vous pouvez spécifier 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, un texte d'invite et un texte multiligne. Le widget peut déclencher des actions lorsque la valeur du texte change.
- Grille : mise en page multicolonne représentant une collection d'éléments. Vous pouvez représenter des éléments avec une image, un titre, un sous-titre et une gamme d'options de personnalisation telles que des styles de bordure et de recadrage.
Cases à cocher DecoratedText
Vous pouvez définir un widget DecoratedText associé à une case à cocher au lieu d'un bouton ou d'un bouton d'activation/de désactivation binaire. Comme pour les boutons d'activation/de désactivation, la valeur de la case à cocher est incluse dans l'objet d'événement d'action transmis à Action associé à cet élément DecoratedText par la méthode setOnClickAction(action).
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 permettant aux utilisateurs de sélectionner une heure, une date ou les deux.
Vous pouvez utiliser 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, 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 widget 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 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'UI de sélection du sélecteur sur les ordinateurs et les appareils mobiles. Lorsqu'il est sélectionné, le sélecteur de date ouvre une interface utilisateur de calendrier basée sur le mois pour permettre à l'utilisateur de sélectionner rapidement une nouvelle date.
Lorsque l'utilisateur sélectionne le sélecteur d'heure sur un ordinateur, un menu déroulant s'ouvre avec une liste d'heures séparées par tranches de 30 minutes parmi lesquelles l'utilisateur peut faire son choix. L'utilisateur peut également saisir une heure spécifique. Sur les appareils mobiles, la sélection d'un sélecteur de date et d'heure ouvre le sélecteur de date et d'heure intégré de l'application "Horloge".
| Ordinateur | Mobile |
|---|---|
|
|
|
|
Grille
Affichez les éléments dans une mise en page multicolonne 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.
Vous pouvez configurer 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 textuels peuvent accepter 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 acceptées et leur objectif sont indiqués 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. |
| Souligné | "This is <u>underline</u>." |
Il s'agit du soulignement. |
| Barré | "This is <s>strikethrough</s>." |
Il s'agit d'un |
| 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. |
| Temps | "This is a time format: <time>2023-02-16 15:00</time>." |
Il s'agit d'un format d'heure: . |
| 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. |