说明
这个 谷歌驱动拾取器 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环境中使用此库:
-
预装脚本: 使用 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> -
确保全球对象可用: 图书馆检查
window.gapi财务报告和审定财务报表window.google.accounts.oauth2如果这些都存在,它会跳过动态注射. -
允许 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-srcpicker 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-id | string | Google Drive app ID (英语). 见 PickerBuilder.setAppId。 。 。 . |
client-id | string | OAuth 2.0客户端ID. 见 使用 OAuth 2. 0 访问 Google API。 。 。 . |
debounce-delay | number | 属性改变后在建立取取取器前以毫秒表示的解跳延迟. |
developer-key | string | 访问Google Picker API的API密钥. 见 PickerBuilder.setDeveloperKey。 。 。 . |
hide-title-bar | "default"|"true"|"false" | 如果设置为真,则隐藏拾取者的标题栏。 见 PickerBuilder.hideTitleBar。 。 。 . |
locale | string | 取取者所用之地. 见 PickerBuilder.setLocale。 。 。 . |
max-items | number | 可选择项目的最大数量 。 见 PickerBuilder.setMaxItems。 。 。 . |
mine-only | boolean | 如果设置为真, 只显示用户拥有的文件 。 见 PickerBuilder.enableFeature。 。 。 . |
multiselect | boolean | 如果设置为真, 启用多个文件选择 。 见 PickerBuilder.enableFeature。 。 。 . |
nav-hidden | boolean | 如果设置为真, 则隐藏导航窗格。 见 PickerBuilder.enableFeature。 。 。 . |
oauth-token | string | OAuth 2.0 认证符. 见 PickerBuilder.setOAuthToken。 。 。 . |
origin | string | 采取器的起源参数 。 见 PickerBuilder.setOrigin。 。 。 . |
relay-url | string | 拾取器的中继 URL 。 见 PickerBuilder.setRelayUrl。 。 。 . |
scope | string | 摘取者OAuth 2.0范围. 默认是 https://www.googleapis.com/auth/drive.file。见 驱动 API 瞄准镜。 。 。 . |
title | string | 取取者所取之名. 见 PickerBuilder.setTitle。 。 。 . |
hd | string | 主机域限制登录到 。 (备选) 见 hd 字段. |
include-granted-scopes | boolean | 允许应用程序使用递增授权. 见 TokenClientConfig.include_granted_scopes。 。 。 . |
login-hint | string | 电子邮件地址或ID标志"sub"值 。 Google 将使用该值作为提示哪些用户要签名. 见 login_hint 字段. |
prompt | ""|"none"|"consent"|"select_account" | 显示用户的提示列表 。 见 TokenClientConfig.prompt |
活动
| 名称 | 类型 | 说明 |
|---|---|---|
picker-oauth-error | OAuthErrorEvent | 当 OAuth 流量发生错误时触发 。 见 错误指南。注意 TokenResponse 对象可以有出错字段. |
picker-oauth-response | OAuthResponseEvent | 当 OAuth 流量完成时触发 。 见 符号模型指南。 。 。 . |
picker-canceled | PickerCanceledEvent | 当用户取消拾取器对话框时触发 。 见 ResponseObject。 。 。 . |
picker-picked | PickerPickedEvent | 用户选择一个或多个项目时触发 。 见 ResponseObject。 。 。 . |
picker-error | PickerErrorEvent | 发生错误时触发 。 见 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。 。 。 .
属性
| 名称 | 类型 | 说明 |
|---|---|---|
enable-drives | "default"|"true"|"false" | 是否允许用户从共享驱动器中选择文件 。 见 DocsView.enableDrives。 。 。 . |
file-ids | string | 以逗号分隔的文件ID列表来过滤视图. 见 View.setFileIds。 。 。 . |
include-folders | "default"|"true"|"false" | 是否在视图中包含文件夹 。 见 DocsView.includeFolders。 。 。 . |
mime-types | string | 以逗号分隔的MIME类型列表来过滤视图. 见 View.setMimeTypes。 。 。 . |
mode | string | 取景模式. 见 DocsViewMode。 。 。 . |
owned-by-me | "default"|"true"|"false" | 是否显示用户拥有的文件 。 见 DocsView.ownedByMe。 。 。 . |
parent | string | 要查看的文件夹的ID 。 见 DocsView.setParent。 。 。 . |
query | string | 过滤视图的查询字符串 。 见 View.setQuery。 。 。 . |
select-folder-enabled | "default"|"true"|"false" | 是否允许用户选择文件夹 。 见 DocsView.selectFolderEnabled。 。 。 . |
starred | "default"|"true"|"false" | 是否显示主控文件 。 见 DocsView.starred。 。 。 . |
view-id | string | 这个 keyof typeof google.picker.ViewId。例如, "DOCS",相当于 google.picker.ViewId.DOCS。见 ViewId。 。 。 . |
属性
| 名称 | 类型 | 说明 |
|---|---|---|
view | google.picker.DocsView | 获得基于当前属性值的Google Drive Picker视图. |