Bei den meisten Add-ons müssen Nutzer nicht nur Daten eingeben, sondern auch Informationen. Wenn Sie ein kartenbasiertes Add-on erstellen, können Sie den Nutzer mit interaktiven Widgets wie Schaltflächen, Menüelementen in Symbolleisten oder Kästchen nach Daten fragen, die Ihr Add-on benötigt, oder andere Interaktionssteuerungen bereitstellen.
Aktionen zu Widgets hinzufügen
Zum größten Teil machen Sie Widgets interaktiv, indem Sie sie mit bestimmten Aktionen verknüpfen und das erforderliche Verhalten in einer Callback-Funktion implementieren. Weitere Informationen finden Sie unter Add-on-Aktionen.
In den meisten Fällen können Sie so ein Widget so konfigurieren, dass es bei Auswahl oder Aktualisierung eine bestimmte Aktion ausführt:
- Erstellen Sie ein
Action
-Objekt und geben Sie dabei die auszuführende Callback-Funktion sowie alle erforderlichen Parameter an. - Verknüpfen Sie das Widget mit dem
Action
, indem Sie die entsprechende Widget-Handler-Funktion aufrufen. - Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten zu implementieren.
Beispiel
Im folgenden Beispiel wird eine Schaltfläche eingerichtet, mit der eine Nutzerbenachrichtigung angezeigt wird, nachdem ein Nutzer darauf geklickt hat. Der Klick löst die Callback-Funktion notifyUser()
mit einem Argument aus, das den Benachrichtigungstext angibt. Die Rückgabe eines erstellten ActionResponse
führt zu einer angezeigten Benachrichtigung.
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification())
.setText(notificationText)
.build(); // Don't forget to build the response!
}
Effektive Interaktionen entwerfen
Beim Entwerfen interaktiver Karten sollten Sie Folgendes beachten:
Interaktive Widgets benötigen in der Regel mindestens eine Handler-Methode, um ihr Verhalten zu definieren.
Verwenden Sie die Funktion des Widget-Handlers
setOpenLink()
, wenn Sie eine URL haben und sie einfach in einem Tab öffnen möchten. Dadurch müssen keinAction
-Objekt und keine Callback-Funktion definiert werden. Wenn Sie die URL zuerst erstellen müssen oder vor dem Öffnen der URL weitere Schritte ausführen müssen, definieren Sie einAction
und verwenden Sie stattdessensetOnClickOpenLinkAction()
.Wenn Sie die Widget-Handler-Funktionen
setOpenLink()
odersetOnClickOpenLinkAction()
verwenden, müssen Sie einOpenLink
-Objekt angeben, um festzulegen, welche URL geöffnet werden soll. Sie können dieses Objekt auch verwenden, um das Öffnungs- und Schließverhalten mithilfe der EnumsOpenAs
undOnClose
festzulegen.Es ist möglich, dass mehrere Widgets dasselbe
Action
-Objekt verwenden. Sie müssen jedoch verschiedeneAction
-Objekte definieren, wenn Sie der Callback-Funktion verschiedene Parameter zur Verfügung stellen möchten.Halten Sie Ihre Callback-Funktionen einfach. Damit die Add-ons responsiv bleiben, beschränkt der Kartendienst Callback-Funktionen auf eine Ausführungszeit von maximal 30 Sekunden. Wenn die Ausführung länger dauert, wird die Karte der Add-on-UI möglicherweise als Reaktion auf
Action
nicht korrekt aktualisiert .Wenn sich der Datenstatus im Back-End eines Drittanbieters aufgrund einer Nutzerinteraktion mit Ihrer Add-on-UI ändert, sollte das Add-on das Bit „Status geändert“ auf
true
setzen, damit vorhandener clientseitiger Cache geleert wird. Weitere Informationen finden Sie in der Beschreibung der MethodeActionResponseBuilder.setStateChanged()
.