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

项目
04/08/2023

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

1.注册应用

若要使用 OneDrive 选取器，需要通过“Azure 应用注册”页注册应用程序并接收应用程序 ID。还需要使用选取器为 Web 应用程序添加有效的重定向 URI。这可以是托管文件选取器 SDK 的网页，也可以是定义的自定义 URL。有关详细信息，请参阅设置。

2.添加对 SDK 的引用

将 OneDrive JavaScript SDK 嵌入网页。

<script type="text/javascript" src="https://js.live.net/v7.2/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",
  sourceInputElementId: "fileUploadControl",
  sourceUri: "",
  fileName: "file.txt",
  openInNewWindow: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  progress: function(percent) { /* progress handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* 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 文件选取体验。
viewType	可以选择的项目的类型。默认值为 `files`。可以指定 `folders`仅选择文件夹，或指定 `all` 支持选择文件和文件夹。
accountSwitchEnabled	默认值是 `true`，它在托管文件选取器页上呈现“切换账户”用户界面。
advanced	一组可进一步自定义文件选取器行为，但并不为大多数方案所需的其他属性。有关详细信息，请参阅高级文件保存方案。
nameConflictBehavior	在上传的文件与目标文件夹中的文件发生名称冲突时传递的可选参数。有关详细信息，请参阅参数定义。
success	在文件上传到服务器完成时调用。 file 参数是服务针对已上传的文件返回的一组元数据。
progress	在 0.0 到 100.0 之间的不同位置处调用，以指明上传进度。至少在 100.0 处调用一次。
cancel	在用户取消文件保存器时调用。
error	在服务器出错、用户配额不足、用户无权将文件上传到选定位置或用户未选择要上传的文件时调用。

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

操作类型

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

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

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

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

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

示例：上传文档

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@content.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(error) { /* error handler */ }
}

重定向到的网页只需加载 OneDrive SDK 脚本：

<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>

注意： 将文件选取器用作弹出窗口（即 openInNewWindow 为 true）时，只能提供自定义重定向 URI。如果采用内联体验，请务必使用默认的重定向 URI。

通过