編輯器動作

請使用 Action 物件在 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 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 觸發條件。

要求目前文件的檔案存取權

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

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