アドオン アクションでは、ウィジェットにインタラクティブな動作を設定できます。アクションを作成することで、ユーザーがウィジェットを選択または更新したときの動作を定義します。
ほとんどの場合、Apps Script カードサービスで提供される Action オブジェクトを使用して、アドオン アクションを定義できます。各 Action は、作成時にコールバック関数に関連付けられます。ユーザーがウィジェットを操作したときに必要な手順を実行するコールバック関数を実装します。また、適切なウィジェット ハンドラ関数を使用して Action をウィジェットにリンクする必要があります。これにより、Action コールバックをトリガーする操作の種類が定義されます。
次の一般的なプロセスを使用して、Action でウィジェットを構成します。
Actionオブジェクトを作成し、実行するコールバック関数と必要なパラメータを指定します。Actionオブジェクトを使用して、ウィジェットで適切なウィジェット ハンドラ関数を呼び出します。- コールバック関数を実装し、必要な動作を実行します。
ウィジェット ハンドラ関数
ウィジェットを特定の Action などの動作にリンクするには、ウィジェット ハンドラ関数を使用します。ハンドラ関数は、操作の種類（ウィジェットのクリックやテキスト フィールドの編集など）に応じてアクションの動作をトリガーします。ハンドラ関数は、操作完了後に UI が実行するステップ（ある場合）も定義します。
次の表に、ウィジェットのさまざまなハンドラの種類と、使用されるウィジェットを示します。
| ハンドラ関数 | アクションをトリガー | 該当するウィジェット | 説明 |
|---|---|---|---|
setOnChangeAction() |
ウィジェットの値が変更される |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
ウィジェットがフォーカスを失ったとき（ユーザーが入力にテキストを入力し、Enter キーを押すときなど）に Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出すイベントにイベント オブジェクトを自動的に渡します。必要に応じて、このイベント オブジェクトに追加のパラメータ情報を挿入できます。 |
setOnClickAction() |
ユーザーがウィジェットをクリックする |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックしたときに Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出すイベントにイベント オブジェクトを自動的に渡します。このイベント オブジェクトには、省略可能なパラメータ情報を挿入できます。 |
setComposeAction() |
ユーザーがウィジェットをクリックする |
CardActionImageImageButtonDecoratedTextTextButton
|
Gmail に固有の指標です。メールの下書きを作成する Action を設定し、その下書きを Gmail UI の作成ウィンドウでユーザーに表示します。下書きは、新しいメッセージとして、または Gmail で開いたメッセージへの返信として作成できます。ハンドラは、ドラフト構築のコールバック関数を呼び出すと、コールバック関数にイベント オブジェクトを渡します。
詳しくは、メッセージの下書きを作成するをご覧ください。 |
setOnClickOpenLinkAction() |
ユーザーがウィジェットをクリックする |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックしたときに URL を開くように Action を設定します。このハンドラは、URL を構築する必要がある場合や、リンクを開く前にその他のアクションを実行する必要がある場合に使用します。それ以外の場合は通常、setOpenLink() を使用する方が簡単です。
URL は新しいウィンドウでのみ開くことができます。閉じると、UI でアドオンを再読み込みできます。 |
setOpenLink() |
ユーザーがウィジェットをクリックする |
CardActionImageImageButtonDecoratedTextTextButton
|
ユーザーがウィジェットをクリックすると、URL が直接開きます。URL がわかっていて、開く必要があるだけの場合は、このハンドラを使用します。それ以外の場合は、setOnClickOpenLinkAction() を使用します。
URL は、新しいウィンドウまたはオーバーレイで開くことができます。閉じると、UI でアドオンを再読み込みできます。 |
setSuggestionsAction() |
ユーザーが入力テキストを入力する |
TextInput
|
ユーザーがテキスト入力ウィジェットにテキストを入力したときに、Apps Script 関数を実行する Action を設定します。ハンドラは、呼び出すイベントにイベント オブジェクトを自動的に渡します。詳しくは、テキスト入力のオートコンプリート候補をご覧ください。 |
コールバック関数
コールバック関数は、Action がトリガーされたときに実行されます。コールバック関数は Apps Script の関数であるため、他のスクリプト関数とほぼ同じことができます。
コールバック関数から特定のレスポンス オブジェクトが返されることがあります。このようなレスポンスは、新しいカードの表示やオートコンプリートの候補の提示など、コールバックの実行が完了した後に必要な追加の操作を示します。コールバック関数が特定のレスポンス オブジェクトを返す必要がある場合は、カードサービスのビルダークラスを使用してそのオブジェクトを作成します。
次の表に、コールバック関数が特定のアクションに対して特定のレスポンス オブジェクトを返すタイミングを示します。これらのアクションはすべて、アドオンが拡張する特定のホストアプリに依存しません。
| 試行された操作 | コールバック関数が返される |
|---|---|
| カード間の移動 | ActionResponse |
Notificationを表示する |
ActionResponse |
setOnClickOpenLinkAction() を使用してリンクを開く |
ActionResponse |
| オートコンプリートの候補を表示する | SuggestionResponse |
| ユニバーサル アクションを使用する | UniversalActionResponse |
| その他の操作 | なし |
これらのアクションに加えて、各ホストアプリケーションには、そのホストでのみ実行できる独自のアクション セットがあります。詳細については、次のガイドをご覧ください。
アクション イベント オブジェクト
アドオンが Action をトリガーすると、UI により JSON イベント オブジェクトが自動的に構築され、引数として Action コールバック関数に渡されます。このイベント オブジェクトには、表示されるユーザーのカードに含まれるすべてのインタラクティブ ウィジェットの現在の値など、ユーザーの現在のクライアント側コンテキストに関する情報が含まれています。
アクション イベント オブジェクトには、オブジェクトに含まれる情報を整理する特定の JSON 構造があります。ホームページ トリガーが起動してホームページを作成する場合や、コンテキスト トリガーが起動してアドオン ディスプレイを更新する場合も同じ構造が使用されます。
イベント オブジェクトの構造の詳細については、イベント オブジェクトをご覧ください。