Doconut 查看器 是一款 .NET 文档查看库，旨在将 PDF、Office、CAD、图像以及其他受支持的文档系列嵌入到应用程序中。一个稳健的 Doconut 集成并非只追求最短的代码片段，而是要在您的应用、查看器和浏览器之间选择一个清晰的边界。
Doconut 文档中心 提供了针对受支持的 .NET 项目类型的维护好的设置路径。使用与您应用中安装的版本相匹配的指南，然后将周围的页面、身份检查和访问工作流视为您团队拥有的应用代码。
从集成边界开始
有三种常见方式在产品中放置文档预览。正确的选择取决于谁拥有导航、认证以及查看器的生命周期。
| 模式 | 最佳适用场景 | 主要权衡 |
|---|---|---|
| 应用视图 | 一个在产品控件旁渲染查看器的 .NET 页面 | 紧密集成，但页面与查看器的生命周期耦合 |
| 应用拥有的 iframe | 一个需要在宿主 UI 与预览路由之间进行隔离的门户 | 边界清晰，但通信必须明确设计 |
| 围绕服务器路由的框架组件 | 由 .NET 应用支持的 React、Angular 或 Vue 外壳 | 熟悉的前端组合，但需要管理更多的生命周期状态 |
iframe 模式不必指向公共文档 URL。它可以指向您自己应用中的受认证路由。该路由可以在渲染查看器页面之前验证访问权限，而无需向宿主页面暴露存储路径。
构建稳定、响应式的预览界面
不要从示例博客片段中重新构建查看器的标记或初始化代码。Doconut 会发布适用于每条受支持 .NET 线路的文件、middleware 步骤、命名空间以及查看器设置。例如，官方的 .NET 6 或更高版本设置指南 解释了服务器 middleware、查看器对象、文档选项、渲染配置以及所需的客户端资源。
使用这些版本化材料创建查看器，然后在您自己的布局中为其宿主区域设定稳定的宽度和高度。在加载之前预留足够空间，防止周围页面跳动，并在产品支持的真实断点上测试工具栏和首页。
在决定组合方式之前，先对比官方的 Doconut 实时演示。这些演示涵盖多种 .NET 与前端集成风格，包括专门的 iframe 示例，帮助您区分官方支持的路径与看似可行的代码片段。
将访问决策保留在服务器端
宿主页面绝不应决定用户是否可以查看文档。在渲染预览路由之前，应用应：
- 对请求进行身份验证。
- 对请求的文档和租户进行授权。
- 通过服务器控制的标识符解析文档。
- 仅在上述检查通过后通过查看器打开文档。
- 在不泄露存储细节的情况下返回通用的未找到或禁止状态。
不透明的标识符有助于保持 URL 整洁，但它本身并不提供授权。对页面、缩略图、搜索、批注、导出和打印请求都执行相同的检查。
决定宿主与查看器的通信方式
应用视图可以直接调用自身组件。iframe 则需要更窄的契约。仅定义宿主真正需要的事件，例如：
- 预览就绪
- 文档打开失败
- 当前页码变化
- 会话过期
- 用户请求关闭预览
如果使用 postMessage，请同时验证 event.origin 与消息结构。生产环境中不要接受通配符来源，且绝不要通过消息传递凭证、存储位置或原始文档内容。
将浏览器限制视为深度防御
iframe 并非自动隔离。sandbox 属性可以降低功能，但过于严格的取值也可能导致查看器脚本、下载或同源行为失效。请从官方文档中针对您的集成列出的最小能力集开始，并结合您的内容安全策略进行测试。
同时检查：
- 预览路由的
frame-ancestors或X-Frame-Options - 宿主页面的
frame-src - 如果 iframe 需要会话，则同站点 Cookie 行为
- 包含路由标识符的 URL 的 Referrer 策略
- 显示敏感内容的页面的缓存头
这些控制属于外围应用和基础设施。查看器组件无法为您的租户和威胁模型自行选择合适的策略。
设计加载、错误与过期状态
空白矩形并不是有用的错误提示。为宿主页面提供明确的状态，以应对授权失败、不受支持的输入、文件损坏、超时以及会话过期等情况。措辞应可操作且不泄露内部路径或异常细节。
对于长文档，在准备首页时保持查看器容器不变。如果用户可以在不离开页面的情况下切换文档，请取消过时的请求，并在加载下一个项目之前重置可见标题、页数和焦点。
可访问性与键盘行为
为每个 iframe 提供有意义的 title。让预览能够通过键盘访问，提供可见方式将焦点返回宿主页面，并避免在自定义覆盖层中陷入焦点。若查看器拥有自己的键盘快捷键，请记录与您产品外壳快捷键的冲突。
在业务规则允许的情况下，可提供受控的下载或替代呈现作为可访问的回退方案。不要仅仅因为回退而添加公共文件链接。
实用验证清单
发布前，请验证完整的请求路径，而不仅仅是初始页面加载：
- 已授权用户能够打开被允许的文档。
- 来自其他租户的用户无法复用预览 URL。
- 对查看器相关端点的直接请求同样会经过授权检查。
- 刷新、后退导航和会话过期会产生可理解的状态。
- 预览在受支持的视口尺寸和缩放级别下保持可用。
- 浏览器控制台错误和网络请求失败能够在监控中被捕获。
- 存储和应用日志不记录机密信息或完整文档 URL。
结论
最易维护的 Doconut 嵌入方式是拥有小而明确的契约。让 Doconut 负责其版本化文档中描述的文档查看角色，而您的应用则掌控身份、授权、路由、保留、浏览器策略以及用户反馈。当您准备在本地评估官方示例时，请使用官方的 Doconut 下载资源，而不是从无关文章中复制源码。