Interaktive Karten erstellen

Bei den meisten Add-ons müssen Nutzer neben der Darstellung von Daten auch Informationen eingeben. Wenn Sie ein kartenbasiertes Add-on erstellen, können Sie den Nutzer mithilfe interaktiver Widgets wie Schaltflächen, Symbolleistenmenüelemente oder Kästchen nach Daten fragen, die das 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 ein Widget so konfigurieren, dass bei Auswahl oder Aktualisierung eine bestimmte Aktion ausgeführt wird:

1. Erstellen Sie ein Action-Objekt und geben Sie darin 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 erreichen.

Beispiel

Im folgenden Beispiel wird eine Schaltfläche festgelegt, die eine Nutzerbenachrichtigung anzeigt, nachdem darauf geklickt wurde. 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

Beachten Sie beim Entwerfen interaktiver Karten Folgendes:

• Interaktive Widgets benötigen normalerweise mindestens eine Handler-Methode, um ihr Verhalten zu definieren.

• Verwenden Sie die Widget-Handler-Funktion setOpenLink(), wenn Sie eine URL haben und sie nur in einem Tab öffnen möchten. So müssen Sie kein Action-Objekt und keine Callback-Funktion definieren. Wenn Sie zuerst die URL erstellen 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, begrenzt der Kartendienst Callback-Funktionen auf eine Ausführungszeit von maximal 30 Sekunden. Wenn die Ausführung länger dauert, wird die Kartenanzeige der Add-on-UI möglicherweise als Reaktion auf den Action nicht korrekt aktualisiert .

• Wenn sich der Datenstatus im Back-End eines Drittanbieters infolge einer Nutzerinteraktion mit der 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().