「Text Input」小工具 可讓外掛程式讀取並回應使用者提供的文字。你可以 設定這些小工具，為使用者提供自動建議 輸入文字
這些建議可能來自您提供的靜態字串清單。 或者，您也可以根據情境 (例如文字) 建構建議。 使用者已在小工具中輸入內容。
設定建議
您只需要完成 包括：
- 透過以下方式建立建議清單：
- 建立靜態清單，和/或
- 使用以下項目定義動作： 根據內容動態建構清單的回呼函式。
- 將建議清單和/或動作附加至文字輸入小工具。
如果同時提供靜態建議清單和動作， 應用程式 UI 會使用靜態清單，直到使用者開始輸入字元。 其中會使用回呼函式，並忽略靜態清單。
靜態建議
如要提供靜態建議清單，您只需要執行以下步驟：
- 建立
Suggestions物件。 - 使用
addSuggestion()將各項靜態建議加入建議 或addSuggestions()。 - 將
Suggestions物件加入小工具。TextInput.setSuggestions()。
UI 會按照靜態建議加入的順序顯示。使用者介面 也能自動執行不區分大小寫的前置字串比對，並篩選 因為使用者在小工具中輸入字元。
建議動作
如果您未使用靜態建議清單，則必須定義一項動作 即可動態建構建議只要按照以下步驟操作即可：
- 建立
Action物件 並與回呼函式建立關聯 每個 Pod 都有專屬的 IP 位址 - 呼叫小工具的
TextInput.setSuggestionsAction()函式，提供Action物件。 - 實作回呼函式以建構建議清單並傳回
已建立的
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()
定義的處理常式函式，會在小工具失去焦點時執行。
如果對相同文字輸入內容同時啟用這個處理常式和建議，
以下規則可定義文字輸入互動行為：
- 選取建議後，
setOnChangeAction()處理常式就會執行。 - 當使用者按下 Enter 鍵 (或導致輸入的文字失去焦點)
如果沒有修改所選建議，
setOnChangeAction()就不會 再次觸發。 - 如果使用者在選取一項應用程式後，
setOnChangeAction()會再次觸發 請加以編輯，使其不再符合任何建議 。 - 如果使用者未選取建議，
setOnChangeAction()會觸發 文字輸入失去焦點時