編輯器動作

使用 Action 物件建立互動式 行為嵌入 Google Workspace 外掛程式

動作物件會定義使用者與小工具互動時會發生什麼事 (例如按鈕)。

在小工具中新增動作

如要將動作附加至小工具，請使用小工具處理常式函式。 這也會定義觸發動作的條件。觸發後 動作會執行指定的回呼函式。 系統會將回呼函式傳送至事件物件 這個 API 可提供有關使用者用戶端互動的資訊。您必須 實作回呼函式，並使其傳回特定的回應物件。

範例：在點選按鈕時顯示新資訊卡

如要在建構的外掛程式中新增按鈕並顯示新資訊卡 請在使用者點擊時執行下列步驟：

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 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

如要使用這個小工具動作和回應物件，必須完成以下所有設定 為 true：

• 外掛程式會使用 REST API。
• 這個外掛程式顯示要求檔案範圍對話方塊 方法是使用 CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); 方法
• 這個外掛程式包含 https://www.googleapis.com/auth/drive.file 位編輯者範圍和 onFileScopeGranted 觸發條件。

要求存取目前文件的檔案

如果想為目前的文件要求檔案存取權，請按照下列步驟操作：

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