使用 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 对象。

注意:如果 openInNewWindowfalse必须 先在网页上对所有回调函数进行全局声明,然后再引用 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

可以使用 actionquery,同时设置 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 中选择 idnamesizefilefolderphoto 属性。

默认情况下,如果将 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>

注意: 将文件选取器用作弹出窗口(即 openInNewWindowtrue)时,只能提供自定义重定向 URI。 如果采用内联体验,请务必使用默认的重定向 URI。