Ein Widget ist ein UI-Element, das mindestens eines der folgenden Elemente bereitstellt:
- Strukturierung für andere Widgets wie Karten und Abschnitte
- Informationen für den Nutzer wie Text und Bilder oder
- Angebote für Aktionen wie Schaltflächen, Texteingabefelder oder Kästchen.
Gruppen von Widgets, die den Kartenbereichen hinzugefügt werden, definieren Add-on-Benutzeroberfläche. Widgets werden im Web und auf Mobilgeräten gleich aussehen und funktionieren. Die Referenzdokumentation beschreibt verschiedene Methoden zum Erstellen von Widget-Sets.
Widget-Typen
Add-on-Widgets werden in der Regel in drei Kategorien unterteilt: Gruppen: Strukturelle Widgets, Informations-Widgets und Widgets für Nutzerinteraktionen.
Strukturelle Widgets
Strukturelle Widgets bieten Container und Organisation für die anderen Widgets die in der UI verwendet werden.
- Schaltflächenset: A Sammlung aus einer oder mehreren Text- oder Bildschaltflächen, die in einem horizontale Zeile.
- Karte: Einzelner Kontext die einen oder mehrere Kartenabschnitte enthält. Sie legen fest, wie Nutzer Daten verschieben dürfen zwischen Karten wechseln, indem Sie Kartennavigation.
- Kartenüberschrift: Das für eine bestimmte Karte. Kartenüberschriften können Titel, Untertitel und einen Bild. Kartenaktionen und universelle Aktionen die die Überschrift der Karte, wenn das Add-on sie verwendet.
- Kartenabschnitt: A Widget-Gruppe, aufgeteilt von den anderen Kartenabschnitten durch ein horizontalen Trennlinie und optional mit einer Abschnittsüberschrift. Jede Karte muss mindestens einen Kartenbereich. Sie können einer Karte keine Karten oder Kartenüberschriften hinzufügen .
Zusätzlich zu diesen grundlegenden Struktur-Widgets Verfügbares Google Workspace-Add-on Kartendienst, um Strukturen zu erstellen, die die aktuelle Karte überlappen: feste Fußzeilen und Peek-Karten:
Feste Fußzeile
Sie können unten auf der Karte eine feste Reihe von Schaltflächen hinzufügen. Diese Zeile sich nicht mit dem restlichen Karteninhalt bewegt oder scrollt.
Die folgenden Codeauszug zeigt, wie Sie eine feste Fußzeile als Beispiel definieren und zu einer Karte hinzufügen:
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();
Karte kurz anzeigen
Wenn neue kontextbezogene Inhalte durch eine Nutzeraktion ausgelöst, wie z. B. das Öffnen eines Gmail-Nachricht haben, können Sie die neuen kontextbezogenen Inhalte entweder sofort (Standardeinstellung) oder zeigen Sie eine Peek-Karten-Benachrichtigung unten im Seitenleiste. Wenn ein Nutzer auf „Zurück“ klickt um zur Startseite zurückzukehren, während ein Kontext-Trigger aktiv ist, wird eine Peek-Infokarte angezeigt, über die Nutzer kontextbezogenen Content zu erstellen.
Um eine Peek-Karte anzuzeigen, wenn neuer kontextbezogener Content verfügbar ist,
die neuen kontextbezogenen Inhalte sofort anzeigen,
.setDisplayStyle(CardService.DisplayStyle.PEEK)
zu deinem
CardBuilder
. Eine Peek-Karte wird nur angezeigt, wenn ein einzelnes Kartenobjekt mit deinem
kontextbezogener Trigger; Andernfalls ersetzen die zurückgegebenen Karten das
aktuelle Karte.
Fügen Sie zum Anpassen des Headers der Peek-Karte die Methode .setPeekCardHeader()
mit
ein Standard-CardHeader
-Objekt beim Erstellen der Kontextkarte. Standardmäßig wird die Überschrift einer Peek-Karte
enthält nur den Namen des Add-ons.
Der folgende Code basiert auf dem Kurzanleitung zum Google Workspace-Add-on für Katzen, informiert Nutzer mit einer Peek-Karte über neue kontextbezogene Inhalte und Den Header der Peek-Karte, um die ausgewählte Gmail-Nachricht aufzurufen Betreff des Threads.
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);
Informations-Widgets
Informations-Widgets präsentieren dem Nutzer Informationen.
- Bild: Ein Bild. die durch eine von Ihnen bereitgestellte gehostete und öffentlich zugängliche URL angegeben werden.
- DecoratedText: Eine SMS Content-String, den Sie mit anderen Elementen wie oben und unten kombinieren können. Textbeschriftungen und ein Bild oder Symbol. Verzierte Text-Widgets können auch einen Schaltfläche oder Widget Wechseln Hinzugefügte Schalter können Ein-/Aus-Schaltflächen oder Kästchen sein. Der Inhaltstext des dekorativen Text-Widgets HTML-Formatierung: oben Labels unten müssen nur Text enthalten.
- Textabsatz: A Absatztext, der folgende Zeichen enthalten kann: HTML-formatierte Elemente.
Widgets für Nutzerinteraktionen
Mit Widgets für die Nutzerinteraktion kann das Add-on auf Aktionen des Nutzenden. Sie können diese Widgets mit Aktionsantworten konfigurieren, verschiedene Karten anzeigen, URLs öffnen, Benachrichtigungen anzeigen, E-Mail-Entwürfe verfassen, oder andere Apps Script-Funktionen ausführen. Weitere Informationen finden Sie in der Interaktive Karten erstellen für Details.
- Kartenaktion: Ein Menü das im Menü der Add-on-Kopfzeile platziert wird. Das Menü der Kopfleiste kann auch Elemente enthalten, die als universelle Aktionen definiert sind, die auf jeder vom Add-on definierten Karte angezeigt werden.
- DateTime-Auswahl: Widgets bei denen Nutzer ein Datum, eine Uhrzeit oder beides auswählen können. Weitere Informationen finden Sie unter Datums- und Uhrzeitauswahl unten finden Sie weitere Informationen.
- Bildschaltfläche: Eine Schaltfläche, die ein Bild statt Text enthält. Sie können eine von mehreren vordefinierte Symbole oder ein öffentlich gehostetes Bild, das durch seine URL gekennzeichnet ist.
- Auswahleingabe: Eine Eingabefeld, das eine Sammlung von Optionen darstellt. Auswahleingabe-Widgets Sie werden als Kontrollkästchen, Optionsfelder oder Dropdown-Auswahlfelder angezeigt.
- Wechseln: Ein/Aus-Schaltfläche Widget. Sie können Schalter nur in Verbindung mit einem DecoratedText-Widget verwenden. Standardmäßig werden diese als Ein-/Aus-Schaltflächen angezeigt. Sie können sie jedoch auch als Kästchen.
- Textschaltfläche: Eine mit einem Textlabel. Sie können eine Hintergrundfarbe für den Text festlegen. -Schaltflächen (Standard ist transparent). Sie können die Schaltfläche auch deaktivieren, erforderlich.
- Texteingabe: Text Eingabefeld. Das Widget kann Titeltext, Hinweistext und mehrzeiligen Text enthalten. Das Widget kann Aktionen auslösen, wenn sich der Textwert ändert.
- Raster: mehrere Spalten das eine Sammlung von Elementen darstellt. Sie können Elemente mit einer Bild, Titel, Untertitel und verschiedene Anpassungsoptionen wie Rahmen und Zuschnittstile.
DecoratedText
Kästchen
Sie können ein DecoratedText
-Element
Widget mit einem Kästchen anstelle einer Schaltfläche oder einer binären Ein/Aus-Schaltfläche
Wie bei Schaltern ist der Wert des Kästchens im
Ereignisobjekt „Aktion“
der an die Action
übergeben wird,
hat an dieses DecoratedText
angehängt
durch die
setOnClickAction(action)
.
Der folgende Codeauszug zeigt, wie ein Kästchen DecoratedText
definiert wird
das Sie dann einer Karte hinzufügen können:
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
Datums- und Uhrzeitauswahl
Sie können Widgets definieren, über die Nutzer eine Uhrzeit, ein Datum oder beides auswählen können.
Sie können setOnChangeAction()
verwenden, um diesen eine Widget-Handler-Funktion zuzuweisen.
wird ausgeführt, wenn sich der Wert der Auswahl ändert.
Der folgende Codeauszug zeigt, wie Sie eine reine Datumsauswahl, und eine Datums-/Uhrzeitauswahl, die Sie dann einer Karte hinzufügen können:
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"));
Im Folgenden finden Sie ein Beispiel für die Handler-Funktion eines Widget-Handlers zur Datums-/Uhrzeitauswahl. Dieses Der Handler formatiert und protokolliert einen String, der die von dem Nutzer in einem Datums-/Uhrzeitauswahl-Widget mit der ID "myDateTimePickerWidgetID" zu:
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);
}
}
Die folgende Tabelle enthält Beispiele für die UIs zur Auswahl der Auswahl auf Computern und Mobilgeräten. Geräte. Wenn diese Option ausgewählt ist, wird über die Datumsauswahl eine monatliche Kalender-UI geöffnet, schnell ein neues Datum auswählen.
Wenn der Nutzer auf Desktop-Geräten die Zeitauswahl auswählt, wird ein Drop-down-Menü geöffnet. mit einer Liste von Zeiten in 30-Minuten-Schritten, die der Nutzer auswählen kann aus. Der Nutzer kann auch eine bestimmte Uhrzeit eingeben. Auf Mobilgeräten wählen Sie mit der Zeitauswahl öffnet sich die integrierte mobile „Uhr“ Zeitauswahl.
Computer | Mobilgeräte |
---|---|
![]() |
![]() |
![]() |
![]() |
Raster
Mit dem Raster-Widget können Sie Elemente in einem mehrspaltigen Layout anzeigen lassen. Jedes Element kann ein Bild, einen Titel und eine Unterüberschrift anzeigen. Mit zusätzlichen Konfigurationsoptionen Die Positionierung von Text relativ zum Bild in einem Rasterelement festlegen.
Sie können ein Rasterelement mit einer Kennung konfigurieren, die als Parameter zurückgegeben wird auf die im Raster definierte Aktion hinzu.
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"));
Textformatierung
Einige textbasierte Widgets unterstützen die einfache Text-HTML-Formatierung. Beim Festlegen den Textinhalt dieser Widgets, fügen Sie einfach die entsprechenden HTML-Tags ein.
Die unterstützten Tags und ihr Zweck sind im Folgenden aufgeführt. Tabelle:
Format | Beispiel | Gerendertes Ergebnis |
---|---|---|
Fett | "This is <b>bold</b>." |
Fett. |
Kursiv | "This is <i>italics</i>." |
Dies ist kursiv. |
Unterstrichen | "This is <u>underline</u>." |
Dies ist Unterstrich. |
Durchgestrichen | "This is <s>strikethrough</s>." |
Dies ist |
Schriftfarbe | "This is <font color=\"#FF0000\">red font</font>." |
in roter Schrift. |
Hyperlink | "This is a <a href=\"https://www.google.com\">hyperlink</a>." |
Dies ist ein Hyperlink. |
Zeit | "This is a time format: <time>2023-02-16 15:00</time>." |
Das Zeitformat lautet: . |
Zeilenvorschub | „"This is the first line. <br> This is a new line. “ |
Das ist die erste Zeile. Das ist eine neue Zeile. |