アドオン アクション

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

ほとんどの場合、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 関数であるため、他のスクリプト関数とほぼすべての処理を、コールバック関数で行うことができます。

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

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

試行された操作 コールバック関数は
カード間を移動する ActionResponse
Notification を表示する ActionResponse
setOnClickOpenLinkAction() を使用してリンクを開く ActionResponse
オートコンプリートの候補を表示する SuggestionResponse
ユニバーサル アクションを使用する UniversalActionResponse
その他の操作 なし

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

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

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

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

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