Add-on-Aktionen

Add-on-Aktionen bieten interaktives Verhalten für Widgets. Wenn Sie eine Aktion erstellen, 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 Google Apps Script-Kartendienst bereitgestellt werden. Jede Action ist mit einer Callback-Funktion verknüpft, wenn Sie sie erstellen. Sie implementieren die Callback-Funktion, um ausgewählte Schritte auszuführen, wenn der Nutzer mit dem Widget interagiert. Sie müssen die Action auch mit einem entsprechenden Widget-Handler verknüpfen, der definiert, welche Art von Interaktion die Action-Callback-Funktion auslöst.

So konfigurieren Sie ein Widget mit einer Action:

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

Verwechseln Sie Action Objekte nicht mit CardAction Objekten. CardAction Objekte sind Menüelemente im Kartenheader, während Action Objekte Antworten auf Nutzerinteraktionen mit der Benutzeroberfläche definieren.

Widget-Handler-Funktionen

Verwenden Sie eine Widget-Handler-Funktion, um ein Widget mit einem Action oder einem anderen Verhalten zu verknüpfen. 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 Benutzeroberfläche nach Abschluss der Aktion ausführt.

In der folgenden Tabelle sind die verschiedenen Handler-Typen für Widgets und die Widgets aufgeführt, mit denen sie verwendet werden:

Handler-Funktion Löst Aktion aus Anwendbare Widgets Beschreibung
setOnChangeAction Der Widget-Wert ändert sich DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Legt eine Action fest, die eine Apps Script-Funktion ausführt, wenn der Fokus vom Widget verloren geht, z. B. wenn der Nutzer Text in ein Eingabefeld eingibt und die Eingabetaste drückt. Der Handler übergibt automatisch ein Ereignisobjekt an die aufgerufene Funktion. Optional können Sie zusätzliche Parameterinformationen in dieses Ereignisobjekt 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. Optional können Sie Parameterinformationen in dieses Ereignisobjekt 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 ihn dem Nutzer dann in einem Gmail-Fenster zum Verfassen von Nachrichten präsentiert. 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 zum Erstellen des Entwurfs 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 eine Action fest, die eine URL öffnet, wenn der Nutzer auf das Widget klickt. Verwenden Sie diesen Handler, wenn Sie die URL erstellen müssen oder andere Aktionen ausgeführt werden müssen, bevor der Link geöffnet wird. Andernfalls ist es in der Regel einfacher, setOpenLink zu verwenden. Sie können die URL nur in einem neuen Fenster öffnen. Wenn das Fenster geschlossen wird, können Sie die Benutzeroberfläche so konfigurieren, dass das Add-on 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. 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 Fenster geschlossen wird, können Sie die Benutzeroberfläche so konfigurieren, dass das Add-on neu geladen wird.
setSuggestionsAction Der Nutzer gibt Text in ein Eingabefeld 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 Automatisch vervollständigte Vorschläge 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 alles tun, was jede andere Skriptfunktion tun kann.

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

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:

Versuchte Aktion Callback-Funktion sollte zurückgeben
Navigieren ActionResponse
Eine Notification anzeigen ActionResponse
Einen Link mit setOnClickOpenLinkAction öffnen ActionResponse
Automatisch vervollständigte Vorschläge anzeigen SuggestionResponse
Eine universelle Aktion verwenden UniversalActionResponse
Weitere Aktionen Nichts

Aktionen für Google Workspace-Hostanwendungen

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

Wenn Sie die Antwort-Builder-Klassen verwenden, rufen Sie die Methode build auf, um die Antwortobjekte zu erstellen. Andernfalls wird ein Fehler ausgegeben.

Universelle Aktionen werden im Projektmanifest definiert und benötigen keine Action-Objekte. Ihre Callback-Funktionen müssen jedoch eine UniversalActionResponse zurückgeben.

Aktionsereignisobjekte

Wenn Ihr Add-on eine Action auslöst, erstellt die Benutzeroberfläche automatisch ein JSON-Ereignisobjekt und übergibt es als Argument an die Action-Callback-Funktion. 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, die die darin enthaltenen Informationen organisiert. Dieselbe Struktur wird verwendet, wenn ein Homepage-Trigger ausgelöst wird, um eine Homepage zu erstellen, oder wenn ein kontextbezogener Trigger ausgelöst wird, um die Add-on-Anzeige zu aktualisieren.

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

Gmail-Add-ons verwendeten eine vereinfachte Version dieser Ereignisobjektstruktur, die jetzt veraltet ist. Aus Gründen der Abwärtskompatibilität sind alle ursprünglichen Felder des Ereignisobjekts von Gmail-Add-ons weiterhin in der neuen Ereignisobjektstruktur enthalten (siehe Ereignisobjektstruktur). Dieselben Informationen werden jedoch in den commonEventObject und Gmail-Ereignis-Objekt Unterstrukturen wiedergegeben. Wenn Sie ein Gmail-Add-on zu einem Google Workspace-Add-on aktualisieren, passen Sie Ihren Code an, um die aktualisierten Felder des Ereignisobjekts zu verwenden. Die ursprünglichen Felder des Ereignisobjekts von Gmail werden schließlich entfernt.