使用 OneDrive 文件选取器 JavaScript SDK v7.0 打开文件
注意: 此版本已被替换成 文件选取器 v7.2。 应使用最新版文件选取器 SDK 实现新集成。
下面逐步展示了如何将文件选取器 SDK 集成到客户端 JavaScript 应用中。
文件打开演示
1.注册应用
必须通过 Azure 应用注册页面注册应用并获取应用 ID,才能使用 OneDrive 文件选取器。还需要为使用文件选取器的 Web 应用添加有效的重定向 URI。这可以是托管文件选取器 SDK 的网页,也可以是定义的自定义 URL。有关详细信息,请参阅设置。
2.添加对 SDK 的引用
将 OneDrive JavaScript SDK 嵌入网页。
<script type="text/javascript" src="https://js.live.net/v7.0/OneDrive.js"></script>
3.启动文件选取器
若要打开 OneDrive 中的文件,应用应提供以编程方式打开 OneDrive 文件选取器的按钮。 由于以下代码将在浏览器中启动弹出窗口,因此需要在显式用户操作期间调用,以免被弹出窗口阻止程序阻止。
在 OneDrive.open(...) 方法中指定选项,从而指定文件选取器的行为方式,以及文件选取器如何通过 options 对象回调代码。
<script type="text/javascript">
function launchOneDrivePicker(){
var odOptions = { /* ... specify the desired options ... */ };
OneDrive.open(odOptions);
}
</script>
<button onClick="launchOneDrivePicker">Open from OneDrive</button>
文件选取器选项
可以提供包含控制文件选取器行为的参数的对象,指定文件选取器的行为方式。 此对象还包含文件选取器在完成时或遇到错误时所需的回调函数。
示例文件选取器选项
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "share | download | query",
multiSelect: true,
openInNewWindow: true,
advanced: {},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(e) { /* error handler */ }
}
参数
| 参数名称 | 说明 |
|---|---|
| clientId | 应用注册控制台为了实现集成而生成的应用 ID。 |
| action | 选择文件后要执行的操作类型。可以指定 share 生成可共享 URL,可以指定 download 获取用于下载文件内容的短期 URL,也可以指定 query 返回可与 Microsoft Graph API 或 OneDrive API 结合使用的标识符。 |
| multiSelect | 默认值可以是 false,要求用户只选取一个文件;也可以是 true,允许用户选取多个文件。 |
| openInNewWindow | 默认值可以是 true,这将打开弹出窗口为用户提供 OneDrive 文件选取体验;也可以是 false,这将在同一窗口中为用户提供 OneDrive 文件选取体验。 |
| advanced | 一组可进一步自定义文件选取器行为,但并不为大多数方案所需的其他属性。 有关详细信息,请参阅高级方案。 |
| success | 在用户选取完文件并获得包含一组选定文件的 response 对象时调用。如果 openInNewWindow 为 true,此为必需参数。 |
| 取消 | 在用户取消文件选取器时调用。 此函数无需使用任何参数。 |
| error | 在服务器出错或用户无权获取选定文件的链接时调用。此函数需要使用一个参数,即 error 对象。 |
注意:如果 openInNewWindow 为 false,必须 先在网页上对所有回调函数进行全局声明,然后再引用 SDK,这样可确保函数得到调用。 经过全局注册的回调函数会进行重命名,即名称中新增 oneDriveFilePicker 前缀。 例如,success 变成 oneDriveFilePickerSuccess。
操作类型
可以使用文件选取器 SDK 的 action 参数,指定在用户选取文件或文件夹后应返回的 URL 的类型。 可取值如下:
| 值 | 说明 |
|---|---|
download |
返回选定文件的短期下载 URL。 |
share |
返回选定文件的只读共享 URL,此 URL 可与其他用户共享。 |
query |
只返回选定文件的元数据。 使用 API 可以对文件执行相应的其他操作。 |
4.处理文件选取器 response 对象
在用户选取完文件后,success 回调会收到 response 对象。 此对象包含属性,其中包括 value 属性,这是 driveItem 资源集合,外加项属性的子集。
对于 OneDrive 个人版,选取多个文件并发出共享链接请求后,response 对象还包括根对象的 webUrl 属性。 这是指向显示所有选定文件的网页的 URL。
{
"webUrl": "https://1drv.ms/link/to/selected/files/page",
"value": [
{
"id": "123456",
"name": "document1.docx",
"size": 12340,
"@microsoft.graph.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
"webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
"thumbnails": [
{
"id": "0",
"small": { "url": "https://sn3302files.onedrive.live.com/..." },
"medium": { "url": "https://sn3302files.onedrive.live.com/..." },
"large": { "url": "https://sn3302files.onedrive.live.com/..." }
}
]
}
]
}
高级文件打开方案
文件选取器还支持通过 query 操作实现其他高级方案。 这样一来,可以将文件选取器与 OneDrive API 结合使用,从而完成高级方案。
options 对象中的 advanced 参数包含以下定义属性:
| 参数名称 | 说明 |
|---|---|
| queryParameters | OneDrive API 指定的一组其他查询参数,以定义项返回方式。这通常包括 select 和/或 expand 值。 |
| createLinkParameters | 更改用于生成 share 操作链接的参数。 |
| redirectUri | 默认情况下,文件选取器将启动网页用作重定向 URI,以供进行身份验证时使用。 这可能并不是对所有方案都适合,因此可以设置并改用自定义 URL。 此 URL 必须与托管文件选取器 SDK 的网页位于同一根域,并使用与之相同的协议。 目标网页必须按照网页调用方式,引用 OneDrive 文件选取器 SDK。 |
| filter | 可以应用于仅显示特定类型的一组文件类型。 支持系统类型“photo”和“folder”,以及使用“docx”等任意扩展名的自定义类型。 一种适用的 filter 设置是“folder,.png”,其中每个筛选器用 , 分隔。 |
注意: 目前,仅 OneDrive 个人版 UI 支持“photo”筛选器类型。
结合使用文件选取器和 API
可以使用 action 值 query,同时设置 advanced 对象的 queryParameters,从而通过 API 返回与选定对象相关的一组自定义属性。例如,在选取文件后,若要添加照片详细信息(若有),请运行以下命令:
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "query",
multiSelect: false,
advanced: {
queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
filter: "folder,.png" /* display folder and files with extension '.png' only */
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(e) { /* error handler */ }
}
这会指示文件选取器 SDK 在 response 中选择 id、name、size、file、folder 和 photo 属性。
返回可共享的读/写公司链接
默认情况下,如果将 action 设置为 share,OneDrive 文件选取器会返回仅供查看的共享 URL。 不过,可以使用 createLinkParameters 属性,更改传递给 createLink action 的参数。
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "share",
multiSelect: false,
advanced: {
createLinkParameters: { type: "edit", scope: "organization" }
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(e) { /* error handler */ }
}
使用自定义重定向 URI
如果应用是大型客户端 JavaScript 应用或使用查询字符串参数维持状态,将文件选取器的启动网页用作重定向 URI 可能并不可取。 若要将启动网页用作重定向 URI,必须在弹出窗口中重新加载整个应用,但这可能会引发性能问题。 可以通过改用 advanced 对象来指定替代的重定向 URI。
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "download",
openInNewWindow: true,
advanced: {
redirectUri: "https://contoso.com/filePickerRedirect.htm"
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(e) { /* error handler */ }
}
重定向到的网页只需加载 OneDrive SDK 脚本:
<html>
<script type="text/javascript" src="https://js.live.net/v7.0/OneDrive.js"></script>
</html>
注意: 将文件选取器用作弹出窗口(即 openInNewWindow 为 true)时,只能提供自定义重定向 URI。 如果采用内联体验,请务必使用默认的重定向 URI。