アドオンのアクション

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

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

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

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

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

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

ウィジェットを Action やその他の動作にリンクするには、ウィジェット ハンドラ関数を使用します。ハンドラ関数は、どのような操作（ウィジェットのクリックやテキスト フィールドの編集など）でアクションの動作がトリガーされるかを決定します。また、ハンドラ関数は、アクションの完了後に UI が行う手順も定義します。

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

ハンドラ関数 アクションをトリガーする 適用可能なウィジェット 説明
setOnChangeAction ウィジェットの値が変更される DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		ウィジェットのフォーカスが外れたときに Apps Script 関数を実行する Action を設定します。ユーザーが入力欄にテキストを入力して Enter キーを押す場合などです。ハンドラは、呼び出す関数にイベント オブジェクトを自動的に渡します。必要に応じて、このイベント オブジェクトに追加のパラメータ情報を挿入できます 。
setOnClickAction ユーザーがウィジェットをクリックする CardAction
Image
ImageButton
DecoratedText
TextButton 		ユーザーがウィジェットをクリックしたときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出す関数に イベント オブジェクトを自動的に渡します。 このイベント オブジェクトに省略可能なパラメータ情報を挿入できます。
setComposeAction ユーザーがウィジェットをクリックする CardAction
Image
ImageButton
DecoratedText
TextButton 		Gmail 固有。メールの下書きを作成し、その下書きを Action の作成ウィンドウに表示する を設定します。下書きは、新しい メッセージとして作成することも、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 関数であるため、他のスクリプト関数とほぼ同じことができます。

Action

コールバック関数は、特定のレスポンス オブジェクトを返すことがあります。このようなレスポンスは、新しいカードの表示や予測入力の候補の表示など、コールバックの実行後に実行する必要がある追加の操作を示します。コールバック関数が特定の レスポンス オブジェクトを返す必要がある場合は、Card サービスの Builder クラスを使用してそのオブジェクトを作成します。

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

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

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

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

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

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

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

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

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

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

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