渲染管线

在 OpenDocumentAsync 与到达浏览器的 PNG 之间，有两个不同的阶段：查看器解析（哪个引擎加载文档，在每次打开时决定一次）和页面处理（每次请求时对每个页面图像的处理）。了解这两者可以解释为何某种格式会以特定方式渲染——以及 DefaultRender 实际切换了什么。

阶段 1 — 解析格式查看器

工厂通过格式目录将文件扩展名映射到查看器，具有三个优先级层次：

1. 自定义查看器优先。 通过 DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) 注册的任何查看器都优先于所有内置查看器。
2. 内置系列查看器。 目录将每个可查看的扩展名映射到一个查看器系列——Word、Excel、PowerPoint、Pdf、Cad、Dgn、Image、Tiff、Psd、Email、Visio、Project、Xps、Epub、Txt、Html、Mht、Dcn——每个系列都有自己的引擎适配器。如果拥有许可证的插件为相同扩展名提供查看器，插件查看器将取代内置查看器。AddDoconut() 在启动时验证已注册插件的授权；工厂回退到内置查看器是一条防御性的运行时规则。
3. 仅插件格式。 某些扩展名根本没有内置查看器——DICOM（.dcm）仅通过 DICOM 插件存在。若在没有所需功能的情况下打开，会抛出：

LicenseException: This document type requires the 'Dicom' plugin license.

如果没有查看器声明支持某个扩展名，则会抛出：

FormatNotSupportedException: Document format '<extension>' is not supported.

解析完成后，配置确定下来：如果你传入了显式的配置对象，则使用它；否则使用目录中该格式的默认配置。DocOptions.Password 会复制到配置中，以用于受保护的文档。

阶段 1b — 重定向模式（DefaultRender = false）

大多数按格式的配置都公开一个 DefaultRender 标志。它在两条根本不同的路径之间进行选择：

• DefaultRender = true — 文档以原生方式渲染，直接生成页面图像。
• DefaultRender = false — 文档首先 在内存中转换为 PDF，源引擎被释放，随后由 PDF 查看器接管。生成的 PDF 嵌入真实文本，因此全文搜索能够得到像素级的原生高亮；管线会为重定向的 PDF 强制开启 AllowSearch 和 AllowCopy，因为转换对用户是透明的。

XPS 以及目录中 MHT 的默认设置使用重定向路径。PDF 投影可以为 HTML 和 Microsoft Project 等格式提供原生搜索。如果生成的 PDF 包含没有文本层的图像，标准查看器将无法搜索这些像素。

当你需要带文本的 PDF 投影时，请使用重定向模式——代价是在文档打开时进行一次预先转换。

阶段 2 — 页面图像管线

渲染的页面在每次请求时通过以下固定顺序处理：

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• 水印 — 根据许可证状态（缺少许可证、临时或订阅许可证过期、域名无效、版本错误）以及 DocOptions.Watermark 中的自定义文本来应用。拥有合法许可证的应用程序——或有效的临时许可证——且未设置自定义水印时会跳过此步骤。
• 旋转/翻转 — 用户在小部件中为每页设置的状态（90°/180°/270°，水平/垂直翻转）会存储在会话中，并在该页的每次后续渲染时应用。
• 缩放 — 通过将渲染的页面缩放到请求的目标尺寸来生成缩略图和缩放级别；0 表示以原始尺寸提供。
• 注释烧录 — 已保存的注释会绘制到位图上，使导出和页面图像能够显示这些注释。
• 编码 — 结果使用池化的内存流编码为 PNG，并直接写入 HTTP 响应。

中间件内部的错误会以 PNG 错误图像（白底红字）的形式返回，而不是 HTTP 错误页面，这样小部件可以在页面区域显示它们。

页面缓存

BaseConfig.CachePages（默认 true）在文档会话期间将渲染的页面图像保存在内存中，因此重新访问页面时不会重新渲染。BaseConfig.ImageResolution（25–300 DPI，0 = 格式默认）是主要的质量/内存调节参数；每种格式的默认值在其配置页面上有文档说明。

调整位置