dompdf.js：纯前端HTML转PDF解决方案

dompdf.js是一个纯前端JavaScript库，能够将HTML转换为可编辑、非图片式、可打印的PDF文件。该库基于html2canvas和jsPDF构建，提供了一种在浏览器中直接生成PDF的简便方法。

## 核心特性

dompdf.js的主要特点包括：
- 纯前端实现，无需服务器端支持
- 生成可编辑的PDF文件（非图片格式）
- 支持自定义页面布局和样式
- 提供灵活的配置选项

## 安装方法

### CDN方式
最简单的方式是通过cdnjs引入：
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/dompdf.js/0.10.1/dompdf.bundle.min.js" integrity="sha512-GsLlZN/3F2ErC5ifS5QtgpiJtWd43JWSuIgh7mbzZ8zBps+dvLusV+eNQATqgA/HdeKFVgA5v3S/cIrLF7QnIg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
```

### NPM安装
```bash
npm install --save dompdf.js
```

**注意**：虽然可以通过NPM安装，但dompdf.js必须在浏览器环境中运行，不能在Node.js中运行。

### 原生JS
直接下载`dist/dompdf.bundle.min.js`并在HTML中引入：
```html
<script src="dompdf.bundle.min.js"></script>
```

## 基本用法

最简单的使用方式：
```js
var element = document.getElementById('element-to-print');
dompdf(element);
```

## 高级用法

dompdf.js提供了基于Promise的API，支持链式调用：

```js
var worker = dompdf();  // 或: var worker = new dompdf.Worker;
```

### Worker API方法

| 方法 | 参数 | 描述 |
|------|------|------|
| from | src, type | 设置PDF的源（HTML字符串或元素） |
| to | target | 将源转换为指定目标 |
| output | type, options, src | 根据指定的源路由到适当的输出方法 |
| save | filename | 保存PDF对象（创建用户下载提示） |
| set | opt | 设置指定属性 |
| get | key, cbk | 返回指定的属性 |

## 配置选项

dompdf.js可以通过`opt`参数进行配置：

```js
var element = document.getElementById('element-to-print');
var opt = {
  margin:       1,
  filename:     'myfile.pdf',
  image:        { type: 'jpeg', quality: 0.98 },
  html2canvas:  { scale: 2 },
  jsPDF:        { unit: 'in', format: 'letter', orientation: 'portrait' }
};

// 新Promise风格用法
dompdf().set(opt).from(element).save();

// 旧风格用法
dompdf(element, opt);
```

### 主要配置参数

| 名称 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| margin | number或array | `0` | PDF边距（jsPDF单位） |
| filename | string | `'file.pdf'` | 导出的PDF默认文件名 |
| pagebreak | object | `{mode: ['css', 'legacy']}` | 控制页面分页行为 |
| image | object | `{type: 'jpeg', quality: 0.95}` | 生成PDF的图像类型和质量 |
| enableLinks | boolean | `true` | 是否启用PDF超链接 |
| html2canvas | object | `{ }` | html2canvas配置选项 |
| jsPDF | object | `{ }` | jsPDF配置选项 |

## 页面分页控制

dompdf.js支持自动添加页面断点，可以通过以下方式控制：

### 分页模式
- `avoid-all`：自动添加分页以避免任何元素跨页分割
- `css`：根据CSS的`break-before`、`break-after`和`break-inside`属性添加分页
- `legacy`：在具有`dompdf__page-break`类的元素后添加分页

### 使用示例
```js
// 避免所有元素的分页，并在#page2el前添加分页
dompdf().set({
  pagebreak: { mode: 'avoid-all', before: '#page2el' }
});

// 启用所有模式，没有显式元素
dompdf().set({
  pagebreak: { mode: ['avoid-all', 'css', 'legacy'] }
});

// 没有模式，只有显式元素
dompdf().set({
  pagebreak: { before: '.beforeClass', after: ['#after1', '#after2'], avoid: 'img' }
});
```

## 图像类型和质量

可以通过设置`image`选项自定义从画布导出的图像类型和质量：

```js
image: { type: 'jpeg', quality: 0.95 }
```

支持的类型：`'png'`、`'jpeg'`和`'webp'`（仅Chrome支持）。质量设置仅对jpeg/webp有效，对png无效。

## 依赖项

dompdf.js依赖于以下外部包：
- [html2canvas](https://github.com/niklasvh/html2canvas)
- [jsPDF](https://github.com/MrRio/jsPDF)
- [es6-promise](https://github.com/stefanpenner/es6-promise)

如果使用未打包的版本，需要按顺序引入依赖项：
```html
<script src="es6-promise.auto.min.js"></script>
<script src="jspdf.min.js"></script>
<script src="html2canvas.min.js"></script>
<script src="dompdf.min.js"></script>
```

## 已知问题

1. **渲染问题**：html2canvas渲染引擎不完美，如果html2canvas没有正确渲染内容，无法修复
2. **节点克隆问题**：dompdf.js克隆内容的方式存在错误
3. **调整大小问题**：dompdf.js将根元素调整大小以适应PDF页面，导致内部内容"重新流动"
4. **渲染为图像**：所有内容都渲染为图像放入PDF，文本不可选择或搜索，文件大小较大
5. **Promise冲突**：可能与自定义Promise库冲突
6. **最大大小限制**：HTML5画布有最大高度/宽度限制，超过该值会失败

## 注意事项

- v0.10版本报告了一些问题，建议考虑继续使用v0.9.3版本
- 文本在生成的PDF中不可选择或搜索
- 大文件可能导致空白PDF
- 需要浏览器环境支持

dompdf.js为前端开发者提供了一种简便的HTML转PDF解决方案，特别适合需要在客户端生成PDF报告或文档的Web应用场景。

dompdf.js：纯前端HTML转PDF解决方案

评论已关闭

本文目录

分类

最新文章