アドオン アクションは、ウィジェットにインタラクティブな動作を提供します。アクションを作成することで、ユーザーがウィジェットを選択または更新したときの動作を定義します。
ほとんどの場合、Apps Script カードサービスが提供する Action オブジェクトを使用してアドオン アクションを定義できます。各 Action は、作成時にコールバック関数に関連付けられます。コールバック関数を実装して、ユーザーがウィジェットを操作したときの目的のステップを実行できるようにします。また、Action コールバックをトリガーする操作の種類を定義する適切なウィジェット ハンドラ関数を使用して、Action をウィジェットにリンクする必要があります。
次の一般的なプロセスを使用して、Action でウィジェットを構成します。
Actionオブジェクトを作成し、必要なパラメータとともに実行するコールバック関数を指定します。Actionオブジェクトを使用して、ウィジェットに対して適切なウィジェット ハンドラ関数を呼び出します。- 必要な動作を実現するためのコールバック関数を実装します。
ウィジェット ハンドラ関数
ウィジェットを特定の Action やその他の動作にリンクするには、ウィジェット ハンドラ関数を使用します。ハンドラ関数は、どの種類のインタラクション（ウィジェットのクリックやテキスト フィールドの編集など）によってアクションの動作がトリガーされるかを決定します。ハンドラ関数は、アクションの完了後に UI が実行するステップ（ある場合）も定義します。
次の表に、ウィジェットの各ハンドラの種類と、使用するウィジェットを示します。
| ハンドラ関数 | アクションをトリガー | 該当するウィジェット | 説明 |
|---|---|---|---|
setOnChangeAction() |
ウィジェットの値が変更される |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
ユーザーが入力テキストを入力して Enter キーを押すなど、ウィジェットがフォーカスを失ったときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。必要に応じて、このイベント オブジェクトに追加のパラメータ情報を挿入できます。 |
setOnClickAction() |
ユーザーがウィジェットをクリックします。 |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックしたときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。このイベント オブジェクトには任意のパラメータ情報を挿入できます。 |
setComposeAction() |
ユーザーがウィジェットをクリックします。 |
CardActionImageImageButtonDecoratedTextTextButton
|
Gmail 固有。メールの下書きを作成する Action を設定し、その下書きを Gmail の UI 作成ウィンドウに表示します。下書きは、新しいメッセージまたは Gmail のオープン メッセージへの返信として作成できます。ハンドラは、ドラフト構築のコールバック関数を呼び出すと、コールバック関数にイベント オブジェクトを渡します。詳しくは、メッセージの下書きを作成するをご覧ください。 |
setOnClickOpenLinkAction() |
ユーザーがウィジェットをクリックします。 |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックしたときに URL を開くように Action を設定します。このハンドラは、URL を構築する必要がある場合や、リンクを開く前に他のアクションを実行する必要がある場合に使用します。それ以外の場合は通常、setOpenLink() を使用する方が簡単です。URL は新しいウィンドウでのみ開くことができます。閉じたら、UI でアドオンを再読み込みできます。 |
setOpenLink() |
ユーザーがウィジェットをクリックします。 |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックすると、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 構造があります。ホームページの作成ホームページのトリガーが配信されたとき、またはアドオン ディスプレイを更新するためのコンテキスト トリガーが配信されたときも同じ構造を使用します。
イベント オブジェクト構造の詳細については、イベント オブジェクトをご覧ください。