Add-on-Aktionen bieten ein interaktives Verhalten für Widgets. Durch das Erstellen einer Aktion 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 Apps Script-Kartendienst bereitgestellt werden.
Jedes Action wird beim Erstellen einer Callback-Funktion zugeordnet. Sie implementieren die Callback-Funktion, um die gewünschten Schritte auszuführen, wenn der Nutzer mit dem Widget interagiert. Außerdem müssen Sie das Action mithilfe einer geeigneten Widget-Handler-Funktion mit dem Widget verknüpfen. Diese definiert, welche Art von Interaktion den Action-Callback auslöst.
So konfigurieren Sie ein Widget mit einem Action:
- Erstellen Sie das Objekt
Actionund geben Sie dabei die Callback-Funktion an, die zusammen mit allen erforderlichen Parametern ausgeführt werden soll. - Rufen Sie mit dem Objekt
Actiondie entsprechende Widget-Handler-Funktion für das Widget auf. - Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten auszuführen.
Widget-Handler-Funktionen
Wenn Sie ein Widget mit einer 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. Mit der Handler-Funktion wird auch definiert, welche Schritte die UI nach Abschluss der Aktion gegebenenfalls unternimmt.
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 | Entsprechende Widgets | Beschreibung |
|---|---|---|---|
setOnChangeAction() |
Der Widget-Wert ändert sich |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Legt ein Action fest, das eine Apps Script-Funktion ausführt, wenn das Widget den Fokus verliert, 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.
Bei Bedarf können Sie zusätzliche Parameterinformationen in dieses Ereignisobjekt einfügen. |
setOnClickAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Legt einen Action fest, der 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 optionale Parameterinformationen in dieses Ereignisobjekt einfügen. |
setComposeAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Nur für Gmail. Legt einen Action fest, der einen E-Mail-Entwurf erstellt und dem Nutzer dann im Editorfenster der Gmail-Benutzeroberfläche 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 Nachrichtenentwürfe schreiben. |
setOnClickOpenLinkAction() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Legt fest, dass ein Action 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 normalerweise einfacher, setOpenLink() zu verwenden.
Sie können die URL nur in einem neuen Fenster öffnen. Wenn das Add-on geschlossen ist, kann es passieren, dass es von der UI neu geladen wird. |
setOpenLink() |
Der Nutzer klickt auf das Widget. |
CardActionImageImageButtonDecoratedTextTextButton
|
Öffnet eine URL direkt, 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 wird, kann dies dazu führen, dass die UI neu geladen wird. |
setSuggestionsAction() |
Die Nutzenden geben Text in eine Eingabe 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-Trigger ausgelöst wird. Da es sich bei der Callback-Funktion um Apps Script-Funktionen handelt, können sie fast alles tun, was jede andere Skriptfunktion kann.
Eine Callback-Funktion gibt manchmal ein bestimmtes Antwortobjekt zurück. Diese Arten von Antworten kennzeichnen zusätzliche Vorgänge, die ausgeführt werden müssen, nachdem die Ausführung des Callbacks abgeschlossen ist, z. B. das Anzeigen einer neuen Karte oder das Anzeigen von Vorschlägen zur automatischen Vervollständigung. Wenn die Callback-Funktion ein bestimmtes Antwortobjekt zurückgeben muss, verwenden Sie im Card-Dienst eine Builder-Klasse, um dieses Objekt zu erstellen.
Die folgende Tabelle zeigt, 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 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 | Nothing |
Zusätzlich zu diesen Aktionen hat jede Hostanwendung ihre eigenen Aktionen, die nur auf diesem Host ausgeführt werden können. Weitere Informationen findest du in den folgenden Anleitungen:
Aktionsereignisobjekte
Wenn das 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 spezielle JSON-Struktur, in der die darin enthaltenen Informationen organisiert sind. Dieselbe Struktur wird verwendet, wenn ein Startseiten-Trigger ausgelöst wird, um eine Startseite zu erstellen, oder wenn ein kontextueller Trigger ausgelöst wird, um die Add-on-Anzeige zu aktualisieren.
Eine ausführliche Erläuterung der Struktur von Ereignisobjekten finden Sie unter Ereignisobjekte.