jsPDF中文显示速通指南：4步搞定中文字体注册与自动换行
【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF
控制台没有任何报错，下载下来的 PDF 却是一排排方框——这是 jsPDF中文显示 最常见的翻车现场。下面按“转字体 → 注册字体 → 排版换行 → 压缩产物”的动线，把中文字体完整接进文档。
jsPDF 默认只内置 Helvetica、Times-Roman 等 14 款 PDF 标准字体，字符集止步于 ASCII。中文码点在这些字体里没有字形，写入后只能渲染成方框，这就是乱码的根因。解法只有一个方向：注册一款自带中文字形的 TTF 字体。
第一步 拿到字体：用 fontconverter 转出注册脚本
- 打开仓库自带的转换器 fontconverter/fontconverter.html
- 填写字体名（如
simhei）与样式（normal / bold） - 选中本地 .ttf 文件，点 Create
- 浏览器会下载一个 .js 文件：TTF 被编码成 base64 字符串，并附带注册代码
- 把生成的 .js 引入项目，jsPDF 初始化后字体即自动生效
不想走转换器的话，也可以用fetch把 .ttf 读成二进制字符串，手动走下面三步。
第二步 注册字体：addFileToVFS → addFont → setFont
// 字体写入虚拟文件系统，注册为 simhei 并切换过去
doc.addFileToVFS('simhei.ttf', base64Data); doc.addFont('simhei.ttf', 'simhei', 'normal'); doc.setFont('simhei');addFont的第一个参数要和addFileToVFS的文件名一致；setFont传的是字体名（第二个参数），别传成文件名。
第三步 排版：maxWidth 一行解决自动换行
// 指定最大宽度自动折行，行高系数放大到 1.4
doc.setFontSize(14); doc.text('你好，这是一段中文排版示例，超宽时自动折行。', 10, 30, { maxWidth: 180, lineHeightFactor: 1.4 });- 不传
maxWidth（或传 0）时不会折行 - 默认行高系数是 1.15，中文场景建议 1.3~1.5
长文本先过一遍 splitTextToSize
// 按宽度切分成多行，再整体写入
const lines = doc.splitTextToSize(longText, 180); doc.text(lines, 10, 50);跨页场景下，用返回的行数检查 y 坐标，避免文字被切到下一页之外。
第四步 压缩产物：把文件体积压下去
// 生成时开启压缩
const doc = new jsPDF({ unit: 'mm', format: 'a4', compression: true });字体是体积大头。全文档只用到几十个汉字时，先用字体子集工具裁掉未用字符，再配合compression，效果最明显。
📋 避坑速查表
| 现象 | 原因 | 一句话处理 |
|---|---|---|
| 中文渲染成方框 | 标准字体无中文字形 | 注册中文 TTF 并 setFont 切换 |
| 已注册仍乱码 | TTF 本身缺中文字形 | 换支持中文的字体（思源黑体等） |
| 行距挤成一团 | 行高系数默认 1.15 偏小 | text 里传lineHeightFactor: 1.4 |
| 文字溢到下一页 | 未做换页判断 | splitTextToSize 拿到行数后检查 y |
| 文件几十 MB | 整字库全量嵌入 | 字体子集化 +compression: true |
| addFont 报错 | 文件名两处不一致 | addFileToVFS 与 addFont 用同一文件名 |
📚 延伸阅读
text全部选项与addFont签名见 README.md；非拉丁字体接法可参考 examples/japanese.js 与 examples/russian.js；完整 API 文档在 docs/ 目录。
【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
