Interaktive Karten erstellen

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:

1. Erstellen Sie ein Action-Objekt und geben Sie dabei die auszuführende Callback-Funktion sowie alle erforderlichen Parameter an.
2. Verknüpfen Sie das Widget mit dem Action, indem Sie die entsprechende Widget-Handler-Funktion aufrufen.
3. 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 kein Action-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 ein Action und verwenden Sie stattdessen setOnClickOpenLinkAction().

• Wenn Sie die Widget-Handler-Funktionen setOpenLink() oder setOnClickOpenLinkAction() verwenden, müssen Sie ein OpenLink-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 Enums OpenAs und OnClose festzulegen.

• Es ist möglich, dass mehrere Widgets dasselbe Action-Objekt verwenden. Sie müssen jedoch verschiedene Action-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 Methode ActionResponseBuilder.setStateChanged().