建構 Google 編輯器介面

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

存取外掛程式 UI

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

Google Workspace 外掛程式可呈現下列介面：

  • 首頁介面：如果外掛程式的資訊清單包含使用者開啟外掛程式的編輯器觸發條件 EDITOR_NAME.homepageTrigger，外掛程式會建構並傳回專為該編輯器設計的首頁資訊卡。如果外掛程式的資訊清單未包含使用者開啟外掛程式的編輯器專用 EDITOR_NAME.homepageTrigger，系統會改為顯示一般首頁資訊卡。

  • REST API 介面：如果外掛程式使用 REST API，您可以加入觸發條件，透過 drive.file 範圍要求文件檔案存取權。獲得授權後，系統會執行另一個名為 EDITOR_NAME.onFileScopeGrantedTrigger 的觸發條件，並顯示檔案專屬的介面。

  • 連結預覽介面：如果外掛程式與第三方服務整合，您可以建構資訊卡，預覽服務網址的內容。

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

按照下列步驟，為編輯器建立編輯器外掛程式介面：

  1. 將適當的addOns.common、addOns.docs、addOns.sheets 和 addOns.slides 欄位新增至外掛程式指令碼專案的資訊清單。
  2. 將所有必要的編輯器範圍新增至指令碼專案資訊清單。
  3. 如果您提供編輯器專屬首頁，請實作 EDITOR_NAME.homepageTrigger 函式來建構介面。如果沒有，請使用 common.homepageTrigger 介面，為主機應用程式建立通用首頁。
  4. 如果您使用 REST API，請實作 drive.file 範圍授權流程和 EDITOR_NAME.onFileScopeGrantedTrigger 觸發函式，顯示特定於開啟檔案的介面。詳情請參閱 REST API 介面。
  5. 如要透過第三方服務設定連結預覽功能，請實作 https://www.googleapis.com/auth/workspace.linkpreview 範圍授權流程和 linkPreviewTriggers 函式。詳情請參閱「連結預覽介面」。
  6. 實作相關聯的回呼函式，以便回應使用者的 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 文件和簡報會顯示相同的首頁，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 函式，顯示專為在編輯器主機應用程式中開啟的檔案設計的新介面。

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

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

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

  1. 在資訊清單的適當編輯器區段中加入 EDITOR_NAME.onFileScopeGrantedTrigger。舉例來說，如要在 Google 試算表中建立這個介面，請將觸發條件新增至 "sheets" 區段。
  2. 實作 EDITOR_NAME.onFileScopeGrantedTrigger 區段中命名的函式。這個函式會接受 event 物件做為引數，且必須傳回單一 Card 物件或 Card 物件陣列。
  3. 與任何資訊卡一樣，您必須實作回呼函式，為介面提供小工具互動功能。舉例來說，如果您在介面中加入按鈕，該按鈕應附加 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。觸發函式會使用事件物件中的資訊，判斷如何建構外掛程式資訊卡，或以其他方式控制外掛程式行為。

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

如果編輯器是外掛程式的代管應用程式，事件物件會包含「文件」、「試算表」或「簡報」事件物件欄位，其中含有用戶端資訊。

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