渲染管线

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

第一步 — 解析格式查看器

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

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 会被复制到配置中，以便处理受保护的文档。

第一步b — 重定向模式（DefaultRender = false）

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

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

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

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

第二步 — 页面图像管线

渲染后的页面会在每次请求时按照固定顺序处理：

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

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

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

页面缓存

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

调整位置