テキスト入力ウィジェットを使用すると、アドオンで、ユーザーが入力したテキストを読み取って応答できます。これらのウィジェットを設定すると、入力テキストを自動的にユーザーに提示するようにできます。
指定する文字列の静的なリストから候補を導き出すことができます。 または、ユーザーがウィジェットにすでに入力したテキストなどのコンテキストから候補を作成することもできます。
候補の構成
テキスト入力の候補を設定するには、次のことのみを行う必要があります。
- 次の方法で候補のリストを作成します。
- 静的リストを作成する
- コンテキストからリストを動的に作成するコールバック関数を使用してアクションを定義する。
- 候補リストやアクションをテキスト入力ウィジェットに追加します。
候補の静的リストとアクションの両方を提供する場合、アプリ UI はユーザーが文字の入力を開始するまで静的リストを使用します。ユーザーが文字を入力し始めると、コールバック関数が使用され、静的リストは無視されます。
静的候補
候補の静的リストを提供するには、次のことのみを行う必要があります。
Suggestions
オブジェクトを作成します。addSuggestion()
またはaddSuggestions()
を使用して、各静的候補をそれに追加します。TextInput.setSuggestions()
を使用して、Suggestions
オブジェクトをウィジェットにアタッチします。
UI には、静的な候補が追加された順に表示されます。また、UI は大文字と小文字を区別しない接頭辞のマッチングを自動的に実行し、ユーザーがウィジェットに文字を入力すると候補リストをフィルタします。
候補の操作
静的な候補リストを使用していない場合は、候補を動的に作成するアクションを定義する必要があります。手順は次のとおりです。
Action
オブジェクトを作成し、定義したコールバック関数に関連付けます。- ウィジェットの
TextInput.setSuggestionsAction()
関数を呼び出し、Action
オブジェクトを指定します。 - 候補リストを作成し、ビルドされた
SuggestionsResponse
オブジェクトを返すコールバック関数を実装します。
UI は、ユーザーがテキスト入力に文字を入力するたびにコールバック関数を呼び出します。ただし、ユーザーが入力を一瞬停止した後でのみ行います。コールバック関数は、開いているカードのウィジェットに関する情報を含むイベント オブジェクトを受け取ります。詳しくは、アクション イベント オブジェクトをご覧ください。
コールバック関数は、表示する候補のリストを含む有効な SuggestionsResponse
オブジェクトを返す必要があります。候補は、追加された順序で UI に表示されます。静的リストとは異なり、UI ではユーザー入力に基づいてコールバックの候補の自動フィルタリングは行われません。このようなフィルタリングが必要な場合は、イベント オブジェクトからテキスト入力値を読み取り、リストの作成時に候補をフィルタリングする必要があります。
例
次の Google Workspace アドオンのコード スニペットは、2 つの異なるテキスト入力ウィジェットで候補を構成する方法を示しています。1 つ目のウィジェットは静的リストを使用し、2 つ目のウィジェットはコールバック関数を使用します。
// 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()
がトリガーされます。