テキスト入力用のオートコンプリート候補

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

テキスト入力ウィジェットを使用すると、アドオンはユーザーが指定したテキストを読み取ってリアクションできます。これらのウィジェットは、入力テキストを自動的にユーザーに提示するよう構成できます。

提案は、指定した文字列の静的リストから取得されます。あるいは、ユーザーがウィジェットに入力したテキストなど、コンテキストに基づいて候補を作成することもできます。

候補の構成

テキスト入力の提案を構成するには、次の操作を行います。

  • 次の方法で、返信文候補のリストを作成します。
    • 静的リストを作成する、および/または
    • コンテキストから動的にリストを表示するコールバック関数を使用してアクションを定義する。
  • テキスト入力ウィジェットに候補リストやアクションを追加します。

候補の静的リストとアクションの両方を提供すると、アプリケーション 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 アドオン コード スニペットは、2 つの異なるテキスト入力ウィジェットで提案を構成する方法を示しています。1 つは静的リストで、もう 1 つはコールバック関数を使用します。

// 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() はテキスト入力がフォーカスされなくなるとトリガーされます。