Package Exports

@neosjs/html-to-pdf
@neosjs/html-to-pdf/package.json

Readme

HTML转PDF工具库

一个功能强大、高性能HTML转PDF工具，支持中文、图片、表格、分页、水印、自定义页眉页脚和页码，内置性能监控和错误处理。

NPM Version Npm Month Downloads Node Version License

✨ 特性

🎯 简单易用 - 简洁的API设计，几行代码即可生成PDF
🚀 高性能: 优化的图片处理和内存管理
📄 完整分页: 智能内容分页，支持页眉页脚
🎨 自定义样式: 支持自定义页眉、页脚、页码样式
📊 性能监控: 内置性能监控和错误追踪
🖼️ 图片支持: 支持图片、表格、复杂布局
🇨🇳 中文支持: 完美支持中文字体和排版
📏 边距控制: 灵活的页面边距配置
🔧 TypeScript: 完整的TypeScript类型支持
🎯 精确控制: 支持自定义纸张大小和方向
🔧 高度可配置: 丰富的配置选项满足各种需求

📦 安装

# 使用 pnpm (推荐)
pnpm add @neosjs/html-to-pdf

# 使用 npm
npm install @neosjs/html-to-pdf

# 使用 yarn
yarn add @neosjs/html-to-pdf

🚀 快速开始

基础用法

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
const url = URL.createObjectURL(blob)
const link = document.createElement('a')
link.href = url
link.download = 'document.pdf'
link.click()
URL.revokeObjectURL(url)

高级用法

import { generatePDF, LogLevel } 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',
  scale: 1.3,
  quality: 0.8,
  
  // 边距配置
  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: {
    show: true,
    fontSize: 12
  },
  
  // 性能监控
  performanceConfig: {
    enablePerformanceMonitoring: true,
    enableMemoryMonitoring: true,
    performanceThreshold: {
      screenshotTime: 5000,
      pdfGenerationTime: 10000,
      memoryUsage: 100
    }
  },
  
  // 日志回调
  logCallback: (log) => {
    console.log(`[${log.level}] ${log.message}`, log.data)
  }
})

📚 API 文档

generatePDF(config: PdfOptions)

生成PDF的主函数。

参数

contentDom: HTMLElement

要转换为PDF的DOM元素（必需）

coverDom?: HTMLElement

封面页DOM元素（可选）

paperSize?: PaperSize

纸张大小，默认为 'a4'

'a0' - A0
'a1' - A1
'a2' - A2
'a3' - A3
'a4' - A4
'a5' - A5
'a6' - A6
'a7' - A7
'a8' - A8

orientation?: PageOrientation

页面方向，默认为 'p'

'p' - 竖版
'l' - 横版

scale?: number

缩放比例，默认为 1.3

quality?: number

图片质量，默认为 0.75

margins?: MarginConfig

页面边距配置

interface MarginConfig {
  top?: number      // 上边距 (默认: 20px)
  bottom?: number   // 下边距 (默认: 20px)
  left?: number     // 左边距 (默认: 20px)
  right?: number    // 右边距 (默认: 20px)
  enabled?: boolean // 是否启用边距 (默认: true)
}

header?: HeaderConfig

页眉配置

interface HeaderConfig {
  content: string           // 页眉内容
  fontSize?: number         // 字体大小 (默认: 12px)
  fontColor?: string        // 字体颜色 (默认: #565D66)
  fontFamily?: string       // 字体族
  position?: 'left' | 'center' | 'right'  // 位置 (默认: center)
  border?: boolean          // 是否显示边框 (默认: false)
  height?: number           // 页眉高度
  autoHeight?: boolean      // 是否自动计算高度 (默认: true)
  minHeight?: number        // 最小高度 (默认: 20px)
  maxHeight?: number        // 最大高度 (默认: 60px)
  padding?: number          // 内边距 (默认: 8px)
}

页脚配置（与页眉配置结构相同）

pageNumber?: PageNumberConfig

页码配置

interface PageNumberConfig {
  show?: boolean    // 是否显示页码 (默认: true)
  fontSize?: number // 字体大小 (默认: 12px)
}

performanceConfig?: PerformanceConfig

性能监控配置

interface PerformanceConfig {
  enablePerformanceMonitoring?: boolean
  enableMemoryMonitoring?: boolean
  enableErrorTracking?: boolean
  performanceThreshold?: {
    screenshotTime?: number      // 截图时间阈值(ms)
    pdfGenerationTime?: number  // PDF生成时间阈值(ms)
    memoryUsage?: number        // 内存使用阈值(MB)
  }
}

logCallback?: (log: LogData) => void

日志回调函数

interface LogData {
  level: LogLevel
  message: string
  timestamp: number
  data?: any
  error?: Error
}

返回值

{
  blob: Blob,    // PDF文件的Blob对象
  pdf: JsPDF     // JsPDF实例，可用于进一步操作
}

工具函数

getPageDimensions(paperSize: PaperSize, orientation: PageOrientation)

获取纸张尺寸信息

clearCache()

清理图片缓存

getCacheStatistics()

获取缓存统计信息

createPerformanceMonitor(config?: any)

创建性能监控器实例

📝 示例

基础示例

<!DOCTYPE html>
<html>
<head>
    <title>基础示例</title>
</head>
<body>
    <div id="content">
        <h1>测试文档</h1>
        <p>这是一个测试文档的内容...</p>
    </div>
    
    <button onclick="generatePDF()">生成PDF</button>
    
    <script type="module">
        import { generatePDF } from '@neosjs/html-to-pdf'
        
        async function generatePDF() {
            try {
                const content = document.getElementById('content')
                const { blob } = await generatePDF({
                    contentDom: content,
                    paperSize: 'a4',
                    orientation: 'p'
                })
                
                // 下载PDF
                const url = URL.createObjectURL(blob)
                const link = document.createElement('a')
                link.href = url
                link.download = 'document.pdf'
                link.click()
                URL.revokeObjectURL(url)
            } catch (error) {
                console.error('PDF生成失败:', error)
            }
        }
        
        window.generatePDF = generatePDF
    </script>
</body>
</html>

带页眉页脚的示例

const { blob } = await generatePDF({
  contentDom: document.getElementById('content'),
  paperSize: 'a4',
  orientation: 'p',
  
  // 页眉
  header: {
    content: '公司文档',
    fontSize: 14,
    fontColor: '#333',
    position: 'center',
    border: true
  },
  
  // 页脚
  footer: {
    content: '机密文件',
    fontSize: 12,
    fontColor: '#666',
    position: 'left'
  },
  
  // 页码
  pageNumber: {
    show: true,
    fontSize: 12
  },
  
  // 边距
  margins: {
    top: 30,
    bottom: 30,
    left: 25,
    right: 25,
    enabled: true
  }
})

性能监控示例

const { blob } = await generatePDF({
  contentDom: document.getElementById('content'),
  
  // 性能监控
  performanceConfig: {
    enablePerformanceMonitoring: true,
    enableMemoryMonitoring: true,
    performanceThreshold: {
      screenshotTime: 5000,
      pdfGenerationTime: 10000,
      memoryUsage: 100
    }
  },
  
  // 日志回调
  logCallback: (log) => {
    switch (log.level) {
      case 'info':
        console.log(`✅ ${log.message}`, log.data)
        break
      case 'warn':
        console.warn(`⚠️ ${log.message}`, log.data)
        break
      case 'error':
        console.error(`❌ ${log.message}`, log.error)
        break
    }
  }
})

📄 License

🙏 致谢

jsPDF - PDF生成库
html-to-image - HTML转图片库

JSPM

@neosjs/html-to-pdf