Skip to content

@neosjs/html-to-pdf ​

浏览器端的 HTML 转 PDF 工具库,底层基于 jsPDF 与 html-to-image。支持中文排版、图片、表格与复杂布局,提供智能内容分页、自定义页眉页脚与页码、水印、PDF 加密、边距与纸张控制,并内置性能监控与错误处理,提供完整的 TypeScript 类型支持。

安装 ​

sh
pnpm add @neosjs/html-to-pdf
sh
npm i @neosjs/html-to-pdf
sh
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 实例,可用于进一步操作。

主要参数 ​

参数类型默认值说明
contentDomHTMLElement—要转换为 PDF 的 DOM 元素(必需)
coverDomHTMLElement—封面页 DOM 元素
paperSizePaperSize'a4'纸张大小,可选 'a0' ~ 'a8'
orientationPageOrientation'p'页面方向:'p' 竖版、'l' 横版
marginsMarginConfig见下文页面边距配置
headerHeaderConfig见下文页眉配置
footerFooterConfig同页眉页脚配置
pageNumberPageNumberConfig见下文页码配置
pluginsPlugin[]—插件列表(如水印插件)
encryptionEncryptionConfig—加密配置
performanceConfigPerformanceConfig—性能监控配置
optimizationConfigOptimizationConfig见下文质量优化配置
logCallback(log: LogData) => void—日志回调函数

MarginConfig ​

属性类型默认值说明
topnumber0上边距(px)
bottomnumber10下边距(px)
leftnumber30左边距(px)
rightnumber30右边距(px)
enabledbooleantrue是否启用边距

HeaderConfig / FooterConfig ​

属性类型默认值说明
contentstring—页眉/页脚内容
fontSizenumber12字体大小(px)
fontColorstring#dddddd字体颜色
fontFamilystringMicrosoft YaHei字体族
fontWeightstringnormal字体粗细(normal / bold / 数值等)
fontStylestringnormal字体样式(normal / italic / oblique)
positionstringcenter位置:left / center / right
borderbooleanfalse是否显示边框
borderHeightnumber1边框高度(px)
autoHeightbooleantrue是否自动计算高度
minHeightnumber40最小高度(px)
maxHeightnumber60最大高度(px)
paddingnumber8内边距(px)

EncryptionConfig ​

属性类型说明
userPasswordstring用户打开 PDF 文件的密码
ownerPasswordstringPDF 拥有者打开文件的密码
userPermissions('print' | 'modify' | 'copy' | 'annot-forms')[]用户权限列表

OptimizationConfig ​

属性类型默认值说明
scalenumber1.5缩放比例,值越大越清晰,也越消耗性能
qualitynumber—图片质量
usePngFormatbooleantrue是否使用 PNG 格式(避免 JPEG 压缩损失)
pngCompressionLevelnumber0PNG 压缩级别(0-9,0 为无压缩)
enableAntialiasingbooleantrue是否启用抗锯齿
enableHighPrecisionbooleantrue是否启用高精度绘制

其他导出 ​

导出项说明
HtmlToPdf(默认导出)类,实例方法包含 generatePDF 等
generateHtmlToPdf 的单例实例
getPageDimensions(paperSize, orientation)获取纸张尺寸信息
clearCache()清理图片缓存
getCacheStatistics()获取缓存统计信息
getPerformanceStats()获取性能统计信息
getLogs()获取日志列表
LogLevel / PaperSize / PageOrientation常用枚举

TIP

生成大文档时,可通过 logCallback 结合 performanceConfig 观察截图与 PDF 生成耗时,必要时调低 optimizationConfig.scale 换取性能。