Interaktive Karten erstellen

Bei den meisten Add-ons müssen Nutzer nicht nur Daten ansehen, sondern auch Informationen eingeben. Wenn Sie ein kartenbasiertes Add-on erstellen, können Sie interaktive Widgets wie Schaltflächen, Symbolleistenmenüpunkte oder Kästchen verwenden, um Nutzer um Daten zu bitten, die für Ihr Add-on erforderlich sind, oder andere Interaktionssteuerungen 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 Rückruffunktion implementieren. Weitere Informationen finden Sie unter Add-on-Aktionen.

In den meisten Fällen können Sie ein Widget so konfigurieren, dass eine bestimmte Aktion ausgeführt wird, wenn es ausgewählt oder aktualisiert wird. Gehen Sie dazu so vor:

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

Beispiel

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

Beachten Sie beim Entwerfen interaktiver Karten Folgendes:

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

• Verwenden Sie die Widget-Handler-Funktion setOpenLink(), wenn Sie eine URL haben und sie einfach in 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 die URL geöffnet wird, definieren Sie eine Action und verwenden Sie stattdessen setOnClickOpenLinkAction().

• Wenn Sie die Widget-Handlerfunktionen setOpenLink() oder setOnClickOpenLinkAction() verwenden, müssen Sie ein OpenLink-Objekt angeben, um zu definieren, welche URL geöffnet werden soll. Mit diesem Objekt können Sie auch das Öffnen und Schließen mithilfe der Enumerationen OpenAs und OnClose festlegen.

• Es ist möglich, dass mehrere Widgets dasselbe Action-Objekt verwenden. Sie müssen jedoch unterschiedliche Action-Objekte definieren, wenn Sie der Callback-Funktion unterschiedliche Parameter übergeben möchten.

• Halten Sie Ihre Rückruffunktionen einfach. Damit die Add-ons reaktionsschnell bleiben, begrenzt der Kartendienst die Ausführungszeit von Callback-Funktionen auf maximal 30 Sekunden. Dauert die Ausführung länger, wird die Kartenanzeige in der Add-on-Benutzeroberfläche möglicherweise nicht richtig 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 das Bit „Status geändert“ auf true setzt, damit der vorhandene clientseitige Cache gelöscht wird. Weitere Informationen finden Sie in der Methodenbeschreibung für ActionResponseBuilder.setStateChanged().