アドオンのアクション

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

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

次の手順で Action を使用してウィジェットを構成します。

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

Action オブジェクトと CardAction オブジェクトを混同しないでください。CardAction オブジェクトはカード ヘッダーのメニュー項目で、Action オブジェクトは UI に対するユーザー操作へのレスポンスを定義します。

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

ウィジェットを 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 固有。メールの下書きを作成し、その下書きを Gmail UI の作成ウィンドウでユーザーに表示する Action を設定します。下書きは、Gmail で新しいメッセージとして作成することも、開いているメッセージへの返信として作成することもできます。ハンドラが下書き作成コールバック関数を呼び出すと、イベント オブジェクトがコールバック関数に渡されます。詳しくは、Compose で下書きメッセージを作成するをご覧ください。
setOnClickOpenLinkAction	ユーザーがウィジェットをクリックする	CardAction Image ImageButton DecoratedText TextButton	ユーザーがウィジェットをクリックしたときに URL を開く Action を設定します。このハンドラは、リンクを開く前に URL を作成する必要がある場合や、他のアクションを実行する必要がある場合に使用します。それ以外の場合は、通常 setOpenLink を使用する方が簡単です。URL は新しいウィンドウでのみ開くことができます。閉じると、UI でアドオンを再読み込みできます。
setOpenLink	ユーザーがウィジェットをクリックする	CardAction Image ImageButton DecoratedText TextButton	ユーザーがウィジェットをクリックしたときに URL を直接開きます。このハンドラは、URL がわかっていて、その URL を開くだけでよい場合にのみ使用します。それ以外の場合は setOnClickOpenLinkAction を使用します。URL は新しいウィンドウまたはオーバーレイで開くことができます。閉じると、UI でアドオンを再読み込みできます。
setSuggestionsAction	ユーザーが入力にテキストを入力する	TextInput	ユーザーがテキスト入力ウィジェットにテキストを入力したときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数に イベント オブジェクトを自動的に渡します。詳しくは、テキスト入力の予測候補をご覧ください。

コールバック関数

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

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

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

試行されたアクション	コールバック関数は
ナビゲーション	ActionResponse
Notification を表示する	ActionResponse
setOnClickOpenLinkAction を使用してリンクを開く	ActionResponse
予測入力の候補を表示する	SuggestionResponse
ユニバーサル アクションを使用する	UniversalActionResponse
その他の操作	Nothing

Google Workspace ホスト アプリケーションのアクション

これらのアクションに加えて、各ホスト アプリケーションには、そのホストでのみ実行できる独自のアクション セットがあります。詳細については、以下のガイドをご覧ください。

• カレンダー アクション
• チャット アクション
• 行動を促す
• Gmail アクション
• エディタのアクション

レスポンス ビルダー クラスを使用する場合は、build メソッドを呼び出してレスポンス オブジェクトを生成します。この要件を満たさないと、エラーが発生します。

ユニバーサル アクションはプロジェクト マニフェストで定義され、Action オブジェクトは必要ありませんが、コールバック関数は UniversalActionResponse を返す必要があります。

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

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

アクション イベント オブジェクトには、含まれる情報を整理する特定の JSON 構造があります。ホームページ トリガーが起動してホームページが作成される場合や、コンテキスト トリガーが起動してアドオンの表示が更新される場合も、同じ構造が使用されます。

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

Gmail アドオンでは、このイベント オブジェクト構造の簡略版が使用されていましたが、これは現在非推奨となっています。下位互換性を維持するため、元の Gmail アドオンのイベント オブジェクトのすべてのフィールドは、新しいイベント オブジェクト構造内に含まれています（イベント オブジェクト構造を参照）。ただし、同じ情報は commonEventObject と Gmail イベント オブジェクトのサブ構造で再現されます。Gmail アドオンを Google Workspace アドオンにアップグレードする場合は、更新されたイベント オブジェクト フィールドを使用するようにコードを調整します。最終的には、元の Gmail イベント オブジェクトのフィールドが削除されます。