@neosjs/html-to-pdf

一个高性能的 HTML 转 PDF 工具，支持中文、图片、表格、分页、水印、自定义页眉页脚、页码，并解决分页截断问题。

NPM Version Npm Month Downloads Node Version License

✨ 特性

🚀 高性能: 优化的内存管理和异步处理
📄 智能分页: 自动处理分页截断问题
🎨 样式支持: 完整支持 CSS 样式和布局
♨️ 方向支持: 支持纵横方向
📊 性能监控: 内置性能监控和报告
🔧 高度可配置: 丰富的配置选项
🛡️ 错误处理: 完善的错误处理机制
📱 响应式: 支持不同设备和屏幕尺寸

📦 安装

npm install @neosjs/html-to-pdf
# 或
yarn add @neosjs/html-to-pdf
# 或
pnpm add @neosjs/html-to-pdf

🚀 快速开始

import HtmlToPdf from "@neosjs/html-to-pdf";

// 创建转换器实例
const converter = new HtmlToPdf({
  elementId: "my-element",
  wholeNodeClass: "no-break",
  enablePerformanceMonitor: true,
  fileName: "文档",
  format: "a4",
  orientation: "p",
  pageMargin: {
    top: 10,
    bottom: 10,
    left: 10,
    right: 10,
  },
  header: {
    content: "文档标题",
    align: "center",
    fontSize: 12,
    color: "#333",
  },
  footer: {
    content: "第 {page} 页，共 {total} 页",
    align: "center",
    fontSize: 10,
    color: "#666",
  },
});

// 生成PDF
try {
  converter.generatePDF().then((blob) => {
    console.log("PDF生成成功:", blob.size, "bytes");
  });
} catch (error) {
  console.error("PDF生成失败:", error);
}

更多示例

/**
 * HTML转PDF使用示例
 */

// 基础使用示例
async function basicExample() {
  const converter = new HtmlToPdf({
    elementId: "my-content",
    wholeNodeClass: "no-break",
    fileName: "文档",
    format: "a4",
    orientation: "p",
  });

  try {
    const blob = await converter.generatePDF();
    console.log("PDF生成成功:", blob.size, "bytes");
  } catch (error) {
    console.error("PDF生成失败:", error);
  }
}

// 高级配置示例
async function advancedExample() {
  const converter = new HtmlToPdf({
    elementId: "my-content",
    wholeNodeClass: "no-break",
    ignoreElementsClass: "ignore-pdf",
    intervalHeight: 10,
    enablePerformanceMonitor: true,
    fileName: "文档",
    format: "a4",
    orientation: "p",
    html2canvas: {
      scale: 2.0,
      quality: 0.9,
      useCORS: true,
      allowTaint: true,
      backgroundColor: "#ffffff",
      logging: false,
    },
    pageMargin: {
      top: 10,
      bottom: 10,
      left: 10,
      right: 10,
    },
    header: {
      content: "文档",
      align: "center",
      fontSize: 14,
      color: "#333333",
      border: true,
    },
    footer: {
      content: "第 {page} 页，共 {total} 页",
      align: "center",
      fontSize: 10,
      color: "#666666",
    },
  });

  try {
    const blob = await converter.generatePDF();

    // 获取性能报告
    const report = converter.getReport();
    console.log("性能报告:", {
      总耗时: `${report.totalTime}ms`,
      平均耗时: `${report.averageTime}ms`,
      最慢步骤: report.slowestStep,
      最快步骤: report.fastestStep,
    });

    // 打印详细报告
    converter.printSummary();

    console.log("PDF生成成功:", {
      文件大小: `${(blob.size / 1024 / 1024).toFixed(2)}MB`,
      总页数: report.steps.length,
    });
  } catch (error) {
    console.error("PDF生成失败:", error);
  }
}

// 错误处理示例
async function errorHandlingExample() {
  const converter = new HtmlToPdf({
    elementId: "non-existent-element",
    wholeNodeClass: "no-break",
  });

  try {
    const _blob = await converter.generatePDF();
    console.log("PDF生成成功");
  } catch (error: any) {
    console.error("错误类型:", error.code);
    console.error("错误信息:", error.message);
    console.error("错误详情:", error.details);
  }
}

// 性能监控示例
async function performanceExample() {
  const converter = new HtmlToPdf({
    elementId: "my-content",
    wholeNodeClass: "no-break",
    enablePerformanceMonitor: true,
  });

  // 手动计时
  converter.startTimer("自定义步骤");

  // 模拟一些操作
  await new Promise((resolve) => setTimeout(resolve, 1000));

  converter.endTimer("自定义步骤");

  try {
    const _blob = await converter.generatePDF();

    // 获取所有日志
    const logs = converter.getLogs();
    console.log("所有性能日志:", logs);

    // 导出性能数据
    const data = converter.exportData();
    console.log("性能数据:", data);
  } catch (error) {
    console.error("PDF生成失败:", error);
  }
}

⚙️ 配置选项

基础配置

选项	类型	默认值	说明
`elementId`	`string \| HTMLElement`	-	要转换的 DOM 元素
`wholeNodeClass`	`string`	-	不允许被截断元素的样式类名
`ignoreElementsClass`	`string`	-	要忽略的元素的类名
`intervalHeight`	`number`	`5`	不允许被截断元素之间的间隔高度
`enablePerformanceMonitor`	`boolean`	`false`	是否开启性能监控
`format`	`PaperFormat`	`'a4'`	纸张大小
`orientation`	`Orientation`	`'p'`	方向
`fileName`	`string`	-	生成的文件名称
`open`	`boolean`	`false`	是否打开 PDF
`pageMargin`	`PageMargin`	`{top:10,bottom:10,left:10,right:10}`	页边距
`header`	`HeaderFooter`	-	页眉配置
`footer`	`HeaderFooter`	-	页脚配置
`html2canvas`	`Html2CanvasOptions`	-	生成 Canvas 配置

html2canvas 配置

选项	类型	默认值	说明
`scale`	`number`	`1.5`	缩放比例
`quality`	`number`	`0.75`	图片质量
`useCORS`	`boolean`	`true`	是否使用 CORS
`allowTaint`	`boolean`	`true`	是否允许跨域图片
`backgroundColor`	`string`	`'#ffffff'`	背景颜色
`logging`	`boolean`	`false`	是否开启日志

📊 性能监控

const converter = new HtmlToPdf({
  elementId: "my-element",
  enablePerformanceMonitor: true,
});

converter.generatePDF();

// 获取性能报告
const report = converter.getReport();
console.log("总耗时:", report.totalTime, "ms");
console.log("平均耗时:", report.averageTime, "ms");
console.log("最慢步骤:", report.slowestStep);

// 打印详细报告
converter.printSummary();

// 导出性能数据
const data = converter.exportData();