ElixirOffice 是一款面向微软 Office 用户的开源办公套件，其浏览器端 PDF 导出功能完全在你的浏览器中完成：点击"另存为 PDF"或打印时，文档内容、图片乃至字体文件都不会上传到服务器，而是由浏览器本地的导出器直接生成 PDF 文件。本文将带新手一步步揭开这项隐私友好型 PDF 导出的工作原理、性能数据与使用方法。

ElixirOffice 浏览器端 PDF 导出是什么

先看一眼 ElixirOffice 的界面——它保留了 Word 熟悉的选项卡、功能区与快捷键，而 PDF 导出就藏在"文件"菜单里：

它的核心承诺写在项目文档 docs/client-pdf.md 的第一句话里：

PDF 导出发生在浏览器中，使用与屏幕完全一致的字体——包括只存在于用户电脑上的字体——而文档和字体都不会被发送到服务器。

具体入口有三个，行为完全一致：

导出长文档时，界面会显示"正在创建 PDF…第 n 页，共 N 页"的进度遮罩，页面之间浏览器保持响应，不会卡死界面。

传统方式：为什么服务器端导出要"上传"文档

理解这项技术的价值，先要看看它替代了什么。传统的 Web 办公套件导出 PDF 时，流程是这样的：

1. 浏览器把"下载 PDF"请求发给服务器；
2. 服务器端 C++ 转换器（x2t）重新打开文档、重新排版；
3. 服务器端的 PDF 写入器（PdfWriter）生成文件再传回浏览器。

这条路线有两个先天缺陷：

• 内容必须上传：文档文本要通过网络到达服务器，才能被转换；
• 字体不可控：服务器只能使用自己安装的字体，看不到你电脑里的 Calibri 或学校专用字体，排版可能和屏幕上不一样。

也就是说，服务器生成的 PDF 用的是"服务器的字体"，而浏览器端导出的优势恰恰在于：屏幕显示用的什么字体，PDF 里就是什么字体。

核心原理：编辑器早就在生成"绘图命令流"

揭秘的关键发现是：浏览器里的 JavaScript 引擎（sdkjs）本身就能逐页产出整份文档的"绘图命令流"（asc_nativeGetPDF）。传统架构中，这条命令流被送往 C++ 端回放成 PDF；而 ElixirOffice 证明——回放器不非得是 C++，JavaScript 写入器（或编译为 WebAssembly 的原生PdfWriter）完全可以胜任。

这条命令流有两个对导出极为友好的特性：

• 字体按名字引用：流里记录的是屏幕上实际显示的那个字体名（含替换字体），写入器只需按名字取到"屏幕正在用的字体字节"即可；
• 文本以字形标识符绘制：连字、Wingdings 项目符号、阿拉伯语等复杂文本的整形（shaping）结果早已由编辑器计算好并写入流中，浏览器端无需再装任何整形库。

捕获过程逐页进行，每页的命令字节直接交给写入器（内存只受单页限制），每 40 毫秒让出一次主线程，因此长文档导出时界面依然流畅。

字体为什么从不离开你的电脑

这是整套设计最巧妙的部分。字体文件其实早就在浏览器内存里了：

• 你在屏幕上看到的每个字，都是引擎（sdkjs）用某个字体文件渲染出来的——服务器字体或本机字体，其字节都缓存在编辑器的字体索引（AscFonts.g_fonts_streams）中；
• 如果开启了"Use my fonts"（使用我的字体，基于 Chrome/Edge 的 Local Font Access API），你电脑中安装的字体也只注册进这个内存索引，从未上传；
• 导出 PDF 时，写入器直接就地读取这些内存中的字体字节，按字形子集嵌入 PDF——没有任何网络请求。

文档中的图片同理：导出时用fetch读取浏览器缓存中屏幕已经加载过的图片 URL，不产生新上传。

结果就是导出全程零携带数据的请求。自动测试 tests/client-pdf/run.mjs 专门校验了这一点：没有任何带请求体的请求，没有携带文档文本或字体字节的网络帧，没有指向其他来源的请求。本地字体功能的完整设计可阅读 docs/localfonts.md。

质量与性能：实测数据一览

项目用 30 份真实语料（74 页）做了严格对比测试（基准工具 tools/client-pdf/bench.mjs 与 tools/client-pdf/gate.sh）：

两个值得注意的惊喜：

1. 文件更小：因为字体按实际使用子集嵌入，浏览器版 PDF 总体只有服务器版的 37% 大小；
2. 某些细节反而更准：例如点线引导符（leader dots），服务器版按整数截断字形宽度导致点线漂移，浏览器版保留屏幕上的精确位置。

当浏览器无法复现时：自动回退到服务器

ElixirOffice 的原则是"绝不产出破损或静默降级的文件"。当遇到浏览器端无法处理的情况时，系统会自动改用服务器生成 PDF，并用一条不阻塞的消息说明原因。触发回退的场景包括：

• 📝 文档含表单字段；
• 🔒 字体许可证（fsType）禁止嵌入，或为纯位图字体；
• ⚠️ 字体无法读取或子集化、图片无法读取；
• 📄 超过 3000 页的超长文档；
• ❓ 命令流中出现未知命令。

注意：只有 PDF/A 导出（归档格式）、"另存副本"到云存储、邮件合并等功能仍由服务器处理——这些本就需要服务器参与。PDF/A 与本地导出的分工详见 docs/wasm.md。

新手快速上手：三步用对本地导出

1. 打开文档：在浏览器中用 ElixirOffice 打开 Word 文档（界面如下，熟悉 Office 的用户无需学习成本）；

2. 直接导出：文件 > Download as > PDF，或按Ctrl+P打印。PDF 已在浏览器中生成，进度条会提示"第 n 页，共 N 页"；
3. （可选）确认开关：文件 > Options 的 "PDF" 组里有"Create PDF files in the browser"开关，默认开启；关闭后所有 PDF 改由服务器生成。该偏好按浏览器保存在localStorage。

💡 小技巧：如果你的文档使用了电脑上才有、而服务器没有的字体，先点击界面提示条上的"Use my fonts"，之后导出的 PDF 就会精确复现你在屏幕上的排版——包括老师常用的手写体等校用字体，而一个字节都不会上传。

相关文档与源码导航

想深入了解的同学可以按图索骥：

• 浏览器端 PDF 导出设计与完整测试报告：docs/client-pdf.md
• WebAssembly 运行时与"PDF-only runtime"说明：docs/wasm.md
• 本地字体接入（Local Font Access API）：docs/localfonts.md
• 字体替换规则与免费字体包：docs/fonts.md
• 捕获与写入器接口：sdkjs/common/clientpdf/、web-apps/apps/common/main/lib/elixir-clientpdf/
• 端到端自动化测试：tests/client-pdf/run.mjs（浏览器场景）、tests/client-pdf/writer.test.mjs（写入器单元检查）

一句话总结：ElixirOffice 把"谁能生成 PDF"的答案从服务器搬进了你的浏览器——屏幕用什么字体，PDF 就用什么字体；文档留在原地，字体留在原地，只有最终的 PDF 文件落到你的下载文件夹。🔐