自動完成文字輸入建議

「文字輸入」小工具可讓您的外掛程式讀取並回應使用者提供的文字。您可以設定這些小工具，向使用者提供輸入文字的自動建議。

這些建議可能來自您提供的靜態字串清單。或者，您也可以根據背景資訊建構建議，例如使用者已在小工具中輸入的文字。

設定建議

如要設定文字輸入的建議，您只需要執行下列操作：

  • 透過以下方式建立建議清單：
    • 建立靜態清單，和/或
    • 使用回呼函式定義動作，以便根據內容動態建構清單。
  • 將建議清單和/或動作附加到文字輸入小工具。

如果您同時提供建議和動作的靜態清單，應用程式 UI 會使用靜態清單，直到使用者開始輸入字元為止，這時會使用回呼函式並忽略靜態清單。

靜態建議

如要提供靜態建議清單，只需執行下列步驟：

  1. 建立 Suggestions 物件。
  2. 使用 addSuggestion() 或 addSuggestions() 將每個靜態建議新增至其中。
  3. 使用 TextInput.setSuggestions() 將 Suggestions 物件附加至小工具。

UI 會按照加入順序顯示靜態建議。UI 也會自動執行不區分大小寫的前置字串比對，並在使用者於小工具中輸入字元時篩選建議清單。

建議動作

如果您不使用靜態建議清單，則必須定義動作才能動態建構建議。只要按照以下步驟操作即可：

  1. 建立 Action 物件，並將其與您定義的回呼函式建立關聯。
  2. 呼叫小工具的 TextInput.setSuggestionsAction() 函式，提供 Action 物件。
  3. 實作回呼函式以建構建議清單，並傳回建構的 SuggestionsResponse 物件。

每當使用者在文字輸入中輸入字元時，UI 才會呼叫回呼函式，但只有在使用者停止輸入一段時間後才會呼叫回呼函式。回呼函式會收到含有開啟卡片小工具相關資訊的事件物件。詳情請參閱「動作事件物件」。

回呼函式必須傳回有效的 SuggestionsResponse 物件，其中包含要顯示的建議清單。UI 會按照新增建議的順序顯示建議。有別於靜態清單，UI 不會根據使用者輸入內容自動篩選回呼建議。如要進行這類篩選，您必須從事件物件讀取文字輸入值，並在建立清單時篩選建議。

範例

下列 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() 會在文字輸入失去焦點時觸發。