jsPDF 中文显示实战指南addFileToVFS 与 addFont 字体加载全流程【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDFjsPDF 是一款在浏览器端生成 PDF 的轻量级库内置的 14 种 PDF 标准字体只覆盖 ASCII 字符集所以直接用默认字体写中文常常出现乱码或空白。解决路径并不复杂把一份包含中文字形glyph的 TTF 字体文件加载进文档再用setFont指定它。本文基于仓库中的真实源码和示例说明加载方式、字体选择、效果验证和常见坑适合第一次处理 jsPDF 中文字体的开发者。什么场景下中文会失灵先定位问题避免在错误方向上花时间。用默认字体如helvetica调用doc.text(中文, 20, 20)时典型表现有两种输出乱码字符汉字位置缺失表现为空白或宽度异常。仓库 README 对此有明确说明PDF 标准字体受限于 ASCII codepage想要 UTF-8 文本比如 Chinese text必须集成一个自带所需字形的自定义字体否则就会显示乱码。所以中文显示从来不是开关而是三件套的组合TTF 字体文件 加载进文档 用 setFont 指定。理解这一点后后面所有操作都是围绕这三件事展开。最小落地方式两步把字体装进文档核心流程只有两步先用addFileToVFS把 TTF 文件放进文档的 vFSvirtual file system虚拟文件系统再用addFont声明字体。官方 README 推荐的做法如下const doc new jsPDF(); // 用 fetch 把 MyFont.ttf 读成 binary string const myFont ...; // 字体文件内容 doc.addFileToVFS(MyFont.ttf, myFont); doc.addFont(MyFont.ttf, MyFont, normal); doc.setFont(MyFont);addFont三个参数分别对应vFS 中的文件名、代码里使用的字体名可自定义、字体样式。装好字体后输出中文就是普通文本调用doc.setFontSize(16); doc.text(jsPDF 中文显示实战, 20, 30); doc.save(chinese-demo.pdf);预期效果打开生成的 PDF中文正常显示、字距正常。如果仍乱码问题通常在字体文件本身见下文而不是代码顺序。如果不想自己写 fetch 逻辑仓库提供了fontconverter/fontconverter.html工具把本地 TTF 转成 base64 编码的 js 文件并附带注册代码引入项目后即可直接调用addFont。仓库示例 examples/js/japanese.js 和 examples/js/arabic.js 正是这种用法——前者加载MouhitsuBold.ttf输出日文后者加载Amiri-Regular.ttf输出阿拉伯文。这两个示例可以直接当作中文字体加载的模板改写。怎么选一份合适的中文 TTF 字体文件字体文件决定了显示效果和最终 PDF 体积选型时看三点字形覆盖面字体必须包含你要输出的汉字。只输出一部分常用字时选覆盖范围够用的开源字体即可test/reference/目录下有若干 TTF 可供测试参考。体积中文字体普遍在数 MB 量级而字体最终会被嵌入生成的 PDF输出文件会比纯英文文档明显更大。文本量小的页面建议做字体子集化subsetting只保留实际用到的字符。从 src/modules/ttfsupport.js 可以看到字体元数据中维护了glyIdsUsed已使用字形 ID 列表这就是输出时做字形裁剪的实现基础。样式配套需要粗体中文时要单独准备一份 bold TTF并用相同字体名、bold样式再注册一次只注册了 normal 却在代码里setFont(name, bold)效果会不符合预期。验证中文显示效果三个检查点生成 PDF 后建议按三个点确认结果而不只是看一眼完整性全部汉字显示完整无乱码、无缺字空白混排中英文混排段落中通过setFont在默认字体和中文字体间切换换行与行距没有异常跳变尺寸setFontSize以 pt 为单位控制字号同样字号下全角汉字的视觉宽度约为半角拉丁字符的两倍这是正常现象不是 bug。仓库的测试用例 test/specs/unicode.spec.js 里有先放 vFS 再注册的完整写法可以作为自检脚本的参考doc.addFileToVFS(PTSans.ttf, PTSans); doc.addFont(PTSans.ttf, PTSans, normal);把字体名换成你的中文字体模式完全一致。常见坑位排查四类报错与现象结合 src/modules/ttfsupport.js 中addFont事件处理器的逻辑实际踩坑基本集中在四类Font does not exist in vFS调用了addFont但对应文件名从未通过addFileToVFS放入 vFS处理逻辑会直接抛错。检查两个调用的先后顺序与文件名拼写即可。Font is not stored as string-data in vFSvFS 里放的数据类型不对比如传入了Uint8Array而非 binary string。把 TTF 读成二进制字符串或改用 fontconverter 生成的 base64 文件。部分字乱码、部分正常字体覆盖面不足该字符的 glyph 根本不在字体文件里。换覆盖面更广的字体或避开这些字。PDF 体积明显变大属于预期行为字体被嵌入了文档。缓解手段是字体子集化与 PDF 压缩而不是删功能。 一个实用技巧排查时先打印确认addFileToVFS的文件名与addFont第一参数字符串完全一致绝大多数字体不存在的问题出在这个细节上。备选路径与相关入口如果你的真实场景是把一段 HTML 转成 PDF而非逐行画文本可以先评估 jsPDF 的 html 模块src/modules/html.js示例位于examples/html2pdf/目录。无论走哪条路径中文字体的注册方式都一致字体必须在使用前完成加载setLanguage、splitTextToSize等排版功能对已注册的自定义字体同样生效。收尾建议把字体加载顺序 字体覆盖面做成团队内的检查清单——先确认 TTF 里有目标字符再按addFileToVFS → addFont → setFont的顺序接入中文显示问题大多在接入阶段就能定位清楚。【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考