Tworzenie interaktywnych kart

Większość dodatków oprócz wyświetlania danych wymaga od użytkownika wprowadzenia informacji. Podczas tworzenia dodatku opartego na kartach możesz używać interaktywnych widżetów, takich jak przyciski, elementy menu paska narzędzi czy pola wyboru, aby prosić użytkownika o dane potrzebne dodatkowi lub udostępniać inne elementy sterujące interakcji.

Dodawanie działań do widżetów

Większość widżetów możesz uczynić interaktywnymi, łącząc je z określonymi działaniami i wdrażając wymagane zachowanie w funkcji wywołania zwrotnego. Szczegółowe informacje znajdziesz w sekcji działań dodatkowych.

W większości przypadków możesz skonfigurować widżet tak, aby po wybraniu lub zaktualizowaniu wykonywał określone działanie, korzystając z tej ogólnej procedury:

  1. Utwórz obiekt Action, określając funkcję wywołania zwrotnego, która ma zostać wykonana, oraz wszystkie wymagane parametry.
  2. Połącz widżet z Action, wywołując odpowiednią funkcję obsługi widżetu.
  3. Zaimplementuj funkcję wywołania zwrotnego, aby wdrożyć wymagane działanie.

Przykład

W tym przykładzie ustawiamy przycisk, który po kliknięciu wyświetla powiadomienie dla użytkownika. Kliknięcie wywołuje funkcję wywołania zwrotnego notifyUser() z argumentem, który określa tekst powiadomienia. Zwrócenie utworzonego elementu ActionResponse spowoduje wyświetlenie powiadomienia.

  /**
   * 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!
  }

Projektowanie skutecznych interakcji

Podczas projektowania kart interaktywnych pamiętaj o tych kwestiach:

  • Widżety interaktywne zwykle wymagają co najmniej jednej metody obsługi, aby zdefiniować swoje działanie.

  • Użyj funkcji obsługi widżetu setOpenLink(), gdy masz adres URL i chcesz go tylko otworzyć na karcie. Pozwala to uniknąć konieczności definiowania obiektu Action i funkcji wywołania zwrotnego. Jeśli musisz najpierw utworzyć adres URL lub wykonać inne dodatkowe czynności przed otwarciem adresu URL, zdefiniuj Action i użyj setOnClickOpenLinkAction().

  • Gdy używasz funkcji obsługi widżetów setOpenLink() lub setOnClickOpenLinkAction(), musisz podać obiekt OpenLink, aby określić, który URL ma zostać otwarty. Możesz też użyć tego obiektu, aby określić zachowanie otwierania i zamykania za pomocą wyliczeń OpenAs i OnClose.

  • Więcej niż 1 widżet może używać tego samego obiektu Action. Jeśli jednak chcesz przekazać do funkcji wywołania zwrotnego inne parametry, musisz zdefiniować inne obiekty Action.

  • Nie komplikuj funkcji wywołania zwrotnego. Aby dodatki działały sprawnie, usługa karty ogranicza czas wykonywania funkcji zwrotnych do maksymalnie 30 sekund. Jeśli wykonanie trwa dłużej, interfejs dodatku może nie zaktualizować prawidłowo wyświetlania karty w odpowiedzi na Action .

  • Jeśli stan danych na backendzie innej firmy zmieni się w wyniku interakcji użytkownika z interfejsem dodatku, zalecamy, aby dodatek ustawił bit „state changed” na true, aby wyczyścić istniejącą pamięć podręczną po stronie klienta. Więcej informacji znajdziesz w opisie metody ActionResponseBuilder.setStateChanged().