Предложения автозаполнения для ввода текста

Виджет «Ввод текста» позволяет вашему дополнению считывать и реагировать на текст, вводимый пользователями. Вы можете настроить эти виджеты для предоставления пользователям автоматических подсказок для ввода текста.

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

Настройка предложений

Для настройки подсказок для ввода текста необходимо выполнить только следующее:

  • Создайте список предложений по:
    • Создание статического списка и/или
    • Определение действия с функцией обратного вызова, которая динамически создает этот список из контекста.
  • Прикрепите список предложений и/или действий к виджету ввода текста.

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

Статические предложения

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

  1. Создайте объект Suggestions .
  2. Добавьте к нему каждое статическое предложение с помощью addSuggestion() или addSuggestions() .
  3. Прикрепите объект Suggestions к виджету с помощью TextInput.setSuggestions() .

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

Действия по предложению

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

  1. Создайте объект Action и свяжите его с определенной вами функцией обратного вызова .
  2. Вызовите функцию TextInput.setSuggestionsAction() виджета, предоставив ей объект Action .
  3. Реализуйте функцию обратного вызова для создания списка предложений и возврата построенного объекта SuggestionsResponse .

Пользовательский интерфейс вызывает функцию обратного вызова каждый раз, когда пользователь вводит символ в поле ввода, но только после того, как пользователь на мгновение прекращает ввод. Функция обратного вызова получает объект события , содержащий информацию о виджетах открытой карточки. Подробнее см. в разделе «Объекты событий действия» .

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

Пример

В следующем фрагменте кода надстройки Google Workspace показано, как настроить подсказки для двух разных виджетов ввода текста: первый — со статическим списком, а второй — с использованием функции обратного вызова:

// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
    .setFieldName('colorInput')
    .setTitle('Color choice')
    .setSuggestions(CardService.newSuggestions()
        .addSuggestion('Red')
        .addSuggestion('Yellow')
        .addSuggestions(['Blue', 'Black', 'Green']));

// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
    .setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
    .setFieldName('emailInput')
    .setTitle('Email')
    .setSuggestionsAction(action);

// ...

/**
 *  Build and return a suggestion response. In this case, the suggestions
 *  are a list of emails taken from the To: and CC: lists of the open
 *  message in Gmail, filtered by the text that the user has already
 *  entered. This method assumes the Google Workspace
 *  add-on extends Gmail; the add-on only calls this method for cards
 *  displayed when the user has entered a message context.
 *
 *  @param {Object} e the event object containing data associated with
 *      this text input widget.
 *  @return {SuggestionsResponse}
 */
 function refreshSuggestions(e) {
   // Activate temporary Gmail scopes, in this case so that the
   // open message metadata can be read.
   var accessToken = e.gmail.accessToken;
   GmailApp.setCurrentMessageAccessToken(accessToken);

   var userInput = e && e.formInput['emailInput'].toLowerCase();
   var messageId = e.gmail.messageId;
   var message = GmailApp.getMessageById(messageId);

   // Combine the comma-separated returned by these methods.
   var addresses = message.getTo() + ',' + message.getCc();

   // Filter the address list to those containing the text the user
   // has already entered.
   var suggestionList = [];
   addresses.split(',').forEach(function(email) {
     if (email.toLowerCase().indexOf(userInput) !== -1) {
       suggestionList.push(email);
     }
   });
   suggestionList.sort();

   return CardService.newSuggestionsResponseBuilder()
       .setSuggestions(CardService.newSuggestions()
           .addSuggestions(suggestionList))
       .build();  // Don't forget to build the response!
 }

Предложения и OnChangeAction()

Для виджетов текстового ввода можно определить функцию-обработчик setOnChangeAction() , которая выполняется при потере фокуса виджетом. Если этот обработчик и подсказки включены для одного и того же текстового поля, следующие правила определяют поведение взаимодействия с текстовым полем:

  1. Обработчик setOnChangeAction() выполняется после выбора предложения.
  2. Если пользователь нажимает Enter (или иным образом теряет фокус ввода текста), не изменяя выбранное предложение, setOnChangeAction() больше не срабатывает.
  3. setOnChangeAction() срабатывает снова, если пользователь, выбрав предложение, редактирует его так, что оно больше не соответствует ни одному из предложений в списке.
  4. Если пользователь не выбирает предложение, setOnChangeAction() срабатывает, когда поле ввода текста теряет фокус.