Tworzenie interaktywnych kart

Większość dodatków oprócz prezentowania danych wymaga od użytkownika wprowadzenia informacji. Gdy tworzysz dodatek na podstawie kart, możesz używać interaktywnych widżetów, takich jak przyciski, elementy menu na pasku narzędzi lub pola wyboru, aby prosić użytkownika o podanie danych, których potrzebuje ten dodatek, lub o dostęp do innych elementów sterowania jego interakcjami.

Dodawanie działań do widżetów

Aby widżety stały się interaktywne, można je połączyć z konkretnymi działaniami i zaimplementować wymagane działanie w funkcji wywołania zwrotnego. Szczegóły znajdziesz w artykule o działaniach dodatkowych.

W większości przypadków możesz wykonać tę ogólną procedurę, aby skonfigurować widżet pod kątem wykonywania określonego działania po wybraniu lub aktualizacji:

1. Utwórz obiekt Action, określając funkcję wywołania zwrotnego, która ma zostać wykonana, oraz wszelkie 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 zastosować wymagane działanie.

Przykład

W przykładzie poniżej można skonfigurować przycisk, który po kliknięciu wyświetla powiadomienie użytkownika. Kliknięcie uruchamia funkcję wywołania zwrotnego notifyUser() z argumentem określającym tekst powiadomienia. Zwrócenie kompilacji ActionResponse spowoduje wyświetlenie wyświetlanego 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 1 metody obsługi, aby określić swoje działanie.

• Jeśli masz adres URL i chcesz tylko otworzyć go na karcie, użyj funkcji obsługi widżetu setOpenLink(). Dzięki temu nie musisz definiować obiektu Action i funkcji wywołania zwrotnego. Jeśli przed otwarciem adresu URL musisz utworzyć adres URL lub wykonać inne dodatkowe czynności, określ Action, a zamiast niego użyj setOnClickOpenLinkAction().

• Jeśli korzystasz z funkcji setOpenLink() lub setOnClickOpenLinkAction(), musisz udostępnić obiekt OpenLink wskazujący, który adres URL ma być otwierany. Możesz też użyć tego obiektu do określenia sposobu otwierania i zamykania za pomocą wyliczeń OpenAs i OnClose.

• Tego samego obiektu Action może używać więcej niż 1 widżet. Aby jednak funkcja wywołania zwrotnego mogła mieć różne parametry, musisz zdefiniować inne obiekty Action.

• Funkcje wywołania zwrotnego powinny być proste. Aby dodatki były sprawne, usługa karty ogranicza czas wykonywania funkcji wywołań zwrotnych do maksymalnie 30 sekund. Jeśli wykonanie tego kodu potrwa dłużej, interfejs dodatku może nie zaktualizować wyświetlania karty prawidłowo w odpowiedzi na Action .

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