建構 Google 編輯器介面

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

存取外掛程式 UI

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

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

  • 首頁介面:如果外掛程式的資訊清單 包含觸發條件 編輯器的 EDITOR_NAME.homepageTrigger 權限,表示使用者開啟外掛程式, 外掛程式版本,並傳回 首頁資訊卡 如果外掛程式的資訊清單未包含 EDITOR_NAME.homepageTrigger:使用者開啟的編輯器 就會改為顯示一般首頁資訊卡

  • REST API 介面:如果外掛程式使用 REST API,您可以加入會要求每個檔案存取文件的觸發條件 使用 drive.file 範圍授予後,又會呼叫另一個觸發條件 EDITOR_NAME.onFileScopeGrantedTrigger 會執行 會顯示檔案專屬的介面

  • 連結預覽介面:如果外掛程式 整合第三方服務,您可以製作資訊卡 將其網址移除。

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

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

  1. 新增適當的 addOns.commonaddOns.docsaddOns.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. 實作回應使用者的回呼所需的關聯回呼函式 使用者介面互動,例如按鈕點擊。

編輯器首頁

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

首頁觸發函式會傳送事件物件 做為包含客戶平台等資訊的參數。你可以 使用事件物件資料來自訂首頁的結構。

你可以顯示編輯器專屬的通用首頁或首頁 使用者開啟您的外掛程式

顯示通用首頁

如要在編輯器中顯示外掛程式的通用首頁,請加入適當的 編輯器欄位,例如 addOns.docsaddOns.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 試算表的獨特首頁回呼 函式 onSheetsHomepage 可建立試算表專用的首頁資訊卡。

 "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 造成的傷害。觸發條件啟動時,會執行內容相關觸發條件函式 指定的 Pod 中 EDITOR_NAME.onFileScopeGrantedTrigger.runFunction 欄位 外掛程式資訊清單。

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

  1. 加入 EDITOR_NAME.onFileScopeGrantedTrigger 與資訊清單相應的編輯器部分中舉例來說,如果您在 想在 Google 試算表中建立這個介面,請將觸發條件 "sheets" 部分。
  2. 實作 EDITOR_NAME.onFileScopeGrantedTrigger 中命名的函式 專區。此函式接受事件物件做為引數,且必須傳回單一 Card敬上 Card 物件的陣列或陣列。
  3. 與任何卡片一樣,您必須實作用於提供的回呼函式,以提供 介面小工具的互動功能。舉例來說,如果您在廣告素材中加入按鈕 介面中應有附加的 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.addonHasFileScopePermissionsheets.addonHasFileScopePermissionslides.addonHasFileScopePermission 欄位中。如果外掛程式 授權,事件物件會包含所有編輯器事件物件欄位。

下例顯示將傳送到 sheets.onFileScopeGrantedTrigger 函式。這個外掛程式提供 目前文件的drive.file範圍授權

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