@neosjs/html-to-pdf
浏览器端的 HTML 转 PDF 工具库,底层基于 jsPDF 与 html-to-image。支持中文排版、图片、表格与复杂布局,提供智能内容分页、自定义页眉页脚与页码、水印、PDF 加密、边距与纸张控制,并内置性能监控与错误处理,提供完整的 TypeScript 类型支持。
安装
sh
pnpm add @neosjs/html-to-pdfsh
npm i @neosjs/html-to-pdfsh
yarn add @neosjs/html-to-pdf快速上手
获取要转换的 DOM 元素,调用 generatePDF 即可:
ts
import { generatePDF } from '@neosjs/html-to-pdf'
// 获取要转换的 DOM 元素
const contentElement = document.getElementById('content')
// 生成 PDF
const { blob, pdf } = await generatePDF({
contentDom: contentElement,
paperSize: 'a4',
orientation: 'p'
})
// 下载 PDF
pdf.save('document.pdf')也可以使用默认导出的 HtmlToPdf 类,自行维护实例:
ts
import HtmlToPdf from '@neosjs/html-to-pdf'
const htmlToPdf = new HtmlToPdf()
const { blob, pdf } = await htmlToPdf.generatePDF({
contentDom: document.getElementById('content'),
paperSize: 'a4',
orientation: 'p'
})高级配置
ts
import { generatePDF } from '@neosjs/html-to-pdf'
const { blob, pdf } = await generatePDF({
// 内容 DOM(必需)
contentDom: document.getElementById('content'),
// 封面 DOM(可选)
coverDom: document.getElementById('cover'),
// PDF 背景色
backgroundColor: '#FFFFFF',
// 纸张与方向
paperSize: 'a4',
orientation: 'p',
// 边距配置
margins: {
top: 20,
bottom: 20,
left: 20,
right: 20,
enabled: true
},
// 页眉配置
header: {
content: '文档',
fontSize: 14,
fontColor: '#333',
position: 'center',
border: true,
padding: 10
},
// 页脚配置(结构同页眉)
footer: {
content: '机密文件',
fontSize: 12,
fontColor: '#666',
position: 'left',
border: false,
padding: 8
},
// 页码配置
pageNumber: {
enabled: true,
fontSize: 12
},
// 插件列表(此处为水印插件)
plugins: [
{
name: 'watermark',
config: {
text: '水印文件',
fontSize: 12,
color: '#ddd',
opacity: 0.5,
rotation: 30,
repeat: true, // 启用重复
repeatMode: 'grid' // 网格模式
},
enabled: true
}
],
// 加密设置
encryption: {
userPassword: '123456', // 用户打开 PDF 的密码
ownerPassword: '654321', // 拥有者密码
userPermissions: ['print'] // 'print' | 'modify' | 'copy' | 'annot-forms'
},
// 性能监控
performanceConfig: {
enablePerformanceMonitoring: true,
enableMemoryMonitoring: true,
performanceThreshold: {
screenshotTime: 5000,
pdfGenerationTime: 10000,
memoryUsage: 100
}
},
// 质量优化配置
optimizationConfig: {
scale: 1.5, // 值越大越清晰,但更消耗性能(默认 1.5)
quality: 0.8,
usePngFormat: true,
enableAntialiasing: true,
enableHighPrecision: true
},
// 日志回调
logCallback: (log) => {
console.log(`[${log.level}] ${log.message}`, log.data)
}
})API
generatePDF(config: PdfOptions)
生成 PDF 的主函数,返回 { blob: Blob, pdf: JsPDF },blob 为 PDF 文件的 Blob 对象,pdf 为 JsPDF 实例,可用于进一步操作。
主要参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
contentDom | HTMLElement | — | 要转换为 PDF 的 DOM 元素(必需) |
coverDom | HTMLElement | — | 封面页 DOM 元素 |
paperSize | PaperSize | 'a4' | 纸张大小,可选 'a0' ~ 'a8' |
orientation | PageOrientation | 'p' | 页面方向:'p' 竖版、'l' 横版 |
margins | MarginConfig | 见下文 | 页面边距配置 |
header | HeaderConfig | 见下文 | 页眉配置 |
footer | FooterConfig | 同页眉 | 页脚配置 |
pageNumber | PageNumberConfig | 见下文 | 页码配置 |
plugins | Plugin[] | — | 插件列表(如水印插件) |
encryption | EncryptionConfig | — | 加密配置 |
performanceConfig | PerformanceConfig | — | 性能监控配置 |
optimizationConfig | OptimizationConfig | 见下文 | 质量优化配置 |
logCallback | (log: LogData) => void | — | 日志回调函数 |
MarginConfig
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
top | number | 0 | 上边距(px) |
bottom | number | 10 | 下边距(px) |
left | number | 30 | 左边距(px) |
right | number | 30 | 右边距(px) |
enabled | boolean | true | 是否启用边距 |
HeaderConfig / FooterConfig
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | string | — | 页眉/页脚内容 |
fontSize | number | 12 | 字体大小(px) |
fontColor | string | #dddddd | 字体颜色 |
fontFamily | string | Microsoft YaHei | 字体族 |
fontWeight | string | normal | 字体粗细(normal / bold / 数值等) |
fontStyle | string | normal | 字体样式(normal / italic / oblique) |
position | string | center | 位置:left / center / right |
border | boolean | false | 是否显示边框 |
borderHeight | number | 1 | 边框高度(px) |
autoHeight | boolean | true | 是否自动计算高度 |
minHeight | number | 40 | 最小高度(px) |
maxHeight | number | 60 | 最大高度(px) |
padding | number | 8 | 内边距(px) |
EncryptionConfig
| 属性 | 类型 | 说明 |
|---|---|---|
userPassword | string | 用户打开 PDF 文件的密码 |
ownerPassword | string | PDF 拥有者打开文件的密码 |
userPermissions | ('print' | 'modify' | 'copy' | 'annot-forms')[] | 用户权限列表 |
OptimizationConfig
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
scale | number | 1.5 | 缩放比例,值越大越清晰,也越消耗性能 |
quality | number | — | 图片质量 |
usePngFormat | boolean | true | 是否使用 PNG 格式(避免 JPEG 压缩损失) |
pngCompressionLevel | number | 0 | PNG 压缩级别(0-9,0 为无压缩) |
enableAntialiasing | boolean | true | 是否启用抗锯齿 |
enableHighPrecision | boolean | true | 是否启用高精度绘制 |
其他导出
| 导出项 | 说明 |
|---|---|
HtmlToPdf(默认导出) | 类,实例方法包含 generatePDF 等 |
generate | HtmlToPdf 的单例实例 |
getPageDimensions(paperSize, orientation) | 获取纸张尺寸信息 |
clearCache() | 清理图片缓存 |
getCacheStatistics() | 获取缓存统计信息 |
getPerformanceStats() | 获取性能统计信息 |
getLogs() | 获取日志列表 |
LogLevel / PaperSize / PageOrientation | 常用枚举 |
TIP
生成大文档时,可通过 logCallback 结合 performanceConfig 观察截图与 PDF 生成耗时,必要时调低 optimizationConfig.scale 换取性能。