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

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

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

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

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

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

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

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

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

  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() срабатывает, когда ввод текста теряет фокус.