PDF 导出 plugin-api-pdf
约 724 字大约 2 分钟
...
2026-09-28
插件说明
@sv-print/plugin-api-pdf 为打印模板实例挂载 toPdf 方法，用于导出 PDF。原理：每页 DOM 通过 snapdom 截图为 JPEG，再嵌入 jsPDF（2.x）合成 PDF 文件。
核心能力：
- 挂载
template.toPdf(printData, nameOrOptions?, oldOpt?)，返回 Deferred promise - 页级进度回调
onProgress - 输出类型支持
blob/bloburl/pdfobjectnewwindow/dataurl（对应jspdf.output(type)） - 可覆盖纸张尺寸（
paperWidth/paperHeight，pt）、截图清晰度（pixelRatio）与 JPEG 质量（quality）
第三方依赖：jspdf 2.x + @zumer/snapdom。
npm install @sv-print/plugin-api-pdf示例代码
唯一注册入口 hiprint.register（异步），须在创建模板之前注册：
import pluginApiPdf from '@sv-print/plugin-api-pdf';
await hiprint.register({
plugins: [pluginApiPdf()], // 工厂函数，可传 config // 与 plugin-api-pdf3 二选一，不可同时注册
});
const template = new hiprint.PrintTemplate(options); // 须在 register 之后创建模板
// "text" 是元素的字段名(field)
const printData = { text: '这是打印时显示的文本' };
const res = await template.toPdf(printData, 'pdf名称', {
isDownload: false, // 不自动下载
type: 'blob', // 默认 blob，支持 blob/bloburl/pdfobjectnewwindow/dataurl
onProgress: (cur, total) => {
console.log('toPdf 进度', Math.floor((cur / total) * 100) + '%');
},
});
console.log('toPdf', res);高级用法
toPdf 参数
第二个参数 nameOrOptions 可传字符串（文件名）或配置对象：
| 参数 | 默认 | 说明 |
|---|---|---|
| name | sv-print-{时间戳}.pdf | 文件名 |
| isDownload | true | 是否触发下载 |
| type | 'blob' | jspdf.output 类型：blob/bloburl/pdfobjectnewwindow/dataurl |
| onProgress(cur, total) | - | 页级进度回调 |
| pixelRatio | dpr | 截图清晰度（scale=0.75） |
| paperWidth/paperHeight | 取模板纸张 | 纸张尺寸，pt |
| quality | 0.8 | JPEG 质量 |
注意事项
plugin-api-pdf与plugin-api-pdf3二选一，不可同时注册（都挂载toPdf）- 需要 jspdf 3.x 时请使用 plugin-api-pdf3，两者 API 完全一致，仅 jspdf 大版本不同
- 所有 api 插件依赖
globalThis.$（jQuery Deferred）与globalThis.hinnn，由 sv-print 内核提供 - 截图方案下文字为图片，不可选中；需要文字可选中的矢量 PDF 请使用 plugin-api-pdf-vector
常见问题
plugin-api-pdf 和 plugin-api-pdf3 怎么选？
两者 API 完全一致，仅 jsPDF 大版本不同：plugin-api-pdf 使用 jspdf 2.x，plugin-api-pdf3 使用 jspdf 3.x。项目依赖哪个版本的 jsPDF 就选对应插件；二者都挂载 toPdf，只能注册其中一个。
如何导出 PDF 但不自动下载？
传 isDownload: false，并通过 type 指定返回形态：blob（Blob 对象，适合自行上传）、bloburl、pdfobjectnewwindow、dataurl（适合内嵌预览）。返回值为 Deferred promise，支持 .then / await。
版权所有
版权归属：sv-print