Un widget est un élément d'interface utilisateur qui fournit un ou plusieurs des éléments suivants:
- La structure d'autres widgets, comme les fiches et les sections,
- Informations destinées à l'utilisateur, comme du texte et des images
- Tarifs d'action, comme 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'intégralité du module complémentaire. Widgets ont la même apparence et la même fonction sur le Web et 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 catégories les groupes: widgets structurels, des widgets d'information et des widgets d'interaction utilisateur.
Widgets de structure
Les widgets de structure fournissent des conteneurs et permettent d'organiser les autres widgets utilisées dans l'interface utilisateur.
- Bouton défini : A collection d'un ou de plusieurs boutons de texte ou d'image, regroupés dans un horizontale.
- Fiche : contexte unique qui contient une ou plusieurs sections de fiches. C'est vous qui définissez la manière dont les utilisateurs entre les cartes en configurant Navigation dans les cartes.
- En-tête de la carte : pour une carte donnée. Les en-têtes de fiche peuvent comporter des titres, des sous-titres et un l'image. Actions sur les fiches des actions universelles apparaissent dans la en-tête de la carte si le module complémentaire les utilise.
- Section Fiche : A ensemble de widgets collectés, divisé des autres sections de fiches par une horizontale et éventuellement d'un en-tête de section. Chaque carte doit contenir au moins une section de fiche. Vous ne pouvez pas ajouter de fiches ni d'en-têtes de cartes à une fiche .
En plus de ces widgets structurels de base, Module complémentaire Google Workspace que vous pouvez utiliser le service de cartes pour créer des structures qui chevauchent la carte actuelle: Pieds de page fixes et fiches d'aperçu:
Pied de page fixe
Vous pouvez ajouter une rangée fixe de boutons au bas de votre fiche. Cette ligne ne se déplace pas avec le reste du contenu de la fiche.
Les éléments suivants : L'extrait de code ci-dessous 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
Lorsque de nouveaux contenus contextuels est déclenchée par une action de l'utilisateur, comme l'ouverture d'un message Gmail, vous pouvez soit afficher immédiatement le nouveau contenu contextuel (comportement par défaut) ou pour afficher une notification sous forme de fiche d'aperçu en bas de la barre latérale. Si l'utilisateur clique sur Retour pour revenir à votre page d'accueil pendant qu'un le déclencheur contextuel est actif, une fiche d'aperçu s'affiche pour aider les utilisateurs à trouver du contenu contextuel.
Pour afficher une fiche d'aperçu lorsque de nouveaux contenus contextuels sont disponibles, au lieu
l'affichage immédiat du nouveau contenu contextuel, ajoutez
.setDisplayStyle(CardService.DisplayStyle.PEEK) à votre
CardBuilder
. Une fiche d'aperçu ne s'affiche que si un seul objet "card" est renvoyé avec votre
le déclencheur contextuel ; Sinon, les cartes retournées remplacent immédiatement
carte actuelle.
Pour personnaliser l'en-tête de la fiche d'aperçu, ajoutez la méthode .setPeekCardHeader() avec
un CardHeader standard
lors de la création de votre fiche contextuelle. Par défaut, un en-tête de carte d'aperçu
contient uniquement le nom de votre module complémentaire.
Le code suivant, basé sur le Guide de démarrage rapide du module complémentaire Chats pour Google Workspace Informe les utilisateurs du nouveau contenu contextuel avec une fiche d'aperçu et personnalise l'en-tête de la carte Peek pour afficher le message Gmail sélectionné l'objet du fil de discussion.
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 : une image indiquée par une URL hébergée et accessible publiquement que vous fournissez.
- DecoratedText : A SMS chaîne de contenu que vous pouvez associer à d'autres éléments comme "top" et "bottom" des étiquettes de texte et une image ou une icône. Les widgets DécoratedText peuvent également inclure un élément Bouton ou le widget Changer. Commutateurs ajoutés peuvent être des boutons d'activation/de désactivation ou des cases à cocher. Texte du contenu du widget DecoratedText peuvent utiliser Mise en forme HTML haut et les étiquettes inférieures doivent utiliser du texte brut.
- Paragraphe de texte : A paragraphe de texte, qui peut inclure HTML.
Widgets d'interaction utilisateur
Les widgets d'interaction de l'utilisateur permettent au module complémentaire de répondre aux actions effectuées par utilisateurs. Vous pouvez configurer ces widgets avec des réponses d'action à afficher différentes fiches, ouvrir des URL, afficher les notifications, rédiger des brouillons d'e-mails, ou exécuter d'autres fonctions Apps Script. Consultez le guide Créer des fiches interactives pour plus de détails.
- Action de la fiche : 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 contiennent 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 heure : widgets permettant aux utilisateurs de sélectionner une date, une heure ou les deux. Voir Sélecteurs de date et d'heure ci-dessous pour en savoir plus.
- Bouton "Image" : A qui utilise une image au lieu de texte. Vous pouvez utiliser l'une des des icônes prédéfinies ou d'une image hébergée publiquement indiquée par son URL.
- Saisie de sélection : une champ de saisie représentant un ensemble d'options. Widgets de saisie de sélection sont présentées sous forme de cases à cocher, de cases d'option ou de boîtes de sélection déroulantes.
- Bouton bascule : bouton bascule . Vous ne pouvez utiliser les contacteurs qu'avec un Widget DecoratedText. Par défaut ils s'affichent sous forme d'interrupteurs, une case à cocher.
- Bouton Texte : A avec un libellé textuel. Vous pouvez spécifier une couleur de remplissage pour l'arrière-plan du texte (par défaut, transparent). Vous pouvez également désactiver le bouton nécessaires.
- Saisie de texte : texte . Le widget peut comporter un titre, des indications et un texte multiligne. Le widget peut déclencher des actions lorsque la valeur du texte change.
- Grille : plusieurs colonnes qui représente une collection d'éléments. Vous pouvez représenter des éléments Image, titre, sous-titre et diverses options de personnalisation, comme la bordure et les styles de recadrage.
DecoratedText cases à cocher
Vous pouvez définir un élément DecoratedText
widget associé à une case à cocher, au lieu d'un bouton ou d'un bouton d'activation binaire.
bouton bascule. Comme pour les commutateurs, la valeur de la case à cocher est incluse dans
Objet événement d'action
transmis à Action
associé à ce DecoratedText
par le
setOnClickAction(action)
.
L'extrait de code suivant montre comment définir une 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 widgets à
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 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élection de la date et de l'heure. Ce les formats de gestionnaire et consigne une chaîne représentant la date et l'heure choisies par l'utilisateur dans un widget de sélection de date et 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'interfaces utilisateur de sélection du sélecteur sur ordinateur et sur mobile appareils. Lorsque cette option est sélectionnée, le sélecteur de date ouvre une interface de calendrier mensuel à 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 incréments de 30 minutes que l'utilisateur peut sélectionner L'utilisateur peut également saisir une heure spécifique. Sur les appareils mobiles, le sélecteur d'heure ouvre l'horloge intégrée dans l'application mobile de l'outil de sélection de l'heure.
| Ordinateur | Mobile |
|---|---|
|
|
|
|
Grille
Affichez les éléments dans une mise en page multicolonne 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 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 sont compatibles avec le format HTML simple du texte. Lors de la configuration le contenu textuel de ces widgets, il vous suffit d'inclure les balises HTML correspondantes.
Les balises prises en charge et leur fonction sont présentées ci-dessous tableau:
| Format | Exemple | Résultat affiché |
|---|---|---|
| Gras | "This is <b>bold</b>." |
Ce texte est en gras. |
| Italique | "This is <i>italics</i>." |
Ceci est en italique. |
| Souligné | "This is <u>underline</u>." |
C'est du texte souligner. |
| Barré | "This is <s>strikethrough</s>." |
Elle est |
| 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>." |
Il s'agit du format d'heure suivant: . |
| 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. |