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
:
- Erstellen Sie das Objekt
Action
und geben Sie dabei die Callback-Funktion an, die zusammen mit allen erforderlichen Parametern ausgeführt werden soll. - Rufen Sie mithilfe des Objekts
Action
die entsprechende Widget-Handler-Funktion für das Widget auf. - 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.