Создание интерактивных карточек

Большинство дополнений, помимо отображения данных, требуют от пользователя ввода информации. При создании дополнения на основе карточек вы можете использовать интерактивные виджеты , такие как кнопки, пункты меню на панели инструментов или флажки, чтобы запросить у пользователя необходимые для дополнения данные или предоставить другие элементы управления взаимодействием.

Добавление действий к виджетам

В большинстве случаев интерактивность виджетов обеспечивается путем их привязки к определенным действиям и реализации необходимого поведения в функции обратного вызова. Подробнее см. в разделе «Дополнительные действия» .

В большинстве случаев для настройки виджета на выполнение определенного действия при выборе или обновлении можно следовать следующей общей процедуре:

  1. Создайте объект Action , указав функцию обратного вызова, которая должна быть выполнена, а также все необходимые параметры.
  2. Свяжите виджет с Action , вызвав соответствующую функцию обработчика виджета .
  3. Реализуйте функцию обратного вызова для выполнения требуемого действия.

Пример

В следующем примере задается кнопка, которая после нажатия отображает уведомление для пользователя. Нажатие запускает функцию обратного вызова notifyUser() с аргументом, указывающим текст уведомления. Возврат сформированного объекта ActionResponse приводит к отображению уведомления.

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

Разрабатывайте эффективные интерактивные решения.

При разработке интерактивных карточек следует учитывать следующее:

  • Интерактивным виджетам обычно требуется как минимум один метод-обработчик для определения их поведения.

  • Используйте функцию обработчика виджета setOpenLink() если у вас есть URL-адрес, и вы просто хотите открыть его во вкладке. Это позволяет избежать необходимости определять объект Action и функцию обратного вызова. Если вам необходимо сначала сформировать URL-адрес или выполнить какие-либо другие дополнительные действия перед открытием URL-адреса, определите Action и используйте вместо этого setOnClickOpenLinkAction() .

  • При использовании функций обработчика виджетов setOpenLink() или setOnClickOpenLinkAction() необходимо предоставить объект OpenLink , чтобы определить, какой URL-адрес следует открыть. Этот же объект можно использовать для указания поведения открытия и закрытия с помощью перечислений OpenAs и OnClose .

  • Один и тот же объект Action может использоваться несколькими виджетами. Однако, если вы хотите передать функции обратного вызова разные параметры, вам потребуется определить разные объекты Action .

  • Используйте простые функции обратного вызова. Для обеспечения быстродействия дополнений служба Card ограничивает время выполнения функций обратного вызова максимум 30 секундами. Если выполнение займет больше времени, пользовательский интерфейс вашего дополнения может некорректно обновлять отображение карточки в ответ на Action .

  • Если состояние данных в стороннем бэкэнде изменяется в результате взаимодействия пользователя с пользовательским интерфейсом вашего дополнения, рекомендуется установить для дополнения бит «состояние изменено» в true , чтобы очистить существующий кэш на стороне клиента. Дополнительные сведения см. в описании метода ActionResponseBuilder.setStateChanged() .