danielwestendorf/breezy-pdf-lite

BreezyPDF Lite：HTML转PDF服务

镜像概述和主要用途

BreezyPDF Lite是一个基于无头Google Chrome的HTML转PDF服务，可快速部署。通过提交HTML内容，即可获取由Chrome渲染的PDF文件。适用于Web应用、命令行工具等场景，支持自定义PDF配置和动态内容渲染。

核心功能和特性

• Chrome渲染引擎：使用无头Google Chrome确保HTML/CSS/JS的准确渲染
• 灵活配置：通过HTML meta标签自定义PDF参数（页面尺寸、边距、方向等）
• 页眉页脚模板：支持自定义页眉页脚，包含动态元素（日期、页码、总页数等）
• 多完成触发方式：支持回调函数、事件、元素检测、变量和定时器等多种内容加载完成触发机制
• 安全访问：通过私有令牌（PRIVATE_TOKEN）控制API访问权限

使用场景和适用范围

• Web应用生成PDF报告、发票、合同等文档
• 命令行工具批量转换HTML为PDF
• 需要动态JavaScript渲染内容的PDF生成
• 集成到各类编程语言（Ruby、PHP、Node.js等）的应用中

使用方法和配置说明

1. 提交HTML转换请求

通过POST请求提交HTML内容，获取PDF文件。需使用私有令牌进行身份验证。

示例（curl命令）：

sh
curl -X POST -H 'Authorization: Bearer PRIVATE_TOKEN_DEFINED_IN_SERVER_ENVIRONMENT' \
  http://url-of-your-breezy-pdf-lite-server/render/html \
  -d "`curl https://raw.githubusercontent.com/danielwestendorf/breezy-pdf-lite/master/sample.html`" \
  -o example.pdf

2. 通过meta标签配置PDF（可选）

在提交的HTML中添加meta标签自定义PDF参数，支持以下配置：

示例：

html
<meta name="breezy-pdf-width" content="10">
<meta name="breezy-pdf-landscape" content="true">

3. 页眉页脚模板

通过HTML模板定义页眉页脚，支持以下动态类：

注意：模板中的图片需使用DataURI编码，样式需内联定义。

4. 完成触发方式

指定内容加载完成的触发条件，默认使用5000ms定时器。支持以下方式（按优先级排序）：

4.1 回调函数

定义全局回调函数，内容加载完成时调用：

html
<meta name="breezy-pdf-callback" content="myWorkHereIsDoneCallback">
<meta name="breezy-pdf-timeout" content="3000"> <!-- 超时时间（ms），默认5000 -->

js
function() {
  // 业务逻辑处理
  window.myWorkHereIsDoneCallback(); // 调用回调通知渲染完成
}

4.2 事件触发

监听指定元素的自定义事件：

html
<meta name="breezy-pdf-event" content="myCustomEvent">
<meta name="breezy-pdf-element" content="#myContainer"> <!-- 元素选择器，默认document -->
<meta name="breezy-pdf-timeout" content="3000">

js
var event = new CustomEvent('myCustomEvent');
document.getElementById('myContainer').dispatchEvent(event);

4.3 元素检测

检测指定CSS选择器的元素是否存在：

html
<meta name="breezy-pdf-element" content="#last-page > #last-element">
<meta name="breezy-pdf-timeout" content="3000">

js
// 动态创建目标元素
var lastElement = document.createElement('div');
lastElement.id = 'last-element';
document.getElementById('last-page').appendChild(lastElement);

4.4 变量检测

检测全局变量是否定义：

html
<meta name="breezy-pdf-variable" content="myWorkHereIsDoneVariable">

js
// 内容加载完成后定义变量
window.myWorkHereIsDoneVariable = true;

4.5 定时器

固定等待时间后渲染：

html
<meta name="breezy-pdf-timer" content="10000"> <!-- 等待10秒 -->

部署方式

Docker部署

sh
docker run -it -p 5002:5002 \
  -e "DEBUG=breezy-pdf-lite:*" \
  -e "PORT=5002" \
  -e "PRIVATE_TOKEN=YOURSUPERSECRETTOKEN" \
  danielwestendorf/breezy-pdf-lite:latest

Heroku部署

点击下方按钮一键部署： ![Deploy]([***]

其他部署方式

1. 安装Node.js和yarn
2. 执行yarn install安装依赖
3. 配置环境变量（见下方配置说明）
4. 启动服务：node index.js

配置说明

通过环境变量配置服务：

客户端库

支持多种编程语言的客户端库：

• Ruby/Rack/Rails: https://github.com/danielwestendorf/breezy_pdf_lite-ruby
• PHP: https://github.com/jitendra-1217/breezy-pdf-lite-php
• Node.js: https://github.com/danielwestendorf/breezy-pdf-lite-client-js
• 其他语言客户端（开发中）：Browserside JS、Java、Swift、Python、Go