Ein Widget ist ein UI-Element, das eine oder mehrere der folgenden Funktionen bietet:
- Struktur für andere Widgets wie Karten und Bereiche,
- Informationen für den Nutzer wie Text und Bilder oder
- Affordances für Aktionen wie Schaltflächen, Textfelder oder Kästchen.
Die Kartenbereiche werden durch Widgets definiert, die hinzugefügt werden. Die Widgets sehen auf Computern und Mobilgeräten gleich aus und haben dieselben Funktionen. In der Referenzdokumentation werden mehrere Methoden zum Erstellen von Widget-Sets beschrieben.
Widget-Typen
Add-on-Widgets werden in der Regel in drei Gruppen unterteilt: strukturelle Widgets, informative Widgets und Widgets für Nutzerinteraktionen.
Strukturelle Widgets
Strukturelle Widgets bieten Container und Organisation für die anderen Widgets, die in der Benutzeroberfläche verwendet werden.
- Schaltflächensatz: Eine Gruppe von Text- oder Bildschaltflächen, die in einer horizontalen Zeile gruppiert sind.
- Karte: Eine einzelne Kontextkarte mit einem oder mehreren Kartenabschnitten. Sie können festlegen, wie Nutzer zwischen Karten wechseln können, indem Sie die Kartennavigation konfigurieren.
- Kartenheader: Der Header für eine bestimmte Karte. Kartenüberschriften können Titel, Untertitel und ein Bild enthalten. Kartenaktionen und universelle Aktionen werden in der Kartenüberschrift angezeigt, wenn sie vom Add-on verwendet werden.
- Kartenbereich: Eine Gruppe von Widgets, die durch eine horizontale Linie von den anderen Kartenbereichen getrennt ist und optional eine Bereichsüberschrift hat. Jede Karte muss mindestens einen Kartenbereich haben. Sie können einem Kartenbereich keine Karten oder Kartenüberschriften hinzufügen.
Zusätzlich zu diesen grundlegenden strukturellen Widgets können Sie in einem Google Workspace-Add-on mit dem Kartendienst Strukturen erstellen, die die aktuelle Karte überlappen: feste Fußzeilen und Infokarten:
Feste Fußzeile
Sie können unten auf der Karte eine feste Zeile mit Schaltflächen hinzufügen. Diese Zeile bewegt sich nicht und wird nicht mit dem Rest des Karteninhalts gescrollt.
Im folgenden Codeausschnitt wird gezeigt, wie eine Beispiel-feste Fußzeile definiert und einer Karte hinzugefügt wird:
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 werden, z. B. durch das Öffnen einer Gmail-Nachricht, können Sie die neuen kontextbezogenen Inhalte entweder sofort anzeigen (Standardverhalten) oder unten in der Seitenleiste eine PeekCard-Benachrichtigung. Wenn ein Nutzer auf „Zurück“ klickt, um zu Ihrer Startseite zurückzukehren, während ein kontextbezogener Trigger aktiv ist, wird eine Minikarte angezeigt, über die Nutzer die kontextbezogenen Inhalte wiederfinden können.
Wenn Sie eine Vorschaukarte anzeigen lassen möchten, wenn neue kontextbezogene Inhalte verfügbar sind, anstatt die neuen kontextbezogenen Inhalte sofort anzuzeigen, fügen Sie der Klasse CardBuilder die Zeichenfolge .setDisplayStyle(CardService.DisplayStyle.PEEK) hinzu. Eine Vorschaukarte wird nur angezeigt, wenn mit Ihrem kontextbezogenen Trigger ein einzelnes Kartenobjekt zurückgegeben wird. Andernfalls ersetzen die zurückgegebenen Karten sofort die aktuelle Karte.
Wenn Sie den Header der Minikarte anpassen möchten, fügen Sie beim Erstellen der kontextbezogenen Karte die Methode .setPeekCardHeader() mit einem standardmäßigen CardHeader-Objekt hinzu. Standardmäßig enthält die Überschrift einer Peek-Karte nur den Namen Ihres Add-ons.
Der folgende Code basiert auf dem Google Workspace-Add-on „Cats“. Er benachrichtigt Nutzer über neue kontextbezogene Inhalte mit einer Peek-Karte und passt die Überschrift der Peek-Karte so an, dass der Betreff der ausgewählten Gmail-Nachrichten-Konversation angezeigt wird.
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, das durch eine von Ihnen angegebene gehostete und öffentlich zugängliche URL angegeben wird.
- DecoratedText: Ein Textinhaltsstring, den Sie mit anderen Elementen wie Textlabels oben und unten sowie einem Bild oder Symbol kombinieren können. DecoratedText-Widgets können auch ein Schaltflächen- oder ein Schalter-Widget enthalten. Hinzugefügte Schalter können Ein-/Aus-Schaltflächen oder Kästchen sein. Der Inhaltstext des DecoratedText-Widgets kann HTML-Formatierung verwenden. Die oberen und unteren Labels müssen jedoch nur aus Text bestehen.
- Textabsatz: Ein Textabsatz, der in HTML formatierte Elemente enthalten kann.
Widgets für Nutzerinteraktionen
Mithilfe von Widgets für Nutzerinteraktionen kann das Add-on auf Aktionen der Nutzer reagieren. Sie können diese Widgets mit Aktionsantworten konfigurieren, um verschiedene Karten anzuzeigen, URLs zu öffnen, Benachrichtigungen zu senden, E-Mail-Entwürfe zu erstellen oder andere Apps Script-Funktionen auszuführen. Weitere Informationen finden Sie im Leitfaden Interaktive Karten erstellen.
- Kartenaktion: Ein Menüpunkt im Menü der Add-on-Headerleiste. Das Menü der Kopfzeile kann auch Elemente enthalten, die als universelle Aktionen definiert sind und auf jeder Karte angezeigt werden, die vom Add-on definiert wird.
- Datum/Uhrzeit-Auswahl: Widgets, mit denen Nutzer ein Datum, eine Uhrzeit oder beides auswählen können. Weitere Informationen finden Sie unten unter Datums- und Uhrzeitauswahl.
- Bildschaltfläche: Eine Schaltfläche, die ein Bild anstelle von Text verwendet. Sie können eines der vordefinierten Symbole oder ein öffentlich gehostetes Bild verwenden, das durch seine URL gekennzeichnet ist.
- Auswahl: Ein Eingabefeld, das eine Reihe von Optionen darstellt. Auswahleingaben werden als Kästchen, Optionsfelder oder Drop-down-Menüs dargestellt.
- Schalter: Ein Schalter-Widget. Sie können Schalter nur in Verbindung mit einem DecoratedText-Widget verwenden. Standardmäßig werden sie als Ein-/Aus-Schalter angezeigt, Sie können sie aber auch als Kästchen anzeigen lassen.
- Textschaltfläche: Eine Schaltfläche mit einem Textlabel. Sie können eine Hintergrundfarbe für Textschaltflächen festlegen (Standard ist „transparent“). Sie können die Schaltfläche bei Bedarf auch deaktivieren.
- Texteingabe: Ein Texteingabefeld. Das Widget kann einen Titel, einen Hinweis und mehrzeiligen Text enthalten. Das Widget kann Aktionen auslösen, wenn sich der Textwert ändert.
- Raster: Ein mehrspaltiges Layout, das eine Sammlung von Elementen darstellt. Sie können Elemente mit einem Bild, einem Titel, einer Zwischenüberschrift und einer Reihe von Anpassungsoptionen wie Rahmen- und Zuschneidestilen darstellen.
DecoratedText Kästchen
Sie können ein DecoratedText-Widget mit einem Kästchen anstelle einer Schaltfläche oder eines binären Ein-/Aus-Schalters definieren. Wie bei Schaltern ist der Wert des Kästchens im Ereignisobjekt „action“ enthalten, das über die Methode setOnClickAction(action) an das Action übergeben wird, das mit diesem DecoratedText verknüpft ist.
Im folgenden Codeausschnitt wird gezeigt, wie Sie ein Kästchen-DecoratedText-Widget definieren, 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, mit denen Nutzer eine Uhrzeit, ein Datum oder beides auswählen können.
Mit setOnChangeAction() können Sie eine Widget-Handlerfunktion zuweisen, die ausgeführt wird, wenn sich der Wert der Auswahl ändert.
Im folgenden Codeausschnitt wird gezeigt, wie Sie eine Datumsauswahl, eine Uhrzeitauswahl und eine Datums-/Uhrzeitauswahl definieren, 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 eine Handlerfunktion für ein Datum/Uhrzeit-Widget. Dieser Handler formatiert und protokolliert einen String, der die vom Nutzer in einem Widget für die Datumsauswahl mit der ID „myDateTimePickerWidgetID“ ausgewählte Uhrzeit darstellt:
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 zeigt Beispiele für die Benutzeroberfläche der Auswahl auf Computern und Mobilgeräten. Wenn die Datumsauswahl ausgewählt ist, wird eine monatsbasierte Kalenderoberfläche geöffnet, über die der Nutzer schnell ein neues Datum auswählen kann.
Wenn der Nutzer auf einem Desktop-Gerät die Uhrzeitauswahl auswählt, wird ein Drop-down-Menü mit einer Liste von Uhrzeiten in 30-Minuten-Schritten geöffnet, aus der er auswählen kann. Der Nutzer kann auch eine bestimmte Uhrzeit eingeben. Auf Mobilgeräten wird durch Auswahl einer Zeitauswahl die integrierte mobile Uhr geöffnet.
| Computer | Mobilgeräte |
|---|---|
|
|
|
|
Raster
Mit dem Raster-Widget können Sie Elemente in einem mehrspaltigen Layout anzeigen. Jedes Element kann ein Bild, einen Titel und einen Untertitel enthalten. Mithilfe zusätzlicher Konfigurationsoptionen können Sie die Positionierung des Texts im Verhältnis zum Bild in einem Rasterelement festlegen.
Sie können ein Rasterelement mit einer Kennung konfigurieren, die als Parameter an die im Raster definierte Aktion zurückgegeben wird.
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 HTML-Formatierung von Text. Geben Sie beim Festlegen des Textinhalts dieser Widgets einfach die entsprechenden HTML-Tags an.
Die unterstützten Tags und ihre Funktion sind in der folgenden Tabelle aufgeführt:
| Format | Beispiel | Gerendertes Ergebnis |
|---|---|---|
| Fett | "This is <b>bold</b>." |
Dieser Text ist fett. |
| Kursiv | "This is <i>italics</i>." |
Das ist kursiv. |
| Unterstrichen | "This is <u>underline</u>." |
Das ist unterstrichen. |
| Durchgestrichen | "This is <s>strikethrough</s>." |
Dies ist |
| Schriftfarbe | "This is <font color=\"#FF0000\">red font</font>." |
Dies ist eine rote 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 ist ein Zeitformat: . |
| Zeilenvorschub | "This is the first line. <br> This is a new line." |
Dies ist die erste Zeile. Dies ist eine neue Zeile. |