jsPDF：3行代码让网页嵌入“下载为PDF”按钮——客户端 PDF 生成完整指南

【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF

jsPDF 是一个在客户端生成 PDF 文档的开源 JavaScript 库：在浏览器或 Node 里跑，几行代码就能产出包含文本、图像、表单的文档，不需要服务器端处理。本文基于仓库的真实内容，讲清它的定位、上手方式和容易踩的坑。

为什么“下载为 PDF”不再需要后端

导出 PDF 的常规做法是：前端把数据发给服务器，由服务器用 PDF 库拼好再回传——多一次网络往返，多一个服务端依赖。jsPDF 的思路相反：文件直接在页面里（或 Node 脚本里）拼装完成。项目的一句话描述是 "Client-side JavaScript PDF generation for everyone"，MIT 许可，目前由 yWorks 共同维护。

对发票、证书、报表导出这类场景，“把这一页存成 PDF”的按钮几乎零部署成本。

3行代码生成第一个 PDF

先npm install jspdf，jsPDF 的最小用法示例如下：

import { jsPDF } from "jspdf"; const doc = new jsPDF(); // 默认 A4、纵向、单位 mm doc.text("Hello world!", 10, 10); doc.save("a4.pdf");

构造函数可指定orientation、unit（mm/in/pt/px）和format（A4 或自定义宽高，如[4, 2]）。在 Node 中会自动加载 node 构建，save写入当前目录；npm 包还提供 es、node、umd 三种构建和面向旧浏览器的 polyfills 文件。

能力拆解：按 src/modules/ 各取所需

核心在src/jspdf.js，能力拆成 src/modules/ 下的独立文件，构建时按需组合：

• addimage.js：嵌入图像，PNG/JPEG/GIF/BMP/WebP 各有支持模块，JPEG 支持 NONE/FAST/MEDIUM/SLOW 四档压缩；
• html.js：把 HTML 片段转成 PDF（依赖 html2canvas）；
• acroform.js：文本框、复选框、单选组、下拉框等表单字段；
• ttfsupport.js：自定义 TTF 字体，配合addFileToVFS；
• total_pages.js：putTotalPages自动页码，另有svg.js、context2d.js、split_text_to_size.js（自动换行）、setlanguage.js、outline.js等。

下图是仓库 examples 里的演示素材，展示图像嵌入效果：

中文乱码怎么破：必须手动挂 TTF 字体

这是新手最常踩的坑：PDF 内置的 14 个标准字体只覆盖 ASCII，用doc.text写中文会出乱码。需要内嵌 TTF 字体，且字体文件本身要包含目标字形：

doc.addFileToVFS("MyFont.ttf", myFontBinary); doc.addFont("MyFont.ttf", "MyFont", "normal"); doc.setFont("MyFont");

也可用仓库里的 fontconverter/fontconverter.html 把 TTF 预先转成 base64 的 js 文件直接引入。examples/js/japanese.js 与 examples/js/russian.js 都是现成参考。

三个必须知道的坑

1. html 属于可选依赖：html2canvas（传入字符串 HTML 时还有 dompurify）只在调用html方法时才动态加载，Webpack 会自动拆成独立 chunk；不用它建议声明为 external，避免白打包。
2. 两套 API 模式并存：合并 yWorks fork 后，变换矩阵、pattern 等高级功能只在 advanced 模式可用，需用doc.advancedAPI(doc => {...})包裹；默认 compat 模式保持旧 API 与插件兼容。
3. 安全细节：用户输入先清洗再传入；Node 下 jsPDF 默认限制读取本地文件，官方推荐用node --permission --allow-fs-read=...由运行时强制权限。

去哪里学：示例、API 文档与测试用例

• examples/：basic.html（文本）、images.html（图像）、html2pdf/showcase.html（HTML 转换），builder.html 是浏览器里的“页面设计器”；
• docs/：jsdoc 生成的完整 API 参考；
• test/specs/：五十多个 spec 文件，test/reference/ 存放每个用例的参考 PDF，便于对照验证输出；
• types/index.d.ts：自带 TypeScript 类型声明。

【免费下载链接】jsPDFClient-side JavaScript PDF generation for everyone.项目地址: https://gitcode.com/gh_mirrors/js/jsPDF