Tworzenie interaktywnych kart

Większość dodatków, oprócz prezentowania danych, wymaga od użytkownika i informacjami o nich. Gdy tworzysz dodatek oparty na kartach, możesz używać: interaktywne widżety, takie jak przyciski, elementy menu na pasku narzędzi lub pola wyboru z prośbą o podanie danych lub zapewnienie innych ustawień interakcji.

Dodawanie działań do widżetów

Widżety są najczęściej interaktywne, ponieważ zawierają linki konkretne działania i zaimplementowanie wymaganego zachowania w wywołaniu zwrotnym, . Szczegóły znajdziesz w sekcji Dodatki.

W większości przypadków możesz wykonać tę ogólną procedurę, aby skonfigurować widżet wykonaj określone działanie po wybraniu lub aktualizacji:

  1. Utwórz obiekt Action. określając funkcję wywołania zwrotnego, która powinna zostać wykonana, oraz .
  2. Połącz widżet z aplikacją Action, wywołując odpowiednią funkcji obsługi widżetów.
  3. zaimplementować funkcję wywołania zwrotnego. w celu wprowadzenia wymaganych działań.

Przykład

Ten przykład umożliwia ustawienie przycisku do wyświetlania powiadomienia dla użytkownika po jego kliknięciu. Kliknięcie powoduje uruchomienie funkcji wywołania zwrotnego notifyUser() z argumentem, który określa tekst powiadomienia. Zwracanie kompilacji 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:

  • Widżety interaktywne zwykle wymagają co najmniej jednej metody obsługi zachowanie użytkownika.

  • Korzystanie z widżetu setOpenLink() , jeśli masz URL i chcesz tylko otworzyć go w karcie. Dzięki temu nie trzeba definiować tagu obiekt Action i wywołanie zwrotne . Jeśli chcesz najpierw utworzyć adres URL lub wykonać inne przed otwarciem adresu URL zdefiniuj Action i używanie setOnClickOpenLinkAction() .

  • Gdy używasz setOpenLink() lub setOnClickOpenLinkAction() funkcji obsługi widżetów, musisz podać OpenLink aby określić adres URL, który ma zostać otworzony. Możesz też użyć tego obiektu, aby określić zachowanie, które otwiera się podczas otwierania i zamykania OpenAs i Wyliczenia OnClose.

  • Istnieje możliwość, że więcej niż jeden widżet używa tego samego Action. Trzeba jednak zdefiniować różne Action obiektów, jeśli chcesz. , aby dostarczyć funkcji wywołania zwrotnego inne parametry.

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

  • Jeśli stan danych w backendzie innej firmy zmieni się w wyniku działania użytkownika z interfejsem dodatku, zalecamy „zmiana stanu”; do true, tak aby obecna pamięć podręczna po stronie klienta była wyczyszczono. Zobacz ActionResponseBuilder.setStateChanged() z opisem metody.