使用 Google Picker 網頁元件

Google Picker 網頁元件提供另一種方式，可將 Google Picker API 整合至網頁應用程式。

這個網頁元件可簡化 Google 雲端硬碟檔案選取功能與網頁應用程式的整合程序。它會將所有樣板 API 載入和驗證邏輯包裝成單一 HTML 元素。您不必編寫 gapi 載入邏輯，就能直接將 <drive-picker> 代碼放入程式碼中。這項功能可用於純 HTML 和 JavaScript，且與架構無關，可與 Svelte、Vue、Angular 等架構順暢搭配使用。

如要進一步瞭解網頁元件程式庫，請參閱 @googleworkspace/drive-picker-element。

如果是 React 應用程式，請使用網頁元件的官方 React 包裝函式套件： @googleworkspace/drive-picker-react。

主要功能與特色

  • 整合簡單：只需幾行程式碼，即可在網路應用程式中加入 Google 挑選器。
  • 不限架構：可與您選擇的任何網頁架構 (React、Vue、Angular 等) 順暢搭配使用。
  • 開放原始碼且可自訂：程式碼可免費取得，您可以根據特定需求自訂。
  • 無縫 OAuth 支援：自動處理使用者驗證，提供流暢的使用者體驗。
  • 可自訂的檢視畫面：設定屬性，讓 Google 挑選器只顯示您需要的檔案類型或檢視畫面。

開始使用

  1. 使用 NPM 或類似工具安裝元件：

    npm i @googleworkspace/drive-picker-element

    您也可以使用 CDN 版本。如要瞭解可用的格式和版本，請參閱 unpkg。

    <script src="https://unpkg.com/@googleworkspace/drive-picker-element@latest/dist/index.iife.min.js"></script>

  2. 將 @googleworkspace/drive-picker-element 元件匯入 JavaScript 檔案：

    import "@googleworkspace/drive-picker-element";

    如果您使用 CDN 版本，系統會自動載入 Google Picker 程式庫和用於驗證的 Google API 用戶端程式庫，因此不需要匯入。

  3. 將自訂元素新增至 HTML 檔案：

    <drive-picker>
    <drive-picker-docs-view></drive-picker-docs-view>
</drive-picker>

    如需 <drive-picker/> 和 <drive-picker-docs-view/> 屬性和屬性，請參閱 @googleworkspace/drive-picker-element 的參考文件。

事件

<drive-picker/> 元素會傳送下列自訂事件：

事件 說明
picker-picked 使用者選取一或多個項目時觸發。
picker-canceled 使用者點選「取消」按鈕或關閉對話方塊 (未選取任何項目) 時觸發。
picker-error 初始化或選取檔案時發生錯誤時觸發。

如要進一步瞭解事件，請參閱 NPM 的@googleworkspace/drive-picker-element說明文件。

活動詳細資料

如果是 picker-picked 事件，事件詳細資料會包含完整的 Google 挑選器 ResponseObject。

{
  "type": "picker-picked",
  "detail": {
    "action": "PICKED",
    "docs": [
      {
        "id": ID,
        "mimeType": "application/pdf",
        "name": NAME,
        "url": "https://drive.google.com/file/d/ID/view?usp=drive_web",
        "sizeBytes": 12345
      }
    ]
  }
}

回應物件中最常用的屬性包括：

  • action：觸發回呼的動作 (例如 PICKED)。
  • docs：使用者選取的 DocumentObject 陣列。每個物件都包含下列屬性：
    • id：所選項目的專屬 ID。
    • mimeType：項目的 MIME 類型。
    • name：項目的名稱。
    • url：在 Google 雲端硬碟中開啟項目的網址。
    • sizeBytes：所選項目的大小 (以位元組為單位)。上傳項目時，系統不會傳回值。

如果是 picker-error 事件，event.detail 包含描述失敗情形的錯誤物件或字串 (例如 ERR_USER_NOT_AUTHENTICATED)。

範例

下列程式碼範例說明如何針對常見用途使用 Google Picker 網頁元件。請針對每個程式碼範例，替換下列項目：

PDF 檔案

使用 mime-types 屬性篩選檢視畫面，只顯示 PDF 檔案。

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view mime-types="application/pdf"></drive-picker-docs-view>
</drive-picker>

圖片和影片檔案

使用 mime-types 屬性篩選檢視畫面，只顯示圖片 (JPEG、PNG) 和影片 (MP4、QuickTime) 檔案。

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view mime-types="image/jpeg,image/png,video/mp4,video/quicktime"></drive-picker-docs-view>
</drive-picker>

我擁有的檔案

使用 owned-by-me 屬性篩選檢視畫面，只顯示目前使用者擁有的檔案。

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view owned-by-me="true"></drive-picker-docs-view>
</drive-picker>

查詢未命名的檔案

使用 query 屬性篩選檢視畫面，顯示符合「未命名」搜尋查詢的檔案。

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view query="Untitled"></drive-picker-docs-view>
</drive-picker>

已加星號的檔案

使用 starred 屬性篩選檢視畫面，只顯示已加星號的檔案。

<drive-picker
  prompt="PROMPT"
  origin="ORIGIN"
  app-id="APP_ID"
  client-id="CLIENT_ID"
>
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>
  • 如要深入瞭解屬性、事件和屬性，請參閱 GitHub 上的完整drive-picker-element說明文件。