渲染管线

从文档到页面图像

在 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 插件存在。打开没有所需功能的文件会抛出:
text
LicenseException: This document type requires the 'Dicom' plugin license.

如果没有查看器声明该扩展名,则会抛出:

text
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 — 页面图像管线

渲染的页面在每次请求时通过固定顺序进行处理:

text
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 = 格式默认)是主要的质量/内存调节;每种格式的默认值在其配置页面上有文档说明。

单节点渲染 vs. 多节点渲染

以上内容描述了单节点按需渲染打开文档的会话。若部署中有一个节点负责渲染并发布整个制品集,而其他节点从共享存储提供这些页面,则使用不同的读取路径——参见 分布式部署。

Linux 上的字体

页面使用服务器上已安装的字体绘制。在 Linux 上,需要在首次打开文档之前安装字体配置库(RHEL 和 Fedora 上为 fontconfig):

bash
apt-get update && apt-get install -y libfontconfig1

如果没有它,打开文档会因 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. 而失败。这是 Doconut 唯一需要的系统包;libgdiplus 并非必需。

它的依赖会带来基本的字体集(DejaVu),因此文档可以即开即渲染。若文档请求服务器未安装的字体——如典型 Linux 镜像中的 Calibri、Arial 或 Times New Roman——系统会使用最接近的已安装字体,因此文本宽度和换行可能与 Windows 不同。若需更接近 Windows 的输出,请安装度量兼容的替代字体 fonts-liberation、fonts-crosextra-carlito 和 fonts-crosextra-caladea;为其他文字体系添加 fonts-noto-core 或 fonts-noto-cjk,或将自己的 .ttf/.otf 文件复制到 /usr/share/fonts/ 并运行 fc-cache -f。

Alpine 及其他基于 musl 的发行版不受支持。

调整位置

需求调优方式
更清晰的页面在格式配置中使用 ImageResolution
在 HTML/EPUB/email/MHT/MPP 上实现精确文本搜索在格式配置中使用 DefaultRender = false
在大型文档上降低内存占用使用 CachePages = false,并显式关闭会话
在每页上添加自定义水印使用 DocOptions.Watermark

此页面对您有帮助吗?