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 wird einer Callback-Funktion zugeordnet, wenn Sie sie erstellen. Sie implementieren die Callback-Funktion, um bestimmte Schritte auszuführen, wenn der Nutzer mit dem Widget interagiert. Außerdem musst du die Action mit dem Widget über eine entsprechende Widget-Handler-Funktion verknüpfen, die definiert, welche Art von Interaktion den Action-Callback auslöst.

Konfigurieren Sie ein Widget mit einem Action auf folgende Weise:

  1. Erstellen Sie das Objekt Action und geben Sie die Callback-Funktion an, die ausgeführt werden soll, sowie alle erforderlichen Parameter.
  2. Rufen Sie die entsprechende Widget-Handler-Funktion im Widget mit dem Objekt Action auf.
  3. Implementiere die Callback-Funktion, um das erforderliche Verhalten anzuwenden.

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 Aktionsverhalten 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 der Fokus auf dem Widget verloren geht, 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. Bei Bedarf können Sie in dieses Ereignisobjekt weitere 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: Legt einen Action fest, mit dem ein E-Mail-Entwurf erstellt und dann dem Nutzer in einem Gmail-Fenster zum Schreiben der Benutzeroberfläche präsentiert wird. Du kannst den Entwurf als neue Nachricht oder als Antwort auf die geöffnete Nachricht in Gmail erstellen. Wenn der Handler die Callback-Funktion für die Entwurfserstellung aufruft, übergibt er ein Ereignisobjekt an die Callback-Funktion. Weitere Informationen finden Sie unter Nachrichtenentwü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 oder andere Aktionen ausführen müssen, bevor der Link geöffnet wird. Andernfalls ist es normalerweise einfacher, setOpenLink() zu verwenden. Sie können die URL nur in einem neuen Fenster öffnen. Wenn dies geschlossen ist, können Sie dafür sorgen, dass die Benutzeroberfläche das Add-on neu lädt.
setOpenLink() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Öffnet eine URL direkt, 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, können Sie dafür sorgen, dass die Benutzeroberfläche das Add-on neu lädt.
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 findest du 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 Funktionen ausführen, die auch andere Skriptfunktionen bieten können.

Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Arten von Antworten geben zusätzliche Vorgänge an, die nach der Ausführung 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 Ihre Callback-Funktion ein bestimmtes Antwortobjekt zurückgeben muss, verwenden Sie zum Erstellen dieses Objekts eine Builder-Klasse im Kartendienst.

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

Aktion versucht Callback-Funktion sollte zurückgegeben werden
Zwischen Karten wechseln 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
Andere Aktionen Nichts

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

Aktionsereignisobjekte

Wenn Ihr Add-on ein Action auslöst, erstellt die UI automatisch ein JSON-Ereignisobjekt und übergibt es als Argument an die Callback-Funktion Action. 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 enthaltenen Informationen organisiert sind. Die gleiche Struktur wird verwendet, wenn ein Startseiten-Trigger ausgelöst wird, um eine Startseite zu erstellen, oder wenn ein Kontext-Trigger ausgelöst wird, um die Add-on-Anzeige zu aktualisieren.

Eine vollständige Erläuterung der Ereignisobjektstruktur finden Sie unter Ereignisobjekte.