使用 OneDrive 文件选取器 JavaScript SDK v7.0 保存文件

注意: 此版本已被替换成 文件选取器 v7.2。 应使用最新版文件选取器 SDK 实现新集成。

若要在 OneDrive 中保存文件,应用应提供以编程方式启动 OneDrive 文件选取器的按钮。

文件保存演示

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.save(...) 方法中指定选项,从而指定文件选取器的行为方式,以及文件选取器如何通过 options 对象回调代码。

<script type="text/javascript">
  function launchSaveToOneDrive(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.save(odOptions);
  }
</script>

<input id="fileUploadControl" name="fileUploadControl" type="file" />
<button onclick="launchSaveToOneDrive">Save to OneDrive</button>

文件选取器选项

可以提供包含控制文件选取器行为的参数的对象,指定文件选取器在保存文件时的行为方式。 此对象还包含文件选取器在完成时或遇到错误时所需的回调函数。

示例文件选取器选项

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "save | query",
  sourceInputElementId: "fileUploadControl",
  sourceUri: "",
  fileName: "file.txt",
  openInNewWindow: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  progress: function(p) { /* progress handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(e) { /* error handler */ }
}

参数

参数名称 说明
clientId 应用注册控制台为了实现集成而生成的应用 ID。
action 选择文件后要执行的操作类型。 可以指定 save 将文件直接保存到 OneDrive,也可以指定 query 返回可与 Microsoft Graph API 或 OneDrive API 结合使用以将文件保存到选定文件夹的标识符。
sourceInputElementId 要上传的文件的窗体输入 (type=file) 元素 ID。
sourceUri 要上传的文件的 http、https 或数据 URI。 OneDrive for Business 和 SharePoint 仅支持数据 URI 值。
fileName 如果 sourceUri 参数是数据 URI,此为必需参数。 如果未提供,将通过输入元素的名称属性推断文件名。
openInNewWindow 默认值为 true,这将打开弹出窗口为用户提供 OneDrive 文件选取体验。 如果值为 false,将在同一窗口中为用户提供 OneDrive 文件选取体验。
advanced 一组可进一步自定义文件选取器行为,但并不为大多数方案所需的其他属性。 有关详细信息,请参阅高级文件保存方案
success 在文件上传到服务器完成时调用。 file 参数是服务针对已上传的文件返回的一组元数据。
progress 在 0.0 到 100.0 之间的不同位置处调用,以指明上传进度。至少在 100.0 处调用一次。
cancel 在用户取消文件保存器时调用。
error 在服务器出错、用户配额不足、用户无权将文件上传到选定位置或用户未选择要上传的文件时调用。

注意:如果 openInNewWindowfalse必须 先在网页上对所有回调函数进行全局声明,然后再引用 SDK,这样可确保函数得到调用。 经过全局注册的回调函数会进行重命名,即名称中新增 oneDriveFilePicker 前缀。 例如,success 变成 oneDriveFilePickerSuccess

操作类型

可以使用文件选取器 SDK 的 action 参数,指定选取器的行为方式。 “save()”操作的可取值如下:

说明
save sourceInputElementIdsourceUri 提供的文件保存到用户 OneDrive 中的选定文件夹。
query 返回与选定文件夹有关的 API 元数据。 然后,应用将一个或多个文件上传到用户选择的文件夹中。

4.处理文件选取器 response 对象

在用户选取完文件后,success 回调会收到 response 对象。 此对象包含属性,其中包括 value 属性,这是 driveItem 资源集合,外加项属性的子集。

使用 save 操作时,此集合提供新上传的文件的项元数据。 对于 query 操作,此集合包含选定文件夹的元数据。

示例:上传文档

{
  "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 将文档保存到文件夹

{
  "value": [
    {
      "id": "1234567!12",
      "name": "Project Vroom",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/project%20vroom",
      "folder": { "childCount": 4 }
    }
  ]
}

高级文件保存方案

options 对象中的 advanced 参数包含以下定义属性:

参数名称 说明
redirectUri 默认情况下,文件选取器将启动网页用作重定向 URI,以供进行身份验证时使用。 这可能并不是对所有方案都适合,因此可以设置并改用自定义 URL。 此 URL 必须与托管文件选取器 SDK 的网页位于同一根域,并使用与之相同的协议。 目标网页必须按照网页调用方式,引用 OneDrive 文件选取器 SDK。

使用自定义重定向 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。