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

建構 Google 編輯器介面

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

存取外掛程式 UI

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

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 部分。外掛程式可擴充 Google 文件、試算表和簡報的功能，並在每個主機應用程式中顯示通用的首頁。

 "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 文件、試算表和簡報。這項功能會在 Google 文件和簡報中顯示通用的首頁，在試算表中顯示專屬的首頁。回呼函式 onSheetsHomepage 會建構 Sheets 專屬的首頁資訊卡。

 "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，因此 Google 試算表會納入 onFileScopeGrantedTrigger。使用者授予 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。觸發條件函式會使用事件物件中的資訊，判斷如何建構外掛程式資訊卡，或以其他方式控制外掛程式行為。

如要瞭解事件物件的完整結構，請參閱「事件物件」。

如果編輯器是外掛程式的代理主機應用程式，事件物件就會包含攜帶用戶端資訊的 Docs、Sheets 或簡報事件物件欄位。

如果外掛程式沒有目前使用者或文件的 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"
          },
          ...
        }