Interaktive Karten erstellen

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

Widgets Aktionen hinzufügen

In den meisten Fällen 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 diesem allgemeinen Verfahren folgen, um ein Widget so zu konfigurieren, dass es bei Auswahl oder Aktualisierung eine bestimmte Aktion ausführt:

  1. Erstellen Sie ein Action-Objekt und geben Sie die Callback-Funktion an, die ausgeführt werden soll, sowie alle erforderlichen Parameter.
  2. Verknüpfen Sie das Widget mit Action, indem Sie die entsprechende Widget-Handler-Funktion aufrufen.
  3. Implementieren Sie die Callback-Funktion, um das erforderliche Verhalten zu erzielen.

Beispiel

Im folgenden Beispiel wird eine Schaltfläche festgelegt, die nach dem Klicken eine Nutzerbenachrichtigung anzeigt. Der Klick löst die Callback-Funktion notifyUser() mit einem Argument aus, das den Benachrichtigungstext angibt. Wenn Sie ein Built-in-Gerät ActionResponse zurückgeben, 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 gestalten

Beachten Sie beim Entwerfen interaktiver Karten Folgendes:

  • Für interaktive Widgets ist in der Regel mindestens eine Handler-Methode erforderlich, um ihr Verhalten zu definieren.

  • Verwenden Sie die setOpenLink()-Widget-Handler-Funktion, wenn Sie eine URL haben und sie nur auf einem Tab öffnen möchten. So müssen Sie kein Action-Objekt und keine Rückruffunktion definieren. Wenn Sie die URL zuerst erstellen oder andere zusätzliche Schritte ausführen müssen, bevor Sie die URL öffnen, 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 mit den 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 unterschiedliche Parameter übergeben möchten.

  • Halten Sie Ihre Callback-Funktionen einfach. Damit Add-ons reaktionsschnell bleiben, begrenzt der Kartendienst die Ausführungszeit von Callback-Funktionen auf maximal 30 Sekunden. Wenn die Ausführung länger dauert, wird die Kartendarstellung der Add-on-Benutzeroberfläche möglicherweise nicht richtig als Reaktion auf die Action aktualisiert .

  • Wenn sich der Datenstatus in einem Drittanbieter-Backend aufgrund einer Nutzerinteraktion mit der Add-on-Benutzeroberfläche ändert, wird empfohlen, dass das Add-on ein „state changed“-Bit auf true setzt, damit alle vorhandenen clientseitigen Caches geleert werden. Weitere Informationen finden Sie in der Beschreibung der Methode ActionResponseBuilder.setStateChanged().