アドオンのアクション

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

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

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

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

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

ウィジェットを特定の 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 固有。メールの下書きを作成し、その下書きを 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 ホスト アプリケーションのアクション

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

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

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

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

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