Silurus/ooxml：基于浏览器的像素级忠实 Office 文档渲染方案

背景

在 Web 开发中，直接在浏览器端查看 Office Open XML (OOXML) 格式文档（如 .docx、.xlsx、.pptx）一直是一个痛点。传统的解决方案通常依赖于后端转换服务（将文档转换为 PDF 或图片）或笨重的第三方库，这往往导致渲染效果失真、加载速度慢或隐私数据泄露风险。

近期，一个名为 Silurus/ooxml 的项目在 Hacker News 上引发了关注。该项目的最大亮点在于其代码生成方式：整个代码库——包括 Rust 解析器、TypeScript 渲染器、测试和工具链——均由 Anthropic 的 AI 助手 Claude 通过迭代提示（iterative prompting）实现，仓库中不存在任何人工编写的业务应用代码。

该项目旨在提供一个基于浏览器的 OOXML 文档查看器，能够利用 HTML Canvas 元素实现像素级（Pixel-faithful）的高保真渲染，同时保持极高的灵活性和性能。

核心内容

技术架构与实现原理

Silurus/ooxml 的核心架构采用了“解析与渲染分离”的设计，充分利用了现代 Web 技术栈的优势：

1. Rust 解析与 WebAssembly (Wasm)：

   • 针对 DOCX、XLSX 和 PPTX 三种格式，分别使用 Rust 编写了解析器。
   • 这些解析器通过 wasm-pack 编译为 WebAssembly 模块（.wasm）。
   • Wasm 模块在 Web Worker 中运行，负责解析 OOXML 归档文件，并将其转换为 JSON 数据模型，随后发送回主线程。

2. Canvas 2D API 渲染：

   • 渲染逻辑使用 TypeScript 编写，基于 HTML Canvas 2D API。
   • 渲染过程在主线程执行，以确保 Canvas 能够共享文档的 FontFaceSet。如果将渲染移至 OffscreenCanvas（在 Worker 中），由于 Worker 拥有独立的字体注册表，可能会静默回退到系统字体，导致文本测量和换行位置与安装的 Web 字体主题产生细微差异，从而影响像素级保真度。

3. 无头引擎（Headless Engine）：

   • 除了内置的 UI 查看器，该项目还暴露了无头引擎 API（如 DocxDocument、XlsxWorkbook、PptxPresentation）。
   • 开发者可以将任何自定义的 Canvas 传入这些引擎，从而构建自定义 UI（如滚动视图、缩略图网格、主从窗格等），而不必局限于内置查看器。

4. 共享核心库 (@silurus/ooxml-core)：

   • 三个格式的渲染器共同依赖一个共享核心包，包含统一的图表渲染器（支持柱状图、折线图、面积图、雷达图、瀑布图）、形状辅助函数（如 resolveFill、applyStroke、buildCustomPath）以及自动调整大小工具。

数学公式渲染支持

对于 DOCX 和 PPTX 文件中包含的 OMML 数学公式（m:oMath / m:oMathPara），该项目集成了 MathJax 和 STIX Two Math 字体引擎。

• 按需加载：该数学引擎体积较大（约 3 MB），因此设计为可选（opt-in）。
• Tree-shaking 优化：如果开发者不导入数学引擎，打包工具会将这 3 MB 的代码完全剔除。
• 离线可用：引擎完全自包含，无需网络请求或跨域访问。

安装与集成

项目通过 npm 发布，支持 npm 和 pnpm 安装。

• 包体积说明：虽然 npm 显示的 Unpacked Size 包含了所有入口点和可选的数学引擎，但实际应用中，开发者只需导入所需的格式入口（例如 @silurus/ooxml/pptx），未使用的部分会被自动剔除。
• 构建工具配置：
  • Vite：需添加 vite-plugin-wasm。
  • Webpack：需启用 experiments.asyncWebAssembly。

代码示例

基础用法（原生 JS/TS）：

import { DocxViewer } from '@silurus/ooxml/docx';
import { XlsxViewer } from '@silurus/ooxml/xlsx';
import { PptxViewer } from '@silurus/ooxml/pptx';

// DOCX 示例：调用者提供 Canvas
const canvas = document.getElementById('docx-canvas') as HTMLCanvasElement;
const docx = new DocxViewer(canvas);
await docx.load('/document.docx');
docx.nextPage();

// XLSX 示例：查看器管理自己的 Canvas 和标签栏
const container = document.getElementById('xlsx-container') as HTMLElement;
const xlsx = new XlsxViewer(container);
await xlsx.load('/workbook.xlsx');

// PPTX 示例：调用者提供 Canvas
const canvasPptx = document.getElementById('pptx-canvas') as HTMLCanvasElement;
const pptx = new PptxViewer(canvasPptx);
await pptx.load('/deck.pptx');
pptx.nextSlide();

数学公式渲染示例：

import { DocxViewer } from '@silurus/ooxml/docx';
import { math } from '@silurus/ooxml/math';

const canvas = document.getElementById('docx-canvas') as HTMLCanvasElement;
// 传入 math 引擎以启用公式渲染
const docx = new DocxViewer(canvas, { math }); 
await docx.load('/paper-with-equations.docx');

主流框架集成：

项目提供了 React 19、Vue 3.5 和 Angular 19 的完整集成示例，展示了如何利用 Hooks/Composition API 和 Signals 来管理 Canvas 引用、加载状态和幻灯片/页面切换逻辑。

关键要点

• AI 全栈生成：整个代码库由 Claude 通过迭代提示生成，无人工编写的应用代码，展示了 AI 辅助复杂全栈开发的潜力。
• 像素级保真：通过在主线程使用 Canvas 2D 并共享 FontFaceSet，确保了渲染结果与本地 Office 应用的高度一致，避免了字体回退导致的布局错位。
• 高性能解析：利用 Rust 编写解析器并编译为 WebAssembly，在 Web Worker 中处理耗时的文档解析任务，避免阻塞 UI 线程。
• 高度可定制：提供无头引擎 API，允许开发者将渲染结果绘制到任何自定义 Canvas 上，从而构建复杂的自定义 UI 组件（如缩略图预览、分屏查看等）。
• 极致的 Tree-shaking：数学引擎（MathJax + STIX Two Math）作为独立入口，仅在显式导入并传入查看器时才被打包，否则会被完全剔除，显著减小了包体积。
• 框架友好：原生支持 React、Vue 和 Angular 的最新版本，提供了清晰的集成模式。
• 离线优先：所有渲染逻辑均在客户端完成，无需后端服务，保障数据隐私且支持离线使用。

意义与影响

Silurus/ooxml 的出现标志着 Web 端文档查看技术的一个重要进步。它解决了长期以来 Web 应用难以高保真渲染复杂 Office 文档的问题，同时通过现代化的技术栈（Rust/Wasm + Canvas）保证了性能。

对于开发者而言，该项目提供了一种轻量级、无需后端依赖的解决方案，特别适用于需要处理敏感文档的隐私优先场景，或需要高度定制 UI 的企业级应用。此外，该项目作为 AI 生成复杂代码库的成功案例，也为 AI 辅助软件工程（AI-SE）提供了极具参考价值的实践范本，证明了 AI 在处理多语言、多模块、高性能要求的系统级代码生成方面的能力。