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

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

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

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

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

  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)
            .setType(CardService.NotificationType.INFO))
        .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() .