Interaktive Karten erstellen

Bei den meisten Add-ons muss der Nutzer nicht nur Daten präsentieren, sondern auch Informationen eingeben. Wenn Sie ein kartenbasiertes Add-on erstellen, können Sie interaktive Widgets wie Schaltflächen, Symbolleistenmenüelemente oder Kästchen verwenden, um den Nutzer nach Daten zu fragen, die das Add-on benötigt, oder um andere Interaktionssteuerungen bereitzustellen.

Aktionen zu Widgets hinzufügen

Widgets werden größtenteils interaktiv, indem du sie mit bestimmten Aktionen verknüpfst und das erforderliche Verhalten in einer Callback-Funktion implementierst. Weitere Informationen finden Sie unter Add-on-Aktionen.

In den meisten Fällen können Sie diesem allgemeinen Verfahren folgen, um ein Widget so zu konfigurieren, dass es bei der Auswahl oder Aktualisierung eine bestimmte Aktion ausführt:

1. Erstellen Sie ein Action-Objekt mit der auszuführenden Callback-Funktion und allen erforderlichen Parametern.
2. Verknüpfen Sie das Widget mit Action. Rufen Sie dazu die entsprechende Widget-Handler-Funktion auf.
3. Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten auszuführen.

Beispiel

Im folgenden Beispiel wird eine Schaltfläche festgelegt, über die nach einem Klick eine Nutzerbenachrichtigung angezeigt wird. Der Klick löst die Callback-Funktion notifyUser() mit einem Argument aus, das den Benachrichtigungstext angibt. Bei Rückgabe eines erstellten ActionResponse wird eine Benachrichtigung angezeigt.

  /**
   * 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. Dadurch müssen weder ein Action-Objekt noch eine Callback-Funktion definiert werden. Wenn Sie zuerst die URL erstellen müssen oder vor dem Öffnen der URL andere zusätzliche 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 anzugeben.

• Es ist möglich, dass mehrere Widgets dasselbe Action-Objekt verwenden. Wenn Sie für die Callback-Funktion jedoch unterschiedliche Parameter bereitstellen möchten, müssen Sie verschiedene Action-Objekte definieren.

• Halten Sie Ihre Callback-Funktionen einfach. Damit die Add-ons responsiv bleiben, beschränkt der Kartendienst die Callback-Funktionen auf maximal 30 Sekunden der Ausführungszeit. Wenn die Ausführung länger dauert, wird die Kartendarstellung der Add-on-UI möglicherweise nicht korrekt als Reaktion auf Action aktualisiert .

• Wenn sich der Datenstatus im Back-End eines Drittanbieters als Ergebnis einer Nutzerinteraktion mit der Add-on-UI ändert, sollte für das Add-on das Bit "Status geändert" auf true gesetzt werden, damit der vorhandene clientseitige Cache gelöscht wird. Weitere Informationen finden Sie in der Beschreibung der Methode ActionResponseBuilder.setStateChanged().