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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

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

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

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

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

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