Add-on-Aktionen

Add-on-Aktionen bieten interaktives Verhalten für Widgets. Mit einer Aktion definieren Sie, was passiert, wenn der Nutzer ein Widget auswählt oder aktualisiert.

In den meisten Fällen können Sie Add-on-Aktionen mit Action-Objekten definieren, die vom Apps Script-Kartendienst bereitgestellt werden. Jeder Action ist einer Callback-Funktion zugeordnet, wenn Sie diese erstellen. Sie implementieren die Callback-Funktion, um die gewünschten Schritte auszuführen, wenn der Nutzer mit dem Widget interagiert. Außerdem müssen Sie Action mit einer geeigneten Widget-Handler-Funktion mit dem Widget verknüpfen. Diese definiert, welche Art von Interaktion den Action-Callback auslöst.

Konfigurieren Sie ein Widget mit einer Action. Gehen Sie dabei so vor:

  1. Erstellen Sie das Objekt Action und geben Sie die Callback-Funktion an, die es zusammen mit allen erforderlichen Parametern ausführen soll.
  2. Rufen Sie mithilfe des Objekts Action die entsprechende Widget-Handler-Funktion im Widget auf.
  3. Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten festzulegen.

Widget-Handler-Funktionen

Wenn Sie ein Widget mit einem bestimmten Action oder einem anderen Verhalten verknüpfen möchten, verwenden Sie eine Widget-Handler-Funktion. Die Handler-Funktion bestimmt, welche Art von Interaktion (z. B. Klicken auf das Widget oder Bearbeiten eines Textfelds) das Verhalten der Aktion auslöst. Die Handler-Funktion definiert auch, welche Schritte die UI nach Abschluss der Aktion ausführt.

In der folgenden Tabelle sind die verschiedenen Handler-Typen für Widgets und die zugehörigen Widgets aufgeführt:

Handler-Funktion Aktion auslösen Anwendbare Widgets Beschreibung
setOnChangeAction() Der Widgetwert ändert sich DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Legt eine Action fest, die eine Apps Script-Funktion ausführt, wenn das Widget den Fokus verliert, z. B. wenn der Nutzer Text in eine Eingabe eingibt und die Eingabetaste drückt. Der Handler übergibt automatisch ein Ereignisobjekt an die aufgerufene Funktion. In dieses Ereignisobjekt können Sie bei Bedarf zusätzliche Parameterinformationen einfügen.
setOnClickAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Legt eine Action fest, die eine Apps Script-Funktion ausführt, wenn der Nutzer auf das Widget klickt. Der Handler übergibt automatisch ein Ereignisobjekt an die aufgerufene Funktion. Sie können in dieses Ereignisobjekt optionale Parameterinformationen einfügen.
setComposeAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Gmail-spezifisch: Legt einen Action fest, mit dem ein E-Mail-Entwurf erstellt und anschließend dem Nutzer in einem Gmail-Fenster zum Schreiben einer Benutzeroberfläche angezeigt wird. Sie können den Entwurf als neue Nachricht oder als Antwort auf die geöffnete Nachricht in Gmail erstellen. Wenn der Handler die Callback-Funktion zur Entwurfserstellung aufruft, übergibt er ein Ereignisobjekt an die Callback-Funktion. Weitere Informationen finden Sie unter E-Mail-Entwürfe erstellen.
setOnClickOpenLinkAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Legt ein Action fest, um eine URL zu öffnen, wenn der Nutzer auf das Widget klickt. Verwende diesen Handler, wenn du die URL erstellen musst oder andere Aktionen vor dem Öffnen des Links erfolgen müssen. Andernfalls ist die Verwendung von setOpenLink() normalerweise einfacher. Sie können die URL nur in einem neuen Fenster öffnen. Wenn das Add-on geschlossen ist, kann die UI dazu führen, dass es neu geladen wird.
setOpenLink() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton 		Öffnet direkt eine URL, wenn der Nutzer auf das Widget klickt. Verwende diesen Handler, wenn du die URL kennst und sie nur öffnen musst. Verwende andernfalls setOnClickOpenLinkAction(). Sie können die URL in einem neuen Fenster oder in einem Overlay öffnen. Wenn sie geschlossen ist, kann die Benutzeroberfläche das Add-on neu laden.
setSuggestionsAction() Der Nutzer gibt Text in eine Eingabe ein TextInput Legt eine Action fest, die eine Apps Script-Funktion ausführt, wenn der Nutzer Text in ein Texteingabe-Widget eingibt. Der Handler übergibt automatisch ein Ereignisobjekt an die aufgerufene Funktion. Weitere Informationen finden Sie unter Vorschläge für die automatische Vervollständigung für Texteingaben.

Callback-Funktionen

Callback-Funktionen werden ausgeführt, wenn ein Action ausgelöst wird. Da Callback-Funktionen Apps Script-Funktionen sind, können sie fast alle anderen Skriptfunktionen ausführen.

Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Arten von Antworten geben zusätzliche Vorgänge an, die nach Abschluss des Callbacks ausgeführt werden müssen, z. B. das Anzeigen einer neuen Karte oder das Einblenden von Vorschlägen zur automatischen Vervollständigung. Wenn die Callback-Funktion ein bestimmtes Antwortobjekt zurückgeben muss, verwenden Sie eine Builder-Klasse im Kartendienst, um das Objekt zu erstellen.

Die folgende Tabelle zeigt, wann Callback-Funktionen für bestimmte Aktionen ein bestimmtes Antwortobjekt zurückgeben müssen. Diese Aktionen sind unabhängig von der spezifischen Hostanwendung, die das Add-on erweitert:

Aktion versucht Callback-Funktion sollte zurückgegeben werden
Zwischen Karten navigieren ActionResponse
Notification anzeigen ActionResponse
Link mit setOnClickOpenLinkAction() öffnen ActionResponse
Vorschläge für die automatische Vervollständigung anzeigen SuggestionResponse
Verwenden Sie eine universelle Aktion. UniversalActionResponse
Weitere Aktionen Nothing

Zusätzlich zu diesen Aktionen hat jede Hostanwendung eigene Aktionen, die nur auf diesem Host ausgeführt werden können. Weitere Informationen finden Sie in den folgenden Leitfäden:

Aktionsereignisobjekte

Wenn das Add-on ein Action auslöst, wird automatisch ein JSON-Ereignisobjekt erstellt und als Argument an die Action-Callback-Funktion übergeben. Dieses Ereignisobjekt enthält Informationen zum aktuellen clientseitigen Kontext des Nutzers, z. B. die aktuellen Werte aller interaktiven Widgets auf der angezeigten Karte.

Aktionsereignisobjekte haben eine bestimmte JSON-Struktur, in der die darin enthaltenen Informationen organisiert sind. Die gleiche Struktur wird verwendet, wenn ein Startseitentrigger zum Erstellen einer Startseite oder ein Kontexttrigger zum Aktualisieren der Add-on-Anzeige ausgelöst wird.

Eine vollständige Erläuterung der Struktur von Ereignisobjekten finden Sie unter Ereignisobjekte.