针对文本输入的自动补全建议

借助文本输入微件，您的插件可以读取用户提供的文本并对其做出响应。您可以配置这些微件，以便为用户提供输入文本的自动建议。

提供的建议可以来自您提供的静态字符串列表。或者，您也可以根据上下文（例如用户已输入到微件中的文本）构建建议。

配置建议

如需为文本输入配置建议，您只需执行以下操作：

  • 您可以通过以下方式创建建议列表：
    • 创建静态列表，以及/或者
    • 使用一个回调函数定义操作，该回调函数会根据上下文动态构建该列表。
  • 将建议列表和/或操作附加到文本输入 widget。

如果您同时提供静态建议列表和操作，应用界面会使用静态列表，直到用户开始输入字符，此时系统会使用回调函数并忽略静态列表。

静态建议

如需提供静态建议列表，您只需执行以下操作：

  1. 创建一个 Suggestions 对象。
  2. 使用 addSuggestion() 或 addSuggestions() 将每条静态建议添加到其中。
  3. 使用 TextInput.setSuggestions() 将 Suggestions 对象附加到 widget。

界面会按添加的顺序显示静态建议。界面还会在用户向 widget 中输入字符时自动执行不区分大小写的前缀匹配并过滤建议列表。

建议操作

如果您不使用静态建议列表，则必须定义一个操作来动态构建建议。您可按以下步骤实现这一目的：

  1. 创建一个 Action 对象，并将其与您定义的回调函数相关联。
  2. 调用 widget 的 TextInput.setSuggestionsAction() 函数，为其提供 Action 对象。
  3. 实现回调函数以构建建议列表，并返回构建的 SuggestionsResponse 对象。

每当用户在文本输入框中输入字符时，界面都会调用回调函数，但仅在用户停止输入一段时间后才会调用。回调函数会接收一个事件对象，其中包含有关打开的卡片的 widget 的信息。如需了解详情，请参阅Action 事件对象。

回调函数必须返回一个有效的 SuggestionsResponse 对象，其中包含要显示的建议列表。界面会按照添加的顺序显示建议。与静态列表不同，界面不会根据用户输入对回调建议进行任何自动过滤。如果您想进行此类过滤，则必须从事件对象读取文本输入值，并在构建列表时过滤建议。

示例

以下 Google Workspace 插件代码段展示了如何在两个不同的文本输入 widget 上配置建议，第一个使用静态列表，第二个使用回调函数：

// 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 
 *  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() 会触发。