Add-on-Aktionen

Add-on-Aktionen bieten interaktives Verhalten für Widgets. Durch das Erstellen 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 mithilfe von Action-Objekten definieren, die vom Kartendienst in Apps Script bereitgestellt werden. Jedes Action wird einer Callback-Funktion zugeordnet, wenn Sie es 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 über eine entsprechende Widget-Handler-Funktion mit dem Widget verknüpfen, die definiert, welche Art von Interaktion den Action-Callback auslöst.

So konfigurieren Sie ein Widget mit einem Action:

  1. Erstellen Sie das Objekt Action und geben Sie dabei die Callback-Funktion an, die zusammen mit allen erforderlichen Parametern ausgeführt werden soll.
  2. Rufen Sie mithilfe des Objekts Action die entsprechende Widget-Handler-Funktion für das Widget auf.
  3. Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten zu erreichen.

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 gegebenenfalls nach Abschluss der Aktion ausführt.

In der folgenden Tabelle sind die verschiedenen Handler-Typen für Widgets sowie deren Verwendung aufgeführt:

Handler-Funktion Trigger-Aktion Anwendbare Widgets Beschreibung
setOnChangeAction() Der Widgetwert ändert sich. DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
Legt ein Action fest, das eine Apps Script-Funktion ausführt, wenn das Widget nicht mehr im Fokus ist, z. B. wenn der Nutzer Text in einer Eingabe eingibt und die Eingabetaste drückt. Der Handler übergibt automatisch ein Ereignisobjekt an die aufgerufene Funktion. Bei Bedarf können Sie in diesem Ereignisobjekt zusätzliche Parameterinformationen einfügen.
setOnClickAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Legt ein Action fest, das 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 diesem Ereignisobjekt optionale Parameterinformationen einfügen.
setComposeAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Gmail-spezifisch Legt ein Action fest, das einen E-Mail-Entwurf erstellt und diesen Entwurf dann dem Nutzer in einem Editorfenster in der Gmail-Benutzeroberfläche präsentiert. Sie können den Entwurf als neue Nachricht oder als Antwort auf die in Gmail geöffnete Nachricht 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 verfassen.
setOnClickOpenLinkAction() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Legt ein Action zum Öffnen einer URL fest, wenn der Nutzer auf das Widget klickt. Verwenden Sie diesen Handler, wenn Sie die URL erstellen müssen oder andere Aktionen vor dem Öffnen des Links ausgeführt werden müssen. Andernfalls ist es normalerweise einfacher, setOpenLink() zu verwenden. Sie können die URL nur in einem neuen Fenster öffnen. Wenn das Add-on geschlossen ist, kann es von der UI neu geladen werden.
setOpenLink() Der Nutzer klickt auf das Widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Öffnet direkt eine URL, wenn der Nutzer auf das Widget klickt. Verwenden Sie diesen Handler, wenn Sie die URL kennen und sie nur öffnen müssen. Andernfalls verwenden Sie setOnClickOpenLinkAction(). Sie können die URL in einem neuen Fenster oder in einem Overlay öffnen. Wenn das Add-on geschlossen ist, kann es von der UI neu geladen werden.
setSuggestionsAction() Der Nutzer gibt Text ein. TextInput Legt ein Action fest, das 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 von Texteingaben.

Callback-Funktionen

Callback-Funktionen werden ausgeführt, wenn ein Action ausgelöst wird. Da es sich bei Callback-Funktionen um Apps Script-Funktionen handelt, können Sie damit fast jede beliebige andere Skriptfunktion nutzen.

Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Antworttypen 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 Vorschläge zur automatischen Vervollständigung. Wenn Ihre Callback-Funktion ein bestimmtes Antwortobjekt zurückgeben muss, erstellen Sie das Objekt mit einer Builder-Klasse im Kartendienst.

In der folgenden Tabelle sehen Sie, wann Ihre Callback-Funktionen für bestimmte Aktionen ein bestimmtes Antwortobjekt zurückgeben müssen. Diese Aktionen sind alle unabhängig von der spezifischen Hostanwendung, die das Add-on erweitert:

Aktion versucht Callback-Funktion sollte
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
Sonstige Aktionen Nichts

Zusätzlich zu diesen Aktionen verfügt jede Hostanwendung über ihre eigenen 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 spezifische JSON-Struktur, in der die darin enthaltenen Informationen organisiert werden. Dieselbe Struktur wird verwendet, wenn ein Startseiten-Trigger zum Erstellen einer Startseite oder ein kontextbezogener Trigger zum Aktualisieren der Add-on-Anzeige ausgelöst wird.

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