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

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

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

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

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

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