iasei-html-to-pdf 测试插件

将 HTML 元素导出为 PDF 的浏览器端工具，基于 html2canvas + jspdf，支持自动分页与自定义纸张大小。

特性

• 通过元素 ID 一键导出 PDF
• 自动按 A4 高度计算分页点并插入 page-break 标记，避免内容被截断
• 支持自定义纸张大小与单位（mm / pt / cm / in / px）
• 根据 window.devicePixelRatio 自适应缩放，保证清晰度
• 返回 jsPDF 实例，可继续追加内容或自定义保存

安装

npm install iasei-html-to-pdf
# 或
pnpm add iasei-html-to-pdf

Peer Dependencies

| 依赖 | 版本 | |------|------| | html2canvas | ^1.4.1 | | jspdf | ^4.2.1 |

用法

基本用法

import html2pdf from 'iasei-html-to-pdf';

const pdf = await html2pdf({ id: 'myPrintHtml' });
pdf.save('document.pdf');

自定义缩放与偏移

const pdf = await html2pdf({
  id: 'myPrintHtml',
  scale: 2,       // canvas 缩放比例
  vOffest: 20,    // 页面顶部留白（pt）
});

自定义纸张大小

const pdf = await html2pdf({
  id: 'myPrintHtml',
  pageSize: {
    width: 210,
    height: 297,
  },
});

API

function html2pdf(params: {
  id: string;
  vOffest?: number;
  scale?: number;
  pageSize?: {
    width: number;
    height: number;
  };
}): Promise<jsPDF>;

参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | id | string | — | 需要导出的 DOM 元素 ID（必填） | | vOffest | number | 15 | PDF 顶部垂直留白（pt） | | scale | number | min(2.5, 2 * devicePixelRatio) | html2canvas 缩放比例，值越大越清晰 | | pageSize | { width, height } | A4 | 自定义纸张大小，未传时使用 A4（595×842pt） |

返回值

返回 Promise<jsPDF>，可调用 .save(filename) 下载，或继续操作 PDF 实例。

分页机制

1. 清理元素中历史的 .page-break 标记
2. 遍历子元素，当累计高度超过 A4 高度（1123 - vOffest * 2 - 20 px）时，为该元素添加 page-break 类
3. 以每个 page-break 为分页点，将整张 canvas 切片后逐页写入 PDF

如需手动控制分页位置，可预先为目标元素添加 page-break 类。

注意事项

• 仅适用于浏览器环境，需要 document / window 全局变量
• 跨域图片需配置 CORS，否则 html2canvas 可能渲染失败
• 导出前请确保目标元素已完整渲染（图片加载完成等）

开发

pnpm install
pnpm run build    # tsc 构建 dist

License

MIT