OneDrive 文件选取器 JavaScript SDK
注意: 此版本已被替换成 文件选取器 v7.2。 应使用最新版文件选取器 SDK 实现新集成。
适用于 Web 应用的 OneDrive 文件选取器和保存器 SDK 是将 OneDrive 集成到网站的最快捷方式。只需使用按钮或几行 JavaScript,即可打开文件,并将文件保存到 OneDrive 中,无需处理身份验证。适用于 Web 应用的 OneDrive 文件选取器和保存器 SDK 不同于其他 OneDrive 文件选取器和保存器 SDK,因为无需下载任何内容,即可开始使用。
如果使用此类文件选取器打开 OneDrive 中的文件,可获取非常适合 Web 查看和发送给亲朋好友的可共享文件链接,或非常适合获取文件内容的可下载文件链接。还可获取图像和视频文件的缩略图,以便轻松快速地查看这些文件。
本指南将介绍如何让应用在 OneDrive 上快速打开和保存文件。
设置
注册应用以获取应用 ID(客户端 ID)(如果尚未这样做的话)。 确保将引用 SDK 的网页是 API 下重定向 URL设置。 还可以上载应用程序徽标,OneDrive文件选取器保护程序体验中显示。
然后,若要开始打开或保存文件,请在网页中添加以下引用,将 APP_ID 替换成应用 ID 或客户端 ID。
<script type="text/javascript" src="https://js.live.net/v5.0/OneDrive.js" id="onedrive-js" client-id="APP_ID"></script>
打开 OneDrive 中的文件
若要打开 OneDrive 中的文件,应用可以嵌入“从 OneDrive 打开”按钮,也可以提供以编程方式启动 OneDrive 文件选取器的自定义按钮。 两种方法均需要使用包含以下参数的 pickerOptions 对象。
| 参数名称 | 说明 |
|---|---|
| success | 必需。在用户选取完文件并将 file 对象数组传递给提供的函数时调用。 |
| cancel | 在用户取消文件选取器时调用。 |
| linkType | 为了授予文件访问权限而创建的链接的类型。 默认值为 webLink,这将返回可提供文件 Web 预览的共享链接 URL。 在用户通过 OneDrive 删除共享链接前,此链接一直有效。 如果值为 downloadLink,这将返回可提供对文件内容的一小时直接访问权限的 URL。 可以使用此 URL 将文件下载到应用中。 |
| multiSelect | 默认值可以是 false,允许用户选取一个文件;也可以是 true,允许用户选取多个文件。 |
| theme | 按钮的颜色主题。默认值为 blue。可取值为 blue 和 white。只能与 OneDrive.createOpenButton 方法配合使用。 |
pickerOptions 对象示例
var pickerOptions = {
success: function(files) {
// Handle returned file object(s)
alert("You picked " + files.values[0].fileName);
},
cancel: function() {
// handle when the user cancels picking a file
},
linkType: "webViewLink", // or "downloadLink",
multiSelect: false // or true
}
使用按钮打开文件
可以使用网站上"从
OneDrive。 以下代码在网页中添加按钮元素。 在用户单击此按钮后,OneDrive 文件选取器便会开始处理指定的 pickerOptions,然后返回用户选取的文件。
若要在网页中添加
按钮,请配置 pickerOptions 并嵌入此按钮,具体如下所示。
<script type="text/javascript">
window.onload = function() {
var pickerOptions = { /* ... */ };
var pickerButton = OneDrive.createOpenButton(pickerOptions);
document.getElementById("picker").appendChild(pickerButton);
}
</script>
<div id="picker"></div>
注意: 一旦调用 createOpenButton 方法,便无法再修改 pickerOptions 对象。
以编程方式启动该选取器
若要以编程方式设计自己的按钮或启动文件选取器,请使用配置了相应 OneDrive.open 的 pickerOptions 方法:
<script type="text/javascript">
function launchOneDrivePicker(){
var pickerOptions = { /* ... */ };
OneDrive.open(pickerOptions);
}
</script>
<button onclick="launchOneDrivePicker">Open from OneDrive</button>
启动后,文件选取器会打开对话框,提示用户选取文件。在用户取消或完成文件选取后,应用便会收到表示用户选取的文件的 response 对象。
处理对文件对象的选取器响应
在用户选取完文件后,success 回调会收到 response 对象,其中包含 values 属性,这是一组 file 对象,每个 select 的长度均为 1。
{
link: "https://...",
values: [
{
fileName: "file.txt",
link: "https://..."
},
{ },
{ }
]
}
response 对象具有以下属性:
| 属性名称 | 值 | 说明 |
|---|---|---|
| link | string - url | 如果 linkType 是 webViewLink 且 multiSelect 是 true,那么 link 将返回用于查看所有文件的 webViewLink。 否则,link 为 null。 |
| values | Array of file objects | 用户选取的每个文件的 file 对象集合。 |
文件对象的示例
{
fileName: "file.txt",
link: "https://...",
linkType: "webViewLink",
size: 123456,
thumbnails: ["https://...", "https://...", "https://..."]
}
file 对象具有以下属性:
| 属性名 | 值 | 说明 |
|---|---|---|
| fileName | string | 文件名(包含扩展名)。 |
| link | string - url | 请求获取的文件的 URL。 |
| linkType | string | 生成的链接类型。 webViewLink 或 downloadLink。 |
| size | integer | 文件大小(以字节为单位)。 |
| thumbnails | Array of thumbnail urls | 图像或视频文件的一组缩略图链接(按大、中和小顺序排列)。对于其他类型文件,此值为 null。 |
将文件保存到 OneDrive
若要开始将文件保存到 OneDrive,请使用
“保存到 OneDrive”按钮 按钮直接嵌入应用,或使用 OneDrive.save 方法打造更加个性化的体验。 两种方法均需要使用包含以下参数的 saverOptions 对象。
注意: 用户使用 OneDrive JavaScript 文件保存器 SDK 可以保存的文件的大小上限是 100MB。
saverOptions 对象示例
var saverOptions = {
file: "inputFile",
fileName: 'file.txt',
success: function(){
// upload is complete
},
progress: function(p) {
// upload is progressing
},
cancel: function(){
// upload was cancelled
},
error: function(e) {
// an error occured
}
}
saverOptions 对象具有以下属性:
| 参数名称 | 说明 |
|---|---|
| file | 必需。file 参数的窗体输入元素 ID。 |
| fileName | 如果未提供,将通过输入元素的名称属性推断文件名。 |
| success | 在文件上传到服务器完成时调用。 |
| progress | 在 0.0 到 100.0 之间的不同位置处调用,以指明上传进度。至少在 100.0 处调用一次。 |
| cancel | 在用户取消文件保存器时调用。 |
| error | 当服务器上出现错误、用户不在配额范围内,或用户没有上载到所选位置的权限时进行调用。 |
| theme | 按钮的颜色主题。默认值为 blue。可取值为 blue 和 white。只能与 OneDrive.createSaveButton 方法配合使用。 |
使用按钮将文件保存到 OneDrive
与
按钮非常相似,只需使用几行代码,即可嵌入
按钮。 在用户单击此按钮后,OneDrive 文件保存器便会启动,用户可以选择 OneDrive 中的位置来保存文件。
<script type="text/javascript">
window.onload = function() {
var saverOptions = { file: "file" /* ... */ };
var saverButton = OneDrive.createSaveButton(saverOptions);
document.getElementById("save").appendChild(saverButton);
}
</script>
<input id="file" name="file" type="file" />
<div id="save"></div>
注意: 一旦调用 createSaveButton 方法,便无法再修改 saverOptions 对象。
以编程方式启动保护程序
可以调用 OneDrive.save 方法,以编程方式设计自己的按钮或启动 OneDrive 文件保存器。文件保存器会显示对话框,提示用户选取用于保存文件的文件夹。选取文件夹后,OneDrive 文件保存器便会上传文件。使用配置了相应选项的 OneDrive.save 方法,启动文件保存器。
<script type="text/javascript">
function launchOneDriveSaver(){
var saverOptions = { file: "file" /* ... */ };
OneDrive.save(saverOptions);
}
</script>
<input id="file" name="file" type="file" />
<button onclick="launchOneDriveSaver">Save to OneDrive</button>
启动后,文件保存器会启动弹出对话框。 在用户选取用于保存文件的文件夹后,文件保存器会关闭并上传文件。
支持的浏览器
OneDrive 文件选取器和保存器支持以下 Web 浏览器:
- Internet Explorer 9 及更高版本
- 最新版 Chrome
- 最新版 Firefox
- 最新版 Safari
许可证
版权所有 (c) Microsoft Corporation。 保留所有权利。
在 MIT 许可证下获得许可。