アドオン アクション

アドオン アクションは、ウィジェットにインタラクティブな動作を提供します。アクションを作成することで、ユーザーがウィジェットを選択または更新したときの動作を定義します。

ほとんどの場合、Apps Script カードサービスが提供する Action オブジェクトを使用してアドオン アクションを定義できます。各 Action は、作成時にコールバック関数に関連付けられます。コールバック関数を実装して、ユーザーがウィジェットを操作したときの目的のステップを実行できるようにします。また、Action コールバックをトリガーする操作の種類を定義する適切なウィジェット ハンドラ関数を使用して、Action をウィジェットにリンクする必要があります。

次の一般的なプロセスを使用して、Action でウィジェットを構成します。

  1. Action オブジェクトを作成し、必要なパラメータとともに実行するコールバック関数を指定します。
  2. Action オブジェクトを使用して、ウィジェットに対して適切なウィジェット ハンドラ関数を呼び出します。
  3. 必要な動作を実現するためのコールバック関数を実装します。

ウィジェット ハンドラ関数

ウィジェットを特定の Action やその他の動作にリンクするには、ウィジェット ハンドラ関数を使用します。ハンドラ関数は、どの種類のインタラクション（ウィジェットのクリックやテキスト フィールドの編集など）によってアクションの動作がトリガーされるかを決定します。ハンドラ関数は、アクションの完了後に UI が実行するステップ（ある場合）も定義します。

次の表に、ウィジェットの各ハンドラの種類と、使用するウィジェットを示します。

ハンドラ関数 アクションをトリガー 該当するウィジェット 説明
setOnChangeAction() ウィジェットの値が変更される DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		ユーザーが入力テキストを入力して Enter キーを押すなど、ウィジェットがフォーカスを失ったときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。必要に応じて、このイベント オブジェクトに追加のパラメータ情報を挿入できます。
setOnClickAction() ユーザーがウィジェットをクリックします。 CardAction
Image
ImageButton
DecoratedText
TextButton 		ユーザーがウィジェットをクリックしたときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。このイベント オブジェクトには任意のパラメータ情報を挿入できます。
setComposeAction() ユーザーがウィジェットをクリックします。 CardAction
Image
ImageButton
DecoratedText
TextButton 		Gmail 固有。メールの下書きを作成する Action を設定し、その下書きを Gmail の UI 作成ウィンドウに表示します。下書きは、新しいメッセージまたは Gmail のオープン メッセージへの返信として作成できます。ハンドラは、ドラフト構築のコールバック関数を呼び出すと、コールバック関数にイベント オブジェクトを渡します。詳しくは、メッセージの下書きを作成するをご覧ください。
setOnClickOpenLinkAction() ユーザーがウィジェットをクリックします。 CardAction
Image
ImageButton
DecoratedText
TextButton 		ユーザーがウィジェットをクリックしたときに URL を開くように Action を設定します。このハンドラは、URL を構築する必要がある場合や、リンクを開く前に他のアクションを実行する必要がある場合に使用します。それ以外の場合は通常、setOpenLink() を使用する方が簡単です。URL は新しいウィンドウでのみ開くことができます。閉じたら、UI でアドオンを再読み込みできます。
setOpenLink() ユーザーがウィジェットをクリックします。 CardAction
Image
ImageButton
DecoratedText
TextButton 		ユーザーがウィジェットをクリックすると、URL を直接開きます。このハンドラは、URL がわかっていて、開く必要がある場合にのみ使用します。それ以外の場合は setOnClickOpenLinkAction() を使用します。 URL は新しいウィンドウまたはオーバーレイで開くことができます。閉じたら、UI でアドオンを再読み込みできます。
setSuggestionsAction() ユーザーが入力テキストを入力する TextInput ユーザーがテキスト入力ウィジェットにテキストを入力したときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。詳しくは、テキスト入力のオートコンプリート候補をご覧ください。

コールバック関数

Action がトリガーされると、コールバック関数が実行されます。コールバック関数は Apps Script 関数であるため、他のスクリプト関数とほぼ同じ処理を行うことができます。

コールバック関数から特定のレスポンス オブジェクトが返されることがあります。これらの種類のレスポンスは、新しいカードの表示やオートコンプリートの候補の提示など、コールバックの実行が完了した後に必要となる追加のオペレーションを示します。コールバック関数が特定のレスポンス オブジェクトを返す必要がある場合は、カードサービスのビルダークラスを使用してそのオブジェクトを作成します。

次の表に、コールバック関数が特定のアクションに対して特定のレスポンス オブジェクトを返すタイミングを示します。これらのアクションはすべて、アドオンが拡張している特定のホスト アプリケーションに依存しません。

試行された操作 コールバック関数は
カード間を移動する ActionResponse
Notification を表示する ActionResponse
setOnClickOpenLinkAction() を使用してリンクを開く ActionResponse
オートコンプリートの候補を表示する SuggestionResponse
ユニバーサル アクションを使用する UniversalActionResponse
その他の操作 なし

これらのアクションに加えて、各ホスト アプリケーションには、そのホストでしか実行できない独自のアクションがあります。詳しくは、次のガイドをご覧ください。

アクション イベント オブジェクト

アドオンが Action をトリガーすると、UI は自動的に JSON イベント オブジェクトを作成し、その引数として Action コールバック関数に渡します。このイベント オブジェクトには、ユーザーの現在のクライアント コンテキストに関する情報（表示カード内のすべてのインタラクティブ ウィジェットの現在の値など）が含まれます。

アクション イベント オブジェクトには、含まれる情報を整理するための特定の JSON 構造があります。ホームページの作成ホームページのトリガーが配信されたとき、またはアドオン ディスプレイを更新するためのコンテキスト トリガーが配信されたときも同じ構造を使用します。

イベント オブジェクト構造の詳細については、イベント オブジェクトをご覧ください。