アドオンのアクション

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

ほとんどの場合、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 専用。メールの下書きを作成し、その下書きを Gmail UI の作成ウィンドウでユーザーに表示する 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 関数なので、他のスクリプト関数で実行できるほぼすべての処理を、これらの関数に実行させることができます。

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

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

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

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

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

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

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

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