浏览器端像素级 OOXML 渲染：Silurus 的 Canvas 架构与保真策略

Web 端预览 Office 文档长期面临保真度难题。传统方案要么依赖服务端转 PDF / 图片，增加延迟与带宽成本；要么用 HTML/CSS 近似还原，却在复杂排版、字体度量、形状渲染上出现肉眼可见的偏差。Silurus（@silurus/ooxml）提供了一条新路径：在浏览器内直接解析 OOXML 压缩包，通过 Canvas 2D API 实现像素级精确渲染，同时保持文档的交互能力。

架构选择：为何不用 DOM 而选 Canvas

OOXML（DOCX/XLSX/PPTX）是面向可编辑文档设计的复杂格式，包含丰富的排版语义、主题系统、DrawingML 形状与图表。将其映射到 HTML/CSS 需要大量近似转换，任何字体回退、行高计算或盒模型的差异都会导致换行位置偏移。Silurus 的解法是将渲染层与浏览器排版引擎解耦：Rust 编写的解析器编译为 WebAssembly，在 Web Worker 中完成 ZIP 解压与 XML 解析，生成 JSON 中间模型；主线程的 Canvas 2D 渲染器则完全控制绘制过程，包括字体加载、文本测量、路径填充与描边。这种架构确保跨浏览器的一致性 —— 只要 Canvas 实现符合规范，渲染结果就 deterministic。

一个关键细节是渲染必须在主线程执行。OffscreenCanvas 虽可在 Worker 中绘图，但其拥有独立的 FontFaceSet，无法感知主线程通过 @font-face 注入的自定义字体，导致系统字体回退与度量差异。Silurus 因此将解析（CPU 密集型）放在 Worker，渲染（依赖字体）留在主线程，通过 postMessage 传递轻量级绘制指令。

功能覆盖与工程取舍

Silurus 支持 DOCX、XLSX、PPTX 三种格式，功能覆盖相当完整。PPTX 渲染支持 130+ 预设形状、渐变与图案填充、阴影与发光效果、图表（柱状 / 折线 / 面积 / 雷达 / 散点 / 气泡 / 饼图）、视频音频播放等。DOCX 支持页眉页脚、分节符、目录、修订追踪、OMML 数学公式（通过 MathJax 可选加载）。XLSX 支持条件格式、迷你图、切片器、冻结窗格与单元格选择交互。

值得注意的是其模块化设计。数学引擎（MathJax + STIX Two Math，约 3MB）是独立入口，仅在需要时导入，打包工具可将其 tree-shake 掉。同样，各格式也是独立子包（@silurus/ooxml/docx、/xlsx、/pptx），应用只需引入所需格式，避免冗余代码。

可落地的安全与性能参数

Silurus 在安全性上做了多层防护。所有渲染输出到 Canvas，不将文档中的脚本、链接或表单注入 DOM，天然隔离 XSS 风险。ZIP 解压默认限制单条目 512MB，防止 zip bomb 攻击，可通过 maxZipEntryBytes 参数调整：

new PptxViewer(canvas, { maxZipEntryBytes: 64 * 1024 * 1024 }); // 64MB

字体加载策略默认保守：主题字体与 Office 字体度量替代方案不会自动请求 Google Fonts，除非显式传入 useGoogleFonts: true。这对 GDPR 合规场景尤为重要，建议生产环境通过 @font-face 自托管所需字体。XML 解析使用 roxmltree，默认不解析外部实体，阻断 XXE 攻击向量。

生态集成与扩展能力

除了浏览器组件，Silurus 提供多形态配套工具。@silurus/ooxml-node 暴露相同的 WASM 解析器给 Node.js，适用于 CI 检查与无头渲染流水线。ooxml-mcp-server 将解析器封装为 MCP 工具，供 AI Agent（Claude、Copilot 等）直接读取文档结构。VS Code 扩展则提供原生预览体验，并可选注册 MCP Server 实现 AI 辅助阅读。

对于需要将文档内容纳入 LLM 工作流的场景，@silurus/ooxml-markdown 可将 PPTX/DOCX/XLSX 转为 GitHub 风格 Markdown，压缩比约 21 倍（相比原始 XML），比纯文本提取器仅增加 8% 体积。

实施 checklist

• 构建配置：Vite 用户需添加 vite-plugin-wasm，webpack 用户启用 experiments.asyncWebAssembly
• 框架适配：提供 React 19、Vue 3.5、Angular 19、Svelte 5、SolidJS 1.9、Qwik 2 的完整示例代码
• 字体策略：生产环境建议自托管字体，关闭 useGoogleFonts，确保度量一致性
• 内存限制：根据文档大小调整 maxZipEntryBytes，不信任来源的文件建议设为 64MB 以下
• 交互增强：利用无头引擎（DocxDocument、PptxPresentation）自定义 UI，实现缩略图网格、主从面板等布局

浏览器端像素级文档渲染不再是服务端专属的奢侈品。通过 Rust/WASM 的高性能解析与 Canvas 2D 的精确绘制，Silurus 证明了在保持安全隔离的前提下，Web 平台同样能够承载复杂的 Office 文档保真预览需求。

资料来源

• npm / Libraries.io: @silurus/ooxml 包文档与 API 说明
• GitHub: yukiyokotani/office-open-xml-viewer 源码与架构图

web