編集者のアクション

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

アクション オブジェクトを使用して、インタラクティブな動作をアドオンに Google Workspace 組み込みます。

アクション オブジェクトは、ユーザーがアドオン UI でウィジェット(ボタンなど)を操作したときに発生する操作を定義します。

ウィジェットにアクションを追加する

ウィジェットにアクションを接続するには、ウィジェット ハンドラ関数を使用します。この関数は、アクションをトリガーする条件も定義します。アクションがトリガーされると、指定されたコールバック関数が実行されます。コールバック関数には、ユーザーのクライアント側操作に関する情報を保持するイベント オブジェクトが渡されます。コールバック関数を実装し、特定のレスポンス オブジェクトを返すようにする必要があります。

例: ボタンがクリックされたときに新しいカードを表示する

クリックして新しいカードを作成して表示するボタンをアドオンに追加する場合は、次の手順を行います。

  1. 新しいボタン ウィジェットを作成します。
  2. カード作成アクションを設定するには、ボタン ウィジェット ハンドラ関数 setOnClickAction(action) を追加します。
  3. 実行する 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 isused 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 でのファイル アクセスのインタラクション

Google Workspace エディタを拡張し、REST API を使用するアドオンには、ファイル アクセスをリクエストするためのウィジェット アクションを追加できます。このアクションを行うには、関連するアクション コールバック関数で特別なレスポンス オブジェクトを返す必要があります。

試行された操作 コールバック関数が返される
current_document のファイルへのアクセスをリクエスト EditorFileScopeActionResponse

このウィジェットのアクション オブジェクトとレスポンス オブジェクトを利用するには、以下のすべての条件を満たす必要があります。

  • このアドオンでは REST API を使用します。
  • アドオンは、CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); を使用してリクエスト ファイル スコープのダイアログを表示します。
  • このアドオンは、マニフェストに https://www.googleapis.com/auth/drive.file エディタ スコープを追加します。

現在のドキュメントへのアクセスをリクエスト

現在のドキュメントへのファイル アクセスをリクエストする手順は次のとおりです。

  1. ホームページに、アドオンの drive.file スコープがあるかどうかを確認するカードを作成します。
  2. アドオンに 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(docsEventObject);
}

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();
}