使用 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 选择器添加到您的 Web 应用中。
  • 独立于框架：可与您选择的任何 Web 框架（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 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 文件选择器 Web 组件。对于每个代码示例，请替换以下内容：

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