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

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

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

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

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

  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() .