Add-on-Aktionen

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:

  1. Erstellen Sie das Action-Objekt. die Callback-Funktion angibt, zusammen mit den erforderlichen Parametern ausgeführt werden.
  2. Rufen Sie die entsprechende Widget-Handler-Funktion auf. im Widget mithilfe der Action -Objekt enthält.
  3. 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 DatePicker
DateTimePicker
SelectionInput
Switch
TextInput 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. CardAction
Image
ImageButton
DecoratedText
TextButton
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. CardAction
Image
ImageButton
DecoratedText
TextButton
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. CardAction
Image
ImageButton
DecoratedText
TextButton
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. CardAction
Image
ImageButton
DecoratedText
TextButton
Ö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.