使用 Google 选择器 Web 组件

Google Picker Web 组件提供了一种将 Google Picker API 集成到 Web 应用中的额外方式。

借助 Web 组件，您可以轻松地将 Google 云端硬盘文件选择功能集成到 Web 应用中。它将所有样板 API 加载和身份验证逻辑封装到一个 HTML 元素中。您可以将 <drive-picker> 标记直接放入 代码中，而无需编写 gapi 加载逻辑。它可用于纯 HTML 和 JavaScript，并且与框架无关，可与 Svelte、Vue、Angular 等框架无缝协作。

如需详细了解 Web 组件库，请参阅 @googleworkspace/drive-picker-element。

对于 React 应用，请使用 Web 组件的官方 React 封装容器软件包： @googleworkspace/drive-picker-react。

主要特性

• 集成简单明了： 只需几行代码，即可将 Google Picker 添加到 Web 应用中。
• 与框架无关： 可与您选择的任何 Web 框架（React、Vue、Angular 等）无缝协作。
• 开源且可自定义： 代码可免费获取，您可以根据自己的具体需求进行自定义。
• 无缝 OAuth 支持： 自动处理用户身份验证，提供顺畅的用户体验。
• 可自定义的视图： 通过设置属性，将 Google Picker 配置为仅显示您需要的文件类型或视图。

开始使用

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/> 元素会调度以下自定义事件：

如需详细了解事件，请参阅 NPM 上的 @googleworkspace/drive-picker-element 文档。

事件详情

对于 picker-picked 事件，事件详情包含完整的 Google Picker 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：所选项目的唯一标识符。
  • mimeType：项目的 MIME 类型。
  • name：推荐项的名称。
  • url：在云端硬盘中打开项目的网址。
  • sizeBytes：所选项目的大小（以字节为单位）。上传项目时不会返回该值。

对于 picker-error 事件，event.detail 包含一个错误对象或字符串，用于描述失败情况（例如 ERR_USER_NOT_AUTHENTICATED）。

示例

以下代码示例展示了如何将 Google Picker Web 组件用于常见用例。对于每个代码示例，请替换以下内容：

• PROMPT：以空格分隔的 Google 账号授权提示列表（区分大小写），用于向用户显示提示。如需了解详情，请参阅 TokenClientConfig.prompt。

• ORIGIN：Picker 的来源参数。例如，https://developers.google.com。如需了解详情，请参阅 PickerBuilder.setOrigin 方法。

• APP_ID：云端硬盘应用 ID。如需了解详情，请参阅 PickerBuilder.setAppId 方法。

• CLIENT_ID：OAuth 2.0 客户端 ID。如需了解详情， 请参阅使用 OAuth 2.0 访问 Google API。

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 文档。