Add-on-Aktionen sorgen für ein interaktives Verhalten von Widgets. Wenn Sie eine Aktion erstellen, legen Sie fest, 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.
Jedem Action wird beim Erstellen eine Callback-Funktion zugewiesen. Sie implementieren die Rückruffunktion, um die gewünschten Schritte auszuführen, wenn der Nutzer mit dem Widget interagiert. Außerdem musst du Action über eine geeignete Widget-Handlerfunktion mit dem Widget verknüpfen. Diese Funktion definiert, welche Art von Interaktion den Callback Action auslöst.
So konfigurieren Sie ein Widget mit einem Action:
- Erstelle das
Action-Objekt und gib die Callback-Funktion an, die ausgeführt werden soll, sowie alle erforderlichen Parameter. - Rufe die entsprechende Widget-Handlerfunktion mit dem
Action-Objekt auf dem Widget auf. - Implementieren Sie die Rückruffunktion, um das erforderliche Verhalten zu aktivieren.
Widget-Handler-Funktionen
Wenn Sie ein Widget mit einem bestimmten Action oder einem anderen Verhalten verknüpfen möchten, verwenden Sie eine Widget-Handlerfunktion. Die Handlerfunktion bestimmt, welche Art von Interaktion (z. B. Klicken auf das Widget oder Bearbeiten eines Textfelds) das Aktionsverhalten auslöst. Die Handlerfunktion definiert auch, welche Schritte die Benutzeroberfläche nach Abschluss der Aktion ausführt, falls zutreffend.
In der folgenden Tabelle sind die verschiedenen Handlertypen für Widgets und die zugehörigen Widgets aufgeführt:
| Handlerfunktion | Trigger-Aktion | Anwendbare Widgets | Beschreibung |
|---|---|---|---|
setOnChangeAction() |
Der Widget-Wert ändert sich |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Hiermit wird ein Action festgelegt, der eine Apps Script-Funktion ausführt, wenn der Fokus des Widgets 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.
Sie können in dieses Ereignisobjekt bei Bedarf zusätzliche Parameterinformationen einfügen. |
setOnClickAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Hier wird eine Action festgelegt, 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. |
CardActionImageImageButtonDecoratedTextTextButton
|
Gmail-spezifisch Legt eine Action fest, die einen E-Mail-Entwurf erstellt und dem Nutzer dann in einem Gmail-Bearbeitungsfenster 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 der Callback-Funktion ein Ereignisobjekt.
Weitere Informationen finden Sie unter Entwürfe von Nachrichten verfassen. |
setOnClickOpenLinkAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Hiermit wird eine Action festgelegt, um eine URL zu öffnen, wenn der Nutzer auf das Widget klickt. Verwenden Sie diesen Handler, wenn die URL erstellt werden muss 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 Add-on geschlossen ist, können Sie es über die Benutzeroberfläche neu laden. |
setOpenLink() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Ö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, können Sie es über die Benutzeroberfläche neu laden. |
setSuggestionsAction() |
Der Nutzer gibt Text in ein Eingabefeld ein. |
TextInput
|
Hiermit wird eine Action festgelegt, 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 Automatische Vervollständigung für Texteingaben. |
Callback-Funktionen
Callback-Funktionen werden ausgeführt, wenn ein Action-Trigger ausgelöst wird. Da Callback-Funktionen Apps Script-Funktionen sind, können Sie mit ihnen fast alles tun, was mit anderen Script-Funktionen möglich ist.
Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Antworttypen geben zusätzliche Vorgänge an, die nach Abschluss der Ausführung des Rückrufs ausgeführt werden müssen, z. B. das Anzeigen einer neuen Karte oder das Präsentieren von Vorschlägen für die automatische Vervollständigung. Wenn deine Rückruffunktion ein bestimmtes Antwortobjekt zurückgeben muss, verwendest du eine Builder-Klasse im Kartendienst, um dieses Objekt zu erstellen.
In der folgenden Tabelle wird angegeben, wann Ihre Callback-Funktionen für bestimmte Aktionen ein bestimmtes Antwortobjekt zurückgeben müssen. Diese Aktionen sind unabhängig von der jeweiligen Hostanwendung, die durch das Add-on erweitert wird:
| Versuchte Aktion | Die Callback-Funktion sollte Folgendes zurückgeben: |
|---|---|
| Zwischen Karten wechseln | ActionResponse |
Notification anzeigen |
ActionResponse |
Link mit setOnClickOpenLinkAction() öffnen |
ActionResponse |
| Automatisch vervollständigte Vorschläge anzeigen | SuggestionResponse |
| Universelle Aktion verwenden | UniversalActionResponse |
| Sonstige Aktionen | Nichts |
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 Ihr Add-on ein Action auslöst, wird in der Benutzeroberfläche 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 enthaltenen Informationen organisiert werden. Diese Struktur wird auch verwendet, wenn ein Startseitentrigger ausgelöst wird, um eine Startseite zu erstellen, oder wenn ein kontextbezogener Trigger ausgelöst wird, um die Add-on-Anzeige zu aktualisieren.
Eine vollständige Erklärung der Struktur von Ereignisobjekten finden Sie unter Ereignisobjekte.