预览应用中的文件

适用于： 开发 人员

添加文件预览 UX，以便用户无需下载文件或打开完整的 Office 编辑体验即可检查 SharePoint Embedded 内容。

需要 Office 编辑时 ，请从应用中完成打开 Office 文件 。 使用本文进行轻量级预览。

了解预览流

预览流有两个步骤：

  1. 调用 Microsoft Graph DriveItem 预览版终结点。
  2. 在 iframe 或新的浏览器页面中使用返回的 URL。

Graph 终结点为：

POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview

其中：

  • {version} 是 Microsoft Graph 版本，例如 v1.0。
  • {driveId} 以 开头 b!的容器 ID。
  • {itemId} 是 DriveItem ID。

有关规范 API 参考，请参阅 预览 DriveItem。

了解支持的文件类型

Microsoft 365 支持许多文件类型（包括常见文档、图像、视频和 PDF 格式）的预览。

示例包括：

  • PDF 文件。
  • JPG 和其他图像文件。
  • MP4 和其他支持的媒体文件。
  • Microsoft 365 预览体验支持的 Office 文件。

有关当前列表，请参阅 支持在 OneDrive、SharePoint 和 Teams 中预览文件的文件类型。

注意

文件类型支持可能因服务功能、租户策略和客户端体验而异。 始终正常处理预览失败。

本机 PDF 查看

SharePoint Embedded 本机 PDF 查看体验支持 在文件中搜索、查看文件上嵌入的 批注和便笺 ，以及 打印 2026 年 3 月) 添加 (。 这些功能可通过 driveItem： preview API 在 beta 和 v1.0 Microsoft Graph 终结点中使用。

使用查询参数增强 PDF 预览器

通过将查询参数追加到 driveItem 的 webUrl 属性来增强 SharePoint Embedded PDF 预览器。 若要获取 webUrl，请调用 driveItem GET API，例如 GET /drives/{drive-id}/items/{item-id}?$select=webUrl。

将参数作为 JSON 编码的 embed 查询字符串传递。 可以在同一对象中包含一个或多个参数。

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}
参数 作用
mpp 启用打印图标和 Ctrl+P 打印。 例如，<webUrl>?&embed={"mpp":true}。
mpsn 当 PDF 包含便笺时显示便笺内容。 例如，<webUrl>?&embed={"mpsn":true}。

先决条件

创建预览之前，请确保：

  • 该文件存储在 SharePoint Embedded 容器中。
  • 你的应用知道容器 ID 和 DriveItem ID。
  • 应用可以获取 Microsoft Graph 令牌。
  • 调用方具有读取文件的权限。
  • 文件类型支持预览。
  • UI 可以托管 iframe 或打开新页面。

从服务层调用预览终结点。

使用此 C# SDK 模式：

ItemPreviewInfo preview = await graphServiceClient.Drives[driveId].Items[itemId]
    .Preview()
    .Request()
    .PostAsync();

响应包括预览 URL 信息：

{
  "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz",
  "postParameters": "param1=value&param2=another%20value",
  "postUrl": "https://www.onedrive.com/embed_by_post"
}

可用时使用 getUrl 。

警告

getUrl 当前包含只能与应用程序一起使用的加密令牌。 此行为可能会更改。

删除预览横幅

将 添加到 nb=true 获取的 URL 以删除顶部的横幅。

示例：

https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true

仅当它适合你的用户体验和符合性要求时才使用。

在 iframe 中嵌入预览

创建托管预览 URL 的应用页。

示例形状：

<!DOCTYPE html>
<html>
  <body>
    <h2>Preview</h2>
    <p>Preview of {file name}:</p>
    <iframe src="{preview URL}" height="200" width="300" id="preview" title="File preview"></iframe>
  </body>
</html>

在生产中，还提供：

  • 描述性的 iframe 标题。

  • 响应式大小调整。

  • 正在加载状态。

  • 错误状态。

  • 回退下载或打开操作。

动态加载预览

如果创建 CORS 问题或公开令牌，请不要直接从浏览器脚本调用 Microsoft Graph。

使用服务器端终结点：：

  1. 对用户进行身份验证。
  2. 验证对所请求文件的访问权限。
  3. 获取 Graph 令牌。
  4. 调用 DriveItem 预览版终结点。
  5. 返回客户端的预览 URL。

使用此服务器端模式：

[HttpGet]
[AuthorizeForScopes(Scopes = new string[] { "Files.Read.All" })]
public async Task<ActionResult<string>> GetPreviewUrl(string driveId, string itemId)
{
  return url + "&nb=true";
}

然后，客户端可以请求 URL 并设置 iframe 源。

async function preview(driveId, itemId) {
  const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`;
  const response = await fetch(url, {
      credentials: 'include',
  }).then(response => response.text());
  document.getElementById('preview').src = response + "&nb=true";
}

设计预览版 UX

良好的预览版 UX 应：

  • 显示文件名。
  • 显示加载指示器。
  • 为 iframe 保留足够的空间。
  • 为 Office 文件提供在 Office 中打开操作。
  • 预览不可用时提供下载操作。
  • 保留键盘辅助功能。
  • 避免在预览帧内捕获焦点。
  • 使用用户友好语言解释错误。

处理预览错误

失败 处理
不支持的文件类型 改为显示下载或打开操作。
缺少权限 要求用户请求访问权限或再次登录。
URL 已过期 请求新的预览 URL。
CORS 错误 将 Graph 调用移动到服务器端终结点。
删除文件 刷新文件列表并删除过时的选择。
服务错误 重试一次，然后显示稳定的回退。

重要

不要将预览 URL 缓存为持久标识符。 存储容器 ID 和 DriveItem ID，然后根据需要创建一个新的预览 URL。

保护预览请求

将预览视为对受保护内容的读取操作。

服务应：

  1. 验证已登录的用户或服务上下文。
  2. 确认调用方是否可以读取容器内容。
  3. 确认请求的项属于预期的容器。
  4. 避免向浏览器公开 Graph 令牌。
  5. 避免记录包含敏感令牌的预览 URL。
  6. 用户注销时，使应用端预览会话过期。

验证预览体验

使用多个文件类型和用户进行测试：

  1. 上传 PDF 文件。
  2. 上传图像文件。
  3. 上传 Office 文件。
  4. 为每个文件创建预览 URL。
  5. 在 iframe 中呈现每个预览。
  6. 测试具有读取访问权限的用户。
  7. 测试没有访问权限的用户。
  8. 删除文件并确认已处理错误。
  9. 刷新过期的预览 URL。
  10. 确认回退操作有效。

连接到下一个生成任务

预览版正常运行后，添加发现体验，以便用户可以跨容器和文件查找内容。

继续 搜索容器和文件。

后续步骤

  • Last updated on