# @googleworkspace/drive-picker-element 中文文档

规范地址：https://npmcn.com/package/%40googleworkspace/drive-picker-element/

版本：0\.7\.3
npm 元数据更新时间：2025-12-09T17:05:48.100Z
中文译文更新时间：2026-11-16T19:56:30.627Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40googleworkspace/drive-picker-element
原文对照：https://npmcn.com/package/%40googleworkspace/drive-picker-element/?lang=original
项目主页：https://github.com/googleworkspace/drive-picker-element
源码仓库：https://github.com/googleworkspace/drive-picker-element

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：303 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-08-19T21:38:49.645Z
- 最新版本发布：2025-12-09T17:05:47.639Z
- 近 30 天下载量：822737（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 6 个）

## 中文简介

Google Drive Picker 的网络组件

## 安装

```sh
npm install @googleworkspace/drive-picker-element
```

也可以使用：`pnpm add @googleworkspace/drive-picker-element`、`yarn add @googleworkspace/drive-picker-element`、`bun add @googleworkspace/drive-picker-element`

## README

[![npm](https://img.shields.io/npm/v/@googleworkspace/drive-picker-element)](https://www.npmjs.com/package/@googleworkspace/drive-picker-element) [![Test](https://github.com/googleworkspace/drive-picker-element/actions/workflows/test.yml/badge.svg)](https://github.com/googleworkspace/drive-picker-element/actions/workflows/test.yml) ![Release](https://github.com/googleworkspace/drive-picker-element/workflows/Release/badge.svg)

## 说明

这个 [谷歌驱动拾取器](https://developers.google.com/drive/picker/guides/overview) web组件提供了一个无缝的方法,将Google Picker API整合到您的网络应用程序中. 这个组件是框架不可知的,意思是它与React,Svelte,Vue,Angular,等等一起无功而返.

Google Picker API是一个JavaScript API,允许用户选择或上传Google Drive文件. 这个组件充当"File Open"对话框,提供访问和与Google Drive所存储文件的交互.

探索 [故事书演示](https://googleworkspace.github.io/drive-picker-element/?path=/docs/stories-drive-picker--docs) 将组成部分付诸行动.

见框架的具体组成部分:

-   [反应](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-react)

## 指数

-   [安装](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-install)
-   [使用量](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-usage)
    -   [导入组件](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-import-the-component)
    -   [将组件添加到您的 HTML](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-add-the-component-to-your-html)
    -   [使用 `oauth-token` 属性](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-use-the-oauth-token-attribute)
    -   [倾听事件](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-listening-to-events)
    -   [事件详情](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-event-details)
    -   [控制可见度](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-controlling-visibility)
    -   [反应](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-react)
    -   [内容安全政策](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-content-security-policy-csp)
-   [支助](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-support)
-   [参考文献](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-reference)
    -   [`<drive-picker/>`](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-drive-picker)
    -   [`<drive-picker-docs-view/>`](https://npmcn.com/package/%40googleworkspace/drive-picker-element/#readme-drive-picker-docs-view)

## 安装

利用国家预防机制或类似机制安装.

```sh
npm i @googleworkspace/drive-picker-element
```

还有一个CDN版本. 见 [(单位:公斤)](https://unpkg.com/browse/@googleworkspace/drive-picker-element/dist/)。 。 。 .

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

## 使用量

用来使用 `drive-picker` 请遵循这些步骤:

### 导入组件

首先导入 `drive-picker` 在 JavaScript 文件的组件 :

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

如果你使用CDN版本,这是没有必要的.

### 将组件添加到您的 HTML

下一个,添加 `drive-picker` hTML 文件的组件。 替换 `YOUR_CLIENT_ID` 财务报告和审定财务报表 `YOUR_APP_ID` 你的客户身份和应用程序身份.

> 注意: 您可以在 [谷歌云控台](https://console.cloud.google.com/) “APIS & Services” > “证书”。 您也可以遵循此指南 [创建新的 OAuth 2. 0 客户端ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid)。 。 。 .

```html
<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID">
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>
```

> 注意:如果想要注册不同名称的组件,可以单独导入组件并呼叫 `customElements.define()` 手动 :

```js
import {
  DrivePickerElement,
  DrivePickerDocsViewElement,
} from "@googleworkspace/drive-picker-element/drive-picker";
customElements.define("custom-drive-picker", DrivePickerElement);
customElements.define(
  "custom-drive-picker-docs-view",
  DrivePickerDocsViewElement,
);
```

### 使用 `oauth-token` 属性

如果你已经有一个OAuth的标志, 你可以把它传递给 `drive-picker` 使用 `oauth-token` 属性。 这将认证用户,而不要求他们再次签名 .

```html
<drive-picker app-id="YOUR_APP_ID" oauth-token="OAUTH_TOKEN"></drive-picker>
```

如果你没有OAuth标志,你可以听 `"picker-oauth-response"` 在用户认证后获取符号的事件。 这个库包 [Google 身份服务图书馆](https://developers.google.com/identity/oauth2/web/guides/overview) 以方便用户认证.

### 倾听事件

这个 `drive-picker` 组件释放您可以听取的多个事件。 以下是如何倾听这些事件的例子:

```html
<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID">
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>

<script>
  const element = document.querySelector("drive-picker");
  element.addEventListener("picker-oauth-response", console.log);
  element.addEventListener("picker-oauth-error", console.log);
  element.addEventListener("picker-picked", console.log);
  element.addEventListener("picker-canceled", console.log);
</script>
```

### 事件详情

大部分事件还原 [`Picker ResponseObject`](https://developers.google.com/drive/picker/reference/picker.responseobject) 作为事件的细节。 例如 `"picker-picked"` `CustomEvent` 包含所选文件的详情 :

```js
{
  "type": "picker-picked",
  "detail": {
    "action": "picked",
    "docs": [
      {
        "id": "OMITTED",
        "mimeType": "application/pdf",
        "name": "OMITTED",
        "url": "https://drive.google.com/file/d/OMITTED/view?usp=drive_web",
        "sizeBytes": 12345
        // ... other properties omitted
      }
    ]
  }
}
```

这个 `"picker-oauth-response"` 事件返回 OAuth 符号响应作为事件细节 :

```js
{
  "type": "picker-oauth-response",
  "detail": {
    "access_token": "OMITTED",
    "expires_in": 3599,
    "scope": "https://www.googleapis.com/auth/drive.file",
    "token_type": "Bearer"
  }
}
```

### 控制可见度

为了让拾取者可见,设置 `visible` 财产的财产 `drive-picker` 元素到 `true`数字 :

```html
<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID"></drive-picker>

<script>
  const element = document.querySelector("drive-picker");
  element.visible = true;
</script>
```

拾取器对话框关闭后 `visible` 属性将重置为 `false`。 。 。 .

### 反应

对于反应应用,我们建议使用官方反应包装包: [`@googleworkspace/drive-picker-react`](https://www.npmjs.com/package/@googleworkspace/drive-picker-react)。 。 。 .

请参看 [软件包文档](https://github.com/googleworkspace/drive-picker-element/tree/main/packages/drive-picker-react) 用于使用指令.

### 内容安全政策

此库动态地加载 Google API 脚本(`https://apis.google.com/js/api.js` 财务报告和审定财务报表 `https://accounts.google.com/gsi/client`如果它们还没有出现。 这可能会违反严格的CSP设置,不允许动态脚本注入或限制脚本来源.

在严格的CSP环境中使用此库:

1.  **预装脚本**: 使用 HTML 手动将 Google API 脚本包含在您的 HTML 中 `<script>` 符合您的 CSP 标签( 例如, 使用 `nonce` 或允许域).
    
    ```html
    <script src="https://apis.google.com/js/api.js" async defer></script>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    ```
    
2.  **确保全球对象可用**: 图书馆检查 `window.gapi` 财务报告和审定财务报表 `window.google.accounts.oauth2`如果这些都存在,它会跳过动态注射.
    
3.  **允许 CSP 中的 Google 域**: 您必须允许拾取者的出处和其他 Google 域名 `Content-Security-Policy`。这里有一个完整的例子:
    
    ```http
    Content-Security-Policy:
      default-src 'self';
      script-src 'self' https://apis.google.com https://accounts.google.com;
      frame-src 'self' https://docs.google.com https://drive.google.com https://accounts.google.com;
      style-src 'self' 'unsafe-inline';
      img-src 'self' https://*.googleusercontent.com;
      connect-src 'self' https://*.googleapis.com;
      font-src 'self' https://fonts.gstatic.com;
    ```
    
    **注释:**
    
    -   这个 `frame-src` picker iframe和认证需要域。 确切的域可能不同,但这些是最常见的.
    -   `style-src: 'unsafe-inline'` 由 Picker 注入的一些样式可能需要。 对于更严格的政策,你可以使用 [无](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src#unsafe_inline_styles)。 。 。 .

**Chrome扩展(Manifest V3)的说明:** 基本的 Google Picker API 依赖 `gapi`,这是 [在 Express V3 扩展中不支持](https://github.com/google/google-api-javascript-client/blob/master/docs/start.md#supported-environments)因此,不管CSP设置如何,此库可能不会在这个环境中运行.

## 支助

请使用 [Google Picker 发行跟踪器](https://developers.google.com/drive/picker/support#developer_product_feedback)关于所有其他问题,请使用 [GitHub 问题跟踪器](https://github.com/googleworkspace/drive-picker-element/issues)。 。 。 .

## 参考文献

### `<drive-picker/>`

这个 `drive-picker` 网络组件提供了一种方便的宣示方式 构建 [`google.picker.Picker`](https://developers.google.com/drive/picker/reference/picker) 使用绘图到相应方法的组件属性 [`google.picker.PickerBuilder`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder)。 。 。 .

#### 属性

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `app-id` | `string` | Google Drive app ID (英语). 见 [`PickerBuilder.setAppId`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setappid)。 。 。 . |
| `client-id` | `string` | OAuth 2.0客户端ID. 见 [使用 OAuth 2. 0 访问 Google API](https://developers.google.com/identity/protocols/oauth2)。 。 。 . |
| `debounce-delay` | `number` | 属性改变后在建立取取取器前以毫秒表示的解跳延迟. |
| `developer-key` | `string` | 访问Google Picker API的API密钥. 见 [`PickerBuilder.setDeveloperKey`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setdeveloperkey)。 。 。 . |
| `hide-title-bar` | `"default"|"true"|"false"` | 如果设置为真,则隐藏拾取者的标题栏。 见 [`PickerBuilder.hideTitleBar`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.hidetitlebar)。 。 。 . |
| `locale` | `string` | 取取者所用之地. 见 [`PickerBuilder.setLocale`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setlocale)。 。 。 . |
| `max-items` | `number` | 可选择项目的最大数量 。 见 [`PickerBuilder.setMaxItems`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setmaxitems)。 。 。 . |
| `mine-only` | `boolean` | 如果设置为真, 只显示用户拥有的文件 。 见 [`PickerBuilder.enableFeature`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.enablefeature)。 。 。 . |
| `multiselect` | `boolean` | 如果设置为真, 启用多个文件选择 。 见 [`PickerBuilder.enableFeature`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.enablefeature)。 。 。 . |
| `nav-hidden` | `boolean` | 如果设置为真, 则隐藏导航窗格。 见 [`PickerBuilder.enableFeature`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.enablefeature)。 。 。 . |
| `oauth-token` | `string` | OAuth 2.0 认证符. 见 [`PickerBuilder.setOAuthToken`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setoauthtoken)。 。 。 . |
| `origin` | `string` | 采取器的起源参数 。 见 [`PickerBuilder.setOrigin`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setorigin)。 。 。 . |
| `relay-url` | `string` | 拾取器的中继 URL 。 见 [`PickerBuilder.setRelayUrl`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.setrelayurl)。 。 。 . |
| `scope` | `string` | 摘取者OAuth 2.0范围. 默认是 `https://www.googleapis.com/auth/drive.file`。见 [驱动 API 瞄准镜](https://developers.google.com/drive/api/guides/api-specific-auth#drive-scopes)。 。 。 . |
| `title` | `string` | 取取者所取之名. 见 [`PickerBuilder.setTitle`](https://developers.google.com/drive/picker/reference/picker.pickerbuilder.settitle)。 。 。 . |
| `hd` | `string` | 主机域限制登录到 。 (备选) 见 `hd` 字段. |
| `include-granted-scopes` | `boolean` | 允许应用程序使用递增授权. 见 [`TokenClientConfig.include_granted_scopes`](https://developers.google.com/identity/oauth2/web/reference/js-reference#TokenClientConfig)。 。 。 . |
| `login-hint` | `string` | 电子邮件地址或ID标志"sub"值 。 Google 将使用该值作为提示哪些用户要签名. 见 `login_hint` 字段. |
| `prompt` | `""|"none"|"consent"|"select_account"` | 显示用户的提示列表 。 见 [`TokenClientConfig.prompt`](https://developers.google.com/identity/oauth2/web/reference/js-reference#TokenClientConfig) |

#### 活动

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `picker-oauth-error` | `OAuthErrorEvent` | 当 OAuth 流量发生错误时触发 。 见 [错误指南](https://developers.google.com/identity/oauth2/web/guides/error)。注意 `TokenResponse` 对象可以有出错字段. |
| `picker-oauth-response` | `OAuthResponseEvent` | 当 OAuth 流量完成时触发 。 见 [符号模型指南](https://developers.google.com/identity/oauth2/web/guides/use-token-model)。 。 。 . |
| `picker-canceled` | `PickerCanceledEvent` | 当用户取消拾取器对话框时触发 。 见 [`ResponseObject`](https://developers.google.com/drive/picker/reference/picker.responseobject)。 。 。 . |
| `picker-picked` | `PickerPickedEvent` | 用户选择一个或多个项目时触发 。 见 [`ResponseObject`](https://developers.google.com/drive/picker/reference/picker.responseobject)。 。 。 . |
| `picker-error` | `PickerErrorEvent` | 发生错误时触发 。 见 [`ResponseObject`](https://developers.google.com/drive/picker/reference/picker.responseobject)。 。 。 . |

#### 槽数

| 名称 | 说明 |
| --- | --- |
| 默认 | 默认槽中包含要显示在拾取器中的视图元素 。 每个视图元素应执行属性 `view` 类型 `google.picker.View`。 。 。 . |

#### 属性

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `visible` | `boolean` | 控制拾取器对话框结束后的能见度 关闭。 如果任何属性发生变化,拾取者将被重建并 可见度将被重置 . |
| `tokenClientConfig` | \`关闭 < |  |

```
    google.accounts.oauth2.TokenClientConfig,
    "callback" \| "error_callback" 	>` |                                                                                                                                                                                      |
```

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

这个 `drive-picker-docs-view` 元素用于定义 a [`google.picker.DocsView`](https://developers.google.com/drive/picker/reference/picker.docsview)。 。 。 .

#### 属性

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `enable-drives` | `"default"|"true"|"false"` | 是否允许用户从共享驱动器中选择文件 。 见 [`DocsView.enableDrives`](https://developers.google.com/drive/picker/reference/picker.docsview.setenabledrives)。 。 。 . |
| `file-ids` | `string` | 以逗号分隔的文件ID列表来过滤视图. 见 [`View.setFileIds`](https://developers.google.com/workspace/drive/picker/reference/picker.docsview.setfileids)。 。 。 . |
| `include-folders` | `"default"|"true"|"false"` | 是否在视图中包含文件夹 。 见 [`DocsView.includeFolders`](https://developers.google.com/drive/picker/reference/picker.docsview.setincludefolders)。 。 。 . |
| `mime-types` | `string` | 以逗号分隔的MIME类型列表来过滤视图. 见 [`View.setMimeTypes`](https://developers.google.com/drive/picker/reference/picker.view.setmimetypes)。 。 。 . |
| `mode` | `string` | 取景模式. 见 [`DocsViewMode`](https://developers.google.com/drive/picker/reference/picker.docsviewmode)。 。 。 . |
| `owned-by-me` | `"default"|"true"|"false"` | 是否显示用户拥有的文件 。 见 [`DocsView.ownedByMe`](https://developers.google.com/drive/picker/reference/picker.docsview.setownedbyme)。 。 。 . |
| `parent` | `string` | 要查看的文件夹的ID 。 见 [`DocsView.setParent`](https://developers.google.com/drive/picker/reference/picker.docsview.setparent)。 。 。 . |
| `query` | `string` | 过滤视图的查询字符串 。 见 [`View.setQuery`](https://developers.google.com/drive/picker/reference/picker.view.setquery)。 。 。 . |
| `select-folder-enabled` | `"default"|"true"|"false"` | 是否允许用户选择文件夹 。 见 [`DocsView.selectFolderEnabled`](https://developers.google.com/drive/picker/reference/picker.docsview.setselectfolderenabled)。 。 。 . |
| `starred` | `"default"|"true"|"false"` | 是否显示主控文件 。 见 [`DocsView.starred`](https://developers.google.com/drive/picker/reference/picker.docsview.setstarred)。 。 。 . |
| `view-id` | `string` | 这个 `keyof typeof google.picker.ViewId`。例如, `"DOCS"`,相当于 `google.picker.ViewId.DOCS`。见 [`ViewId`](https://developers.google.com/drive/picker/reference/picker.viewid)。 。 。 . |

#### 属性

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `view` | `google.picker.DocsView` | 获得基于当前属性值的Google Drive Picker视图. |

## 常见问题

### @googleworkspace/drive-picker-element 是什么？

Google Drive Picker 的网络组件

### 如何安装 @googleworkspace/drive-picker-element？

在项目目录运行 npm install @googleworkspace/drive-picker-element，或使用 pnpm add / yarn add / bun add。

### @googleworkspace/drive-picker-element 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @googleworkspace/drive-picker-element 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @googleworkspace/drive-picker-element 可以商用吗？

@googleworkspace/drive-picker-element 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @googleworkspace/drive-picker-element 的下载量有多少？

根据 npm 官方下载统计，@googleworkspace/drive-picker-element 在 2026/10/17 – 2026/11/15 这 30 天内被下载 822,737 次，日均约 27,425 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @googleworkspace/drive-picker-element 还在维护吗？

最新版本 0\.7\.3 发布于 2025/12/10（11 个月前）；至今共发布 27 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/08/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

