Add-on-Aktionen bieten interaktive Funktionen für Widgets Durch das Erstellen einer Aktion legen Sie fest, was passiert, wenn Nutzende eine Auswahl oder Aktualisierung treffen ein Widget.
In den meisten Fällen können Sie Add-on-Aktionen mit
Action
Objekte, die vom Apps Script-Kartendienst bereitgestellt werden.
Jedes Action ist verknüpft mit
eine Callback-Funktion hinzu. Sie implementieren die Callback-Funktion.
die gewünschten Schritte auszuführen, wenn Nutzende mit dem Widget interagieren. Außerdem müssen Sie
Action mit dem Widget verknüpfen
Verwenden Sie dazu eine geeignete Widget-Handler-Funktion,
definiert, welche Art von Interaktion
Action-Callback.
Widget mit einem Action konfigurieren
Gehen Sie dabei wie folgt vor:
- Erstellen Sie das
Action-Objekt. die Callback-Funktion angibt, zusammen mit den erforderlichen Parametern ausgeführt werden. - Rufen Sie die entsprechende Widget-Handler-Funktion auf.
im Widget mithilfe der
Action-Objekt enthält. - Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten auszuführen.
Widget-Handler-Funktionen
So verknüpfen Sie ein Widget mit einem bestimmten Action:
oder andere Verhaltensweisen,
Handler-Funktion. Die Handler-Funktion bestimmt, welche Art von Interaktion
(z. B. durch Klicken auf das Widget oder Bearbeiten eines Textfeldes) das Ereignis
handlungsbezogenem Verhalten. Die Handler-Funktion definiert auch,
welche Schritte die Benutzeroberfläche unternimmt,
nach Abschluss der Aktion.
In der folgenden Tabelle sind die verschiedenen Handler-Typen für Widgets aufgeführt und es wird angegeben, Widgets verwendet werden:
| Handler-Funktion | Löst Aktion aus | Entsprechende Widgets | Beschreibung |
|---|---|---|---|
setOnChangeAction() |
Der Widget-Wert ändert sich |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Legt einen Action fest
die eine Apps Script-Funktion ausführt, wenn das Widget den Fokus verliert, z. B.
z. B. wenn der Nutzer Text eingibt und die Eingabetaste drückt. Die
gibt den Handler automatisch eine
Ereignisobjekt für die aufgerufene Funktion.
Sie können zusätzliche Parameterinformationen in dieses Ereignisobjekt einfügen
falls gewünscht. |
setOnClickAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Legt einen Action fest
die eine Apps Script-Funktion ausführt, wenn der Nutzer auf das Widget klickt. Die
gibt den Handler automatisch eine
Ereignisobjekt für die aufgerufene Funktion.
Sie können optionale Parameterinformationen in dieses Ereignisobjekt einfügen. |
setComposeAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Nur für Gmail. Legt eine
Action
mit der ein E-Mail-Entwurf erstellt und den Nutzenden in einem
Gmail-UI zum Schreiben Sie können den Entwurf als neue Nachricht oder als
auf die geöffnete Nachricht in Gmail antworten. Wenn der Handler die Methode
Callback-Funktion erstellt, übergibt sie eine
Ereignisobjekt an die Callback-Funktion übergeben.
Weitere Informationen finden Sie unter
Nachrichtenentwürfe verfassen
. |
setOnClickOpenLinkAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Legt einen Action fest
um eine URL zu öffnen, wenn der Nutzer auf das Widget klickt. Verwenden Sie diesen Handler, wenn Sie
müssen die URL erstellen oder andere Aktionen müssen vor dem Link erfolgen.
öffnet; Andernfalls ist es in der Regel einfacher, setOpenLink() zu verwenden.
Sie können die URL nur in einem neuen Fenster öffnen. Wenn sie geschlossen ist,
UI zum Aktualisieren des Add-ons |
setOpenLink() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Öffnet eine URL direkt, wenn der Nutzer auf das Widget klickt. Verwenden
wenn Sie die URL kennen und sie nur öffnen müssen. Andernfalls verwenden
setOnClickOpenLinkAction()
Sie können die URL in einem neuen Fenster oder in einem Overlay öffnen. Wenn geschlossen,
kann dazu führen, dass das Add-on in der UI neu geladen wird. |
setSuggestionsAction() |
Die Nutzenden geben Text in eine Eingabe ein. |
TextInput
|
Legt einen Action fest
die eine Apps Script-Funktion ausführt, wenn der Nutzer Text in ein
Texteingabe-Widget. Der Handler übergibt automatisch eine
Ereignisobjekt für die aufgerufene Funktion.
Weitere Informationen finden Sie unter
Vorschläge für die automatische Vervollständigung
für Texteingaben. |
Callback-Funktionen
Callback-Funktionen werden ausgeführt, wenn ein Action
Trigger. Da es sich bei den Callback-Funktionen um Apps Script-Funktionen handelt,
fast alles, was jede andere Skriptfunktion kann.
Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Arten von Antworten auf zusätzliche Vorgänge hinweisen, die nach die Ausführung des Callbacks beendet, etwa das Anzeigen einer neuen Karte oder die Präsentation automatisch vervollständigten Vorschlägen. Wenn die Callback-Funktion eine bestimmte Antwortobjekt verwendet, wird eine Builder-Klasse im Kartendienst verwendet. um das Objekt zu erstellen.
Die folgende Tabelle zeigt, wann Ihre Callback-Funktionen ein Antwortobjekt für bestimmte Aktionen. Diese Aktionen sind alle unabhängig von der spezifischen Hostanwendung, die durch das Add-on erweitert wird:
| Aktion versucht | Die Callback-Funktion sollte Folgendes zurückgeben: |
|---|---|
| Zwischen Karten wechseln | ActionResponse |
Notification anzeigen |
ActionResponse |
Link mit setOnClickOpenLinkAction() öffnen |
ActionResponse |
| Vorschläge für die automatische Vervollständigung anzeigen | SuggestionResponse |
| Universelle Aktion verwenden | UniversalActionResponse |
| Sonstige Aktionen | Nichts |
Zusätzlich zu diesen Aktionen verfügt jede Hostanwendung über eigene Aktionen, die nur auf diesem Host ausgeführt werden können. Weitere Informationen finden Sie Anleitungen:
Aktionsereignisobjekte
Wenn Ihr Add-on ein Action auslöst,
Die Benutzeroberfläche erstellt automatisch ein JSON-Ereignisobjekt und übergibt es als
Argument für den Action-Callback
. Dieses Ereignisobjekt enthält Informationen zur aktuellen
clientseitigen Kontext wie die aktuellen Werte aller interaktiven
Widgets auf der angezeigten Karte.
Aktionsereignisobjekte haben eine spezifische JSON-Struktur, die darin enthaltenen Informationen enthalten. Die gleiche Struktur wird verwendet, wenn ein Startseitentrigger wird ausgelöst, um eine Startseite zu erstellen, oder wenn ein kontextbezogener Trigger wird ausgelöst, um die Anzeige des Add-ons zu aktualisieren.
Eine vollständige Übersicht finden Sie unter Ereignisobjekte. Erläuterung der Struktur des Ereignisobjekts.