自動完成文字輸入建議

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

這些建議可能來自您提供的靜態字串清單。 或者,您也可以根據情境 (例如文字) 建構建議。 使用者已在小工具中輸入內容。

設定建議

您只需要完成 包括:

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

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

靜態建議

如要提供靜態建議清單,您只需要執行以下步驟:

  1. 建立 Suggestions 物件。
  2. 使用 addSuggestion() 將各項靜態建議加入建議 或 addSuggestions()
  3. Suggestions 物件加入小工具。TextInput.setSuggestions()

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

建議動作

如果您未使用靜態建議清單,則必須定義一項動作 即可動態建構建議只要按照以下步驟操作即可:

  1. 建立 Action 物件 並與回呼函式建立關聯 每個 Pod 都有專屬的 IP 位址
  2. 呼叫小工具的 TextInput.setSuggestionsAction() 函式,提供 Action 物件。
  3. 實作回呼函式以建構建議清單並傳回 已建立的 SuggestionsResponse 物件。

當使用者在 但使用者暫時停止輸入字詞後才會消失 回呼函式會接收事件物件,內含 開啟資訊卡的小工具。詳情請見 動作事件物件

回呼函式必須傳回有效的 SuggestionsResponse 物件,其中包含要顯示的建議清單。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() 會觸發 文字輸入失去焦點時