@googleworkspace/drive-picker-element

中文文档
0.7.3发布于 2025/12/10Apache-2.0TypeScriptES Module零依赖构建来源已验证近 30 天下载 82.3万

Google Drive Picker 的网络组件

中文使用文档
文档目录16 节
  1. 说明
  2. 指数
  3. 安装
  4. 使用量
  5. 导入组件
  6. 将组件添加到您的 HTML
  7. 使用 oauth-token 属性
  8. 倾听事件
  9. 事件详情
  10. 控制可见度
  11. 反应
  12. 内容安全政策
  13. 支助
  14. 参考文献
  15. <drive-picker/>
  16. <drive-picker-docs-view/>

npm Test Release

说明

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

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

探索 故事书演示 将组成部分付诸行动.

见框架的具体组成部分:

指数

安装

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

npm i @googleworkspace/drive-picker-element

还有一个CDN版本. 见 (单位:公斤)。 。 。 .

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

使用量

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

导入组件

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

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

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

将组件添加到您的 HTML

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

注意: 您可以在 谷歌云控台 “APIS & Services” > “证书”。 您也可以遵循此指南 创建新的 OAuth 2. 0 客户端ID。 。 。 .

<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() 手动 :

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 属性。 这将认证用户,而不要求他们再次签名 .

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

如果你没有OAuth标志,你可以听 "picker-oauth-response" 在用户认证后获取符号的事件。 这个库包 Google 身份服务图书馆 以方便用户认证.

倾听事件

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

<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 作为事件的细节。 例如 "picker-picked" CustomEvent 包含所选文件的详情 :

{
  "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 符号响应作为事件细节 :

{
  "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数字 :

<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。 。 。 .

请参看 软件包文档 用于使用指令.

内容安全政策

此库动态地加载 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 或允许域).

    <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。这里有一个完整的例子:

    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 注入的一些样式可能需要。 对于更严格的政策,你可以使用 无。 。 。 .

Chrome扩展(Manifest V3)的说明: 基本的 Google Picker API 依赖 gapi,这是 在 Express V3 扩展中不支持因此,不管CSP设置如何,此库可能不会在这个环境中运行.

支助

请使用 Google Picker 发行跟踪器关于所有其他问题,请使用 GitHub 问题跟踪器。 。 。 .

参考文献

<drive-picker/>

这个 drive-picker 网络组件提供了一种方便的宣示方式 构建 google.picker.Picker 使用绘图到相应方法的组件属性 google.picker.PickerBuilder。 。 。 .

属性

名称类型说明
app-idstringGoogle Drive app ID (英语). 见 PickerBuilder.setAppId。 。 。 .
client-idstringOAuth 2.0客户端ID. 见 使用 OAuth 2. 0 访问 Google API。 。 。 .
debounce-delaynumber属性改变后在建立取取取器前以毫秒表示的解跳延迟.
developer-keystring访问Google Picker API的API密钥. 见 PickerBuilder.setDeveloperKey。 。 。 .
hide-title-bar"default"|"true"|"false"如果设置为真,则隐藏拾取者的标题栏。 见 PickerBuilder.hideTitleBar。 。 。 .
localestring取取者所用之地. 见 PickerBuilder.setLocale。 。 。 .
max-itemsnumber可选择项目的最大数量 。 见 PickerBuilder.setMaxItems。 。 。 .
mine-onlyboolean如果设置为真, 只显示用户拥有的文件 。 见 PickerBuilder.enableFeature。 。 。 .
multiselectboolean如果设置为真, 启用多个文件选择 。 见 PickerBuilder.enableFeature。 。 。 .
nav-hiddenboolean如果设置为真, 则隐藏导航窗格。 见 PickerBuilder.enableFeature。 。 。 .
oauth-tokenstringOAuth 2.0 认证符. 见 PickerBuilder.setOAuthToken。 。 。 .
originstring采取器的起源参数 。 见 PickerBuilder.setOrigin。 。 。 .
relay-urlstring拾取器的中继 URL 。 见 PickerBuilder.setRelayUrl。 。 。 .
scopestring摘取者OAuth 2.0范围. 默认是 https://www.googleapis.com/auth/drive.file。见 驱动 API 瞄准镜。 。 。 .
titlestring取取者所取之名. 见 PickerBuilder.setTitle。 。 。 .
hdstring主机域限制登录到 。 (备选) 见 hd 字段.
include-granted-scopesboolean允许应用程序使用递增授权. 见 TokenClientConfig.include_granted_scopes。 。 。 .
login-hintstring电子邮件地址或ID标志"sub"值 。 Google 将使用该值作为提示哪些用户要签名. 见 login_hint 字段.
prompt""|"none"|"consent"|"select_account"显示用户的提示列表 。 见 TokenClientConfig.prompt

活动

名称类型说明
picker-oauth-errorOAuthErrorEvent当 OAuth 流量发生错误时触发 。 见 错误指南。注意 TokenResponse 对象可以有出错字段.
picker-oauth-responseOAuthResponseEvent当 OAuth 流量完成时触发 。 见 符号模型指南。 。 。 .
picker-canceledPickerCanceledEvent当用户取消拾取器对话框时触发 。 见 ResponseObject。 。 。 .
picker-pickedPickerPickedEvent用户选择一个或多个项目时触发 。 见 ResponseObject。 。 。 .
picker-errorPickerErrorEvent发生错误时触发 。 见 ResponseObject。 。 。 .

槽数

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

属性

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

<drive-picker-docs-view/>

这个 drive-picker-docs-view 元素用于定义 a google.picker.DocsView。 。 。 .

属性

名称类型说明
enable-drives"default"|"true"|"false"是否允许用户从共享驱动器中选择文件 。 见 DocsView.enableDrives。 。 。 .
file-idsstring以逗号分隔的文件ID列表来过滤视图. 见 View.setFileIds。 。 。 .
include-folders"default"|"true"|"false"是否在视图中包含文件夹 。 见 DocsView.includeFolders。 。 。 .
mime-typesstring以逗号分隔的MIME类型列表来过滤视图. 见 View.setMimeTypes。 。 。 .
modestring取景模式. 见 DocsViewMode。 。 。 .
owned-by-me"default"|"true"|"false"是否显示用户拥有的文件 。 见 DocsView.ownedByMe。 。 。 .
parentstring要查看的文件夹的ID 。 见 DocsView.setParent。 。 。 .
querystring过滤视图的查询字符串 。 见 View.setQuery。 。 。 .
select-folder-enabled"default"|"true"|"false"是否允许用户选择文件夹 。 见 DocsView.selectFolderEnabled。 。 。 .
starred"default"|"true"|"false"是否显示主控文件 。 见 DocsView.starred。 。 。 .
view-idstring这个 keyof typeof google.picker.ViewId。例如, "DOCS",相当于 google.picker.ViewId.DOCS。见 ViewId。 。 。 .

属性

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

版本与发布记录

@googleworkspace/drive-picker-element 共发布 27 个版本,首次发布于 2024/08/20;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.7.3latest2025/12/1011 个月前
0.7.22025/12/0511 个月前
0.7.12025/12/0211 个月前
0.7.02025/11/2011 个月前
0.6.52025/11/1911 个月前
0.6.42025/11/1911 个月前

关于 @googleworkspace/drive-picker-element 的常见问题

@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 和提交记录判断。