アドオンのアクション

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

ほとんどの場合、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
その他の操作 Nothing

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

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

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

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

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