Tworzenie interaktywnych kart

Większość dodatków, oprócz prezentowania danych, wymaga od użytkownika wprowadzenia informacji. Gdy tworzysz dodatek oparty na kartach, możesz użyć interaktywnych widżetów, takich jak przyciski, pozycje menu na pasku narzędzi lub pola wyboru, aby poprosić użytkownika o dane potrzebne mu lub udostępnić inne opcje interakcji.

Dodawanie działań do widżetów

Aby widżety były interaktywne, najczęściej wystarczy połączyć je z konkretnymi działaniami i zaimplementować wymagane działanie w funkcji wywołania zwrotnego. Szczegóły znajdziesz w sekcji Dodatki.

W większości przypadków możesz wykonać tę ogólną procedurę, aby skonfigurować widżet do 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 wywołać wymagane działanie.

Przykład

Ten przykład pokazuje ustawienie przycisku, który po kliknięciu wyświetla powiadomienie użytkownika. Kliknięcie aktywuje funkcję wywołania zwrotnego notifyUser() z argumentem określającym tekst powiadomienia. Zwrócenie kompilacji ActionResponse powoduje wyświetlenie wyświetlonego 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ć działanie.

• Jeśli masz URL i chcesz otworzyć go w karcie, użyj funkcji obsługi widżetów setOpenLink(). Dzięki temu nie trzeba definiować obiektu Action ani funkcji wywołania zwrotnego. Jeśli najpierw musisz utworzyć adres URL lub wykonać inne czynności przed otwarciem adresu URL, zdefiniuj Action i zamiast tego użyj setOnClickOpenLinkAction().

• Jeśli korzystasz z funkcji obsługi widżetów setOpenLink() lub setOnClickOpenLinkAction(), musisz podać obiekt OpenLink, aby określić adres URL, który chcesz otworzyć. Za pomocą tego obiektu możesz też określić zachowanie przy otwieraniu i zamykaniu za pomocą wyliczenia OpenAs i OnClose.

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

• Funkcje wywołania zwrotnego powinny być proste. Aby dodatki były elastyczne, usługa karty ogranicza funkcje wywołań zwrotnych do maksymalnie 30 sekund czasu wykonywania. Jeśli potrwa to dłużej, interfejs użytkownika dodatku może nie zaktualizować prawidłowo wyświetlania karty w odpowiedzi na żądanie Action .

• Jeśli stan danych w backendzie innej firmy zmieni się w wyniku interakcji użytkownika z interfejsem dodatku, zalecamy ustawienie tego parametru na true w celu wyczyszczenia całej pamięci podręcznej po stronie klienta. Więcej informacji znajdziesz w opisie metody ActionResponseBuilder.setStateChanged().