本頁面由 Cloud Translation API 翻譯而成。

建立 Google 編輯器介面

透過 Google Workspace 外掛程式，您可以在編輯器中提供自訂介面，包括 Google 文件、試算表和簡報。這可讓您為使用者提供相關資訊、自動執行工作，以及將第三方系統連結至編輯器。

存取外掛程式 UI

如果 Google Workspace 外掛程式圖示出現在文件、試算表和簡報使用者介面右側的 Google Workspace 快速存取側邊面板中，您就可以在編輯器中開啟 Google Workspace 外掛程式。

Google Workspace 外掛程式可以顯示下列介面：

首頁介面：如果外掛程式的資訊清單中包含用於使用者編輯器的觸發條件 EDITOR_NAME.homepageTrigger，該外掛程式會建構外掛程式，並傳回該編輯器專屬的首頁資訊卡。如果外掛程式的資訊清單中不含使用者開啟該編輯器的 EDITOR_NAME.homepageTrigger，就會改為顯示一般首頁資訊卡。
REST API 介面：如果外掛程式使用 REST API，您可以加入觸發條件，使用 drive.file 範圍要求每個檔案對文件的存取權。授予權限後，另一個名為 EDITOR_NAME.onFileScopeGrantedTrigger 的觸發條件就會執行並顯示檔案特有的介面。
連結預覽介面：如果您的外掛程式已與第三方服務整合，您就可以建構資訊卡來預覽服務網址中的內容。

建構編輯器外掛程式的介面

請按照下列步驟建構編輯器的編輯器外掛程式介面：

將適當的 addOns.common、addOns.docs、addOns.sheets 和 addOns.slides 欄位加入外掛程式指令碼專案的資訊清單資訊清單。
將任何必要的編輯器範圍新增至指令碼專案資訊清單。
如果您提供的是編輯器專屬的首頁，請實作 EDITOR_NAME.homepageTrigger 函式來建構介面。如果不是，請使用 common.homepageTrigger 介面為您的代管應用程式建構通用首頁。
如果您使用 REST API，請實作 drive.file 範圍授權流程和 EDITOR_NAME.onFileScopeGrantedTrigger 觸發條件函式，以顯示開啟檔案的專屬介面。詳情請參閱「REST API 介面」一文。
如要從第三方服務設定連結預覽，請實作 https://www.googleapis.com/auth/workspace.linkpreview 範圍授權流程和 linkPreviewTriggers 函式。詳情請參閱「連結預覽介面」。
實作回應使用者 UI 互動 (例如按鈕點擊) 所需的相關聯的回呼函式。

編輯器首頁

您必須在外掛程式的指令碼專案中提供首頁觸發條件函式，該函式建構並傳回單一 Card 或構成外掛程式首頁的 Card 物件陣列。

首頁觸發函式會將事件物件傳遞為參數，其中包含用戶端平台等資訊。您可以使用事件物件資料來調整首頁的結構。

您可以顯示使用者開啟外掛程式的通用首頁或首頁。

顯示一般首頁

如要在編輯器中顯示外掛程式的通用首頁，請在外掛程式的資訊清單中加入適當的編輯器欄位，例如 addOns.docs、addOns.sheets 或 addOns.slides。

以下範例顯示 Google Workspace 外掛程式資訊清單中的 addons 部分。外掛程式擴充了文件、試算表和簡報，並顯示每個主應用程式的一般首頁。

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

顯示編輯器專屬的首頁

如要顯示編輯器專屬的首頁，請在外掛程式資訊清單中加入 EDITOR_NAME.homepageTrigger。

以下範例顯示 Google Workspace 外掛程式資訊清單中的 addons 部分。 Google 文件、試算表和簡報均已啟用這個外掛程式。其中顯示文件和簡報中的一般首頁，以及試算表的專屬首頁。回呼函式 onSheetsHomepage 會建構 Google 試算表專屬的首頁資訊卡。

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

REST API 介面

如果您的外掛程式使用 REST API (例如 Google Sheets API)，您可以使用 onFileScopeGrantedTrigger 函式，顯示在編輯器主機應用程式中開啟檔案的專屬介面。

您必須加入 drive.file 範圍授權流程才能使用 onFileScopeGrantedTrigger 函式。如要瞭解如何要求 drive.file 範圍，請參閱「要求目前文件的檔案存取權」。

當使用者授予 drive.file 範圍時，EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 會啟動。觸發條件啟動時，會執行外掛程式資訊清單中 EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 欄位指定的關聯觸發條件函式。

如要為其中一個編輯器建立 REST API 介面，請按照下列步驟操作。將 EDITOR_NAME 替換為您選擇的編輯器主機應用程式，例如 sheets.onFileScopeGrantedTrigger。

在資訊清單的適當編輯器部分加入 EDITOR_NAME.onFileScopeGrantedTrigger。舉例來說，若要在 Google 試算表中建立這個介面，請將觸發條件新增至 "sheets" 區段。
實作 EDITOR_NAME.onFileScopeGrantedTrigger 區段中命名的函式。這個函式接受事件物件做為引數，且必須傳回單一 Card 物件或 Card 物件的陣列。
和所有資訊卡一樣，您必須實作回呼函式，為介面提供小工具互動。舉例來說，如果您在介面中加入按鈕，按鈕應會附加 Action，以及系統在使用者點選按鈕時執行的回呼函式。

以下範例顯示 Google Workspace 外掛程式資訊清單中的 addons 部分。這個外掛程式使用 REST API，因此 onFileScopeGrantedTrigger 可用於 Google 試算表。當使用者授予 drive.file 範圍時，回呼函式 onFileScopeGrantedSheets 會建構檔案專屬介面。

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

第三方服務的連結預覽介面

如要啟用第三方服務的連結預覽，您必須在外掛程式的資訊清單中設定連結預覽，並建立傳回預覽資訊卡的函式。如果服務需要使用者授權，您的函式也必須叫用授權流程。

開啟連結預覽的步驟請參閱「使用智慧型方塊預覽連結」。

事件物件

系統會建立事件物件，並傳遞至觸發條件函式，例如 EDITOR_NAME.homepageTrigger 或 EDITOR_NAME.onFileScopeGrantedTrigger。觸發函式會使用事件物件中的資訊，決定如何建構外掛程式資訊卡或控制外掛程式行為。

事件物件的完整結構請參閱「事件物件」一文。

如果編輯器是外掛程式運作的主機應用程式，事件物件會包含用於收集用戶端資訊的文件、試算表或簡報事件物件欄位。

如果外掛程式沒有目前使用者或文件的 drive.file 範圍授權，事件物件只會包含 docs.addonHasFileScopePermission、sheets.addonHasFileScopePermission 或 slides.addonHasFileScopePermission 欄位。如果外掛程式確實獲得授權，事件物件就會包含所有編輯器事件物件欄位。

以下範例顯示傳遞至 sheets.onFileScopeGrantedTrigger 函式的編輯器事件物件。這裡的外掛程式具備目前文件的 drive.file 範圍授權：

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }