Action オブジェクトを使用して、Google Workspace アドオンにインタラクティブな動作を組み込みます。
アクション オブジェクトは、ユーザーがアドオン UI のウィジェット(ボタンなど)を操作したときに何が起こるかを定義します。
ウィジェットにアクションを追加する
ウィジェットにアクションを関連付けるには、ウィジェット ハンドラ関数を使用します。この関数では、アクションをトリガーする条件も定義します。トリガーされると、アクションは指定されたコールバック関数を実行します。コールバック関数には、ユーザーのクライアントサイドの操作に関する情報を含むイベント オブジェクトが渡されます。コールバック関数を実装し、特定のレスポンス オブジェクトを返すようにする必要があります。
例: ボタンがクリックされたときに新しいカードを表示する
クリックすると新しいカードを作成して表示するボタンをアドオンに追加するには、次の手順を行います。
- ボタンのウィジェットを作成します。
- カード作成アクションを設定するには、ボタン ウィジェット ハンドラ関数
setOnClickAction(action)
を追加します。 - 実行する Apps Script コールバック関数を作成し、ウィジェット ハンドラ関数内の
(action)
として指定します。この場合、コールバック関数は必要なカードを作成し、ActionResponse
オブジェクトを返す必要があります。レスポンス オブジェクトは、コールバック関数が作成したカードを表示するようアドオンに指示します。
次の例は、ボタン ウィジェットの作成方法を示しています。このアクションは、アドオンに代わって現在のファイルの drive.file
スコープをリクエストします。
/** * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button. * When it's clicked, the callback triggers file scope permission flow. This is used in * the add-on when the home-page displays basic data. */ function addRequestFileScopeButtonToBuilder(cardBuilder) { var buttonSection = CardService.newCardSection(); // If the add-on does not have access permission, add a button that // allows the user to provide that permission on a per-file basis. var buttonAction = CardService.newAction() .setFunctionName("onRequestFileScopeButtonClickedInEditor"); var button = CardService.newTextButton() .setText("Request permission") .setBackgroundColor("#4285f4") .setTextButtonStyle(CardService.TextButtonStyle.FILLED) .setOnClickAction(buttonAction); buttonSection.addWidget(button); cardBuilder.addSection(buttonSection); } /** * Callback function for a button action. Instructs Docs to display a * permissions dialog to the user, requesting `drive.file` scope for the * current file on behalf of this add-on. * * @param {Object} e The parameters object that contains the document’s ID * @return {editorFileScopeActionResponse} */ function onRequestFileScopeButtonClickedInEditor(e) { return CardService.newEditorFileScopeActionResponseBuilder() .requestFileScopeForActiveDocument().build();
REST API のファイル アクセス操作
エディタを拡張し、REST API を使用する Google Workspace アドオンには、ファイル アクセスをリクエストする追加のウィジェット アクションを含めることができます。このアクションでは、関連付けられたアクション コールバック関数が特殊なレスポンス オブジェクトを返す必要があります。
試行した操作 | コールバック関数は |
---|---|
current_document のファイル アクセスをリクエスト | EditorFileScopeActionResponse |
このウィジェットのアクション オブジェクトとレスポンス オブジェクトを利用するには、次の条件をすべて満たしている必要があります。
- アドオンは REST API を使用します。
- アドオンは
CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
メソッドを使用してリクエスト ファイル スコープ ダイアログを表示します。 - アドオンのマニフェストに
https://www.googleapis.com/auth/drive.file
エディタ スコープとonFileScopeGranted
トリガーが含まれています。
現在のドキュメントのファイル アクセスをリクエストする
現在のドキュメントのファイル アクセスをリクエストする手順は次のとおりです。
- アドオンに
drive.file
スコープがあるかどうかを確認するホームページ カードを作成します。 - アドオンに
drive.file
スコープが付与されていない場合は、ユーザーが現在のドキュメントにdrive.file
スコープを付与するようリクエストする方法を構築します。
例: Google ドキュメントで現在のドキュメントのアクセス権を取得する
次の例では、現在のドキュメントのサイズを表示する Google ドキュメントのインターフェースを構築します。アドオンに drive.file
認証がない場合は、ファイル スコープの認証を開始するボタンが表示されます。
/**
* Build a simple card that checks selected items' quota usage. Checking
* quota usage requires user-permissions, so this add-on provides a button
* to request `drive.file` scope for items the add-on doesn't yet have
* permission to access.
*
* @param e The event object passed containing information about the
* current document.
* @return {Card}
*/
function onDocsHomepage(e) {
return createAddOnView(e);
}
function onFileScopeGranted(e) {
return createAddOnView(e);
}
/**
* For the current document, display either its quota information or
* a button that allows the user to provide permission to access that
* file to retrieve its quota details.
*
* @param e The event containing information about the current document
* @return {Card}
*/
function createAddOnView(e) {
var docsEventObject = e['docs'];
var builder = CardService.newCardBuilder();
var cardSection = CardService.newCardSection();
if (docsEventObject['addonHasFileScopePermission']) {
cardSection.setHeader(docsEventObject['title']);
// This add-on uses the recommended, limited-permission `drive.file`
// scope to get granular per-file access permissions.
// See: https://developers.google.com/drive/api/v2/about-auth
// If the add-on has access permission, read and display its quota.
cardSection.addWidget(
CardService.newTextParagraph().setText(
"This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
} else {
// If the add-on does not have access permission, add a button that
// allows the user to provide that permission on a per-file basis.
cardSection.addWidget(
CardService.newTextParagraph().setText(
"The add-on needs permission to access this file's quota."));
var buttonAction = CardService.newAction()
.setFunctionName("onRequestFileScopeButtonClicked");
var button = CardService.newTextButton()
.setText("Request permission")
.setOnClickAction(buttonAction);
cardSection.addWidget(button);
}
return builder.addSection(cardSection).build();
}
/**
* Callback function for a button action. Instructs Docs to display a
* permissions dialog to the user, requesting `drive.file` scope for the
* current file on behalf of this add-on.
*
* @param {Object} e The parameters object that contains the document’s ID
* @return {editorFileScopeActionResponse}
*/
function onRequestFileScopeButtonClicked(e) {
return CardService.newEditorFileScopeActionResponseBuilder()
.requestFileScopeForActiveDocument().build();
}