Tworzenie interaktywnych kart

Większość dodatków oprócz prezentowania danych wymaga od użytkownika podania informacji. Podczas tworzenia dodatku na podstawie kart możesz używać interaktywnych widżetów, takich jak przyciski, elementy menu na pasku narzędzi lub pola wyboru, aby poprosić użytkownika o dane, których potrzebuje Twój dodatek, lub udostępnić inne elementy sterujące interakcją.

Dodawanie działań do widżetów

W większości przypadków możesz uczynić widżety interaktywnymi, łącząc je z określonymi czynnikami i wdrażając wymagane działanie w funkcji wywołania zwrotnego. Szczegółowe informacje znajdziesz w sekcji Działania dodatkowe.

W większości przypadków możesz skonfigurować widżet, aby wykonywał określone działanie po wybraniu lub zaktualizowaniu:

1. Utwórz obiekt Action, podając funkcję wywołania zwrotnego, która ma zostać wykonana, wraz z wymaganymi parametrami.
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 powoduje wywołanie funkcji notifyUser() z argumentem określającym tekst powiadomienia. Zwrot utworzonego elementu ActionResponse powoduje 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:

• Interaktywne widżety wymagają zwykle co najmniej 1 metody obsługi, aby zdefiniować ich działanie.

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

• Jeśli używasz funkcji obsługi widżetu setOpenLink() lub setOnClickOpenLinkAction(), musisz podać obiekt OpenLink, aby określić, który adres URL ma zostać otwarty. Możesz też użyć tego obiektu do określenia zachowania otwierania i zamykania za pomocą enumeracji OpenAs i OnClose.

• W jednym widżecie może być używany ten sam obiekt Action. Jeśli jednak chcesz podać inną funkcję wywołania zwrotnego, musisz zdefiniować inne obiekty Action.

• Funkcje wywołania zwrotnego powinny być proste. Aby zapewnić dodatkom odpowiednią responsywność, usługa kart ogranicza czas wykonywania funkcji wywołania zwrotnego 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 zapleczu usługi zewnętrznej zmieni się w wyniku interakcji użytkownika z interfejsem dodatku, zalecamy ustawienie bitu „stan zmieniony” na true, aby wyczyścić istniejące pamięci podręczne po stronie klienta. Więcej informacji znajdziesz w opisie metody ActionResponseBuilder.setStateChanged().