文字輸入小工具可讓外掛程式讀取使用者提供的文字並做出回應。您可以設定這些小工具,為使用者提供輸入文字的自動建議。
系統提供的建議可來自您提供的靜態字串清單。或者,您也可以根據內容建立建議,例如使用者已輸入小工具的文字。
設定建議
如要設定文字輸入建議,您只需執行下列操作:
- 建立建議清單的方法:
- 建立靜態清單,以及/或者
- 使用回呼函式定義動作,該函式會根據內容動態建構該清單。
- 將建議清單和/或動作附加至文字輸入小工具。
如果您同時提供靜態建議清單和動作,應用程式 UI 會使用靜態清單,直到使用者開始輸入字元為止,屆時系統會使用回呼函式,並忽略靜態清單。
靜態建議
如要提供靜態建議清單,您只需執行下列操作:
- 建立
Suggestions
物件。 - 使用
addSuggestion()
或addSuggestions()
新增每個靜態建議。 - 使用
TextInput.setSuggestions()
將Suggestions
物件附加至小工具。
使用者介面會按照新增的順序顯示靜態建議。UI 也會自動執行不區分大小寫的前置字串比對,並在使用者在小工具中輸入字元時篩選建議清單。
建議動作
如果您沒有使用靜態建議清單,就必須定義動作,才能動態建立建議。只要按照以下步驟操作即可:
- 建立
Action
物件,並將其與您定義的回呼函式建立關聯。 - 呼叫小工具的
TextInput.setSuggestionsAction()
函式,並提供Action
物件。 - 實作回呼函式,以建構建議清單並傳回已建構的
SuggestionsResponse
物件。
每當使用者在文字輸入內容中輸入字元,UI 就會呼叫回呼函式,但只有在使用者停止輸入一段時間後才會呼叫。回呼函式會接收含有開放資訊卡小工具相關資訊的事件物件。詳情請參閱「動作事件物件」。
回呼函式必須傳回有效的 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()
會在文字輸入內容失去焦點時觸發。