jquick-pdf 超详细入门教程Java 轻量级 HTML 模板生成 PDF 工具引入Java 后端做 PDF 导出最先遇到的往往不是业务难题而是排版难题用底层 API 逐个创建页面、字体、段落与表格代码会迅速膨胀成一套“坐标计算器”改一个标题或间距就要重新编译中文字体、长文本分页与服务端输出又会变成隐性维护成本。jquick-pdf 把数据和版式分开Java 准备数据类 HTML 模板描述页面渲染器输出 PDF。本文先走通一次完整生成。核心讲解版本基线与入口类本文以仓库事实io.github.paohaijiao:jquick-pdfx:4.0.0和 JDK 8 为准。核心入口是com.github.paohaijiao.executor.JQuickPdfFactory它接收模板、变量与页面配置返回 PDF 的byte[]。模板常用pdfbody固定文字必须用单引号如订单确认单变量用${customer}已注册资源用{name}。它是元素与样式边界明确的模板语言不是浏览器也不承诺支持完整 CSS。五步渲染链路一次生成可拆成五个节点排查问题也应沿这条链路定位读入把模板字符串、classpath 资源或磁盘文件读入内存。解析解析器识别根节点、元素、文本与style属性形成可遍历结构。绑定变量上下文替换${...}已注册资源替换{...}。布局与分页按字体、边距与尺寸计算位置并在超出页面时处理分页。渲染输出PDFBox 渲染器写入内存流工厂取出最终字节。工厂内部持有JContext与JPdfConfig因此一次请求应创建一次工厂不要跨请求复用带有业务变量的实例。三种执行方式对比方法模板来源适用场景executeContent(String)内存字符串单元测试、动态拼装的短模板executeResource(String)classpath 资源随制品发布的版本化模板如report.txtexecuteFile(String)磁盘文件外置模板目录、需要单独更新的版式三者都返回byte[]既可写文件也可直接写 HTTP 响应流。bind 与 bindAll 语义bind(String,Object)绑定单变量bindAll(MapString,Object)批量绑定变量名必须与${name}完全一致缺失变量不会自动补值。bind返回工厂自身因此可链式调用。JQuickPdfFactory.create()与new JQuickPdfFactory()等价。配置页面可调用pageSize(...)、margins(top,right,bottom,left)也可构造JPdfConfig传入工厂。模块构成最小场景只需jquick-pdfx。矢量图表再引入jquick-pdf-svg30 图表jquick-pdf-data提供图表配置模型如JOption、JChartjquick-pdf-font提供内置 CJK 字体jquick-pdf-css提供 CSS 模型。文档层支持标题、段落、行内文本、块、列表、表格、图片、SVG、树与表单域并提供areaBreak、htmlPageBreak、lineSeparator等布局元素按需引入可避免基础导出携带全部图表代码。关键细节文本与变量语法单引号是文本语法而非装饰遗漏会导致解析异常${name}只做取值替换{name}用于图表、模板、树或 SVG 等已注册资源。变量应通过绑定传入禁止把用户输入拼进标签或style否则可能破坏语法并引入注入风险。样式与单位要点样式写在style属性中以分号分隔属性名支持驼峰与连字符互为别名可在同一声明中混用。尺寸可用px、pt、mm、cm、inpx按 96 DPI 折算1px 0.75pt。常用属性包括width、height、minHeight、maxWidth、relativePosition、margin*、padding*、verticalAlignment、backgroundColor、border、borderRadius、opacity文字可用fontFamilyNames、fontSize、fontColor、bold、italic、underline、textAlignment、characterSpacing。border采用“类型 宽度 颜色”如solid 1px #999borderRadius支持 1~4 个值。颜色支持颜色名、#RRGGBB、rgb()/rgba()与linear-gradient。需要提前知道的边界模板循环指令如for/each、rowSpan/colSpan合并单元格、直接渲染网络 URL 图片、表单提交动作与提交 URL、全局分页背景或全局水印、keepTogether绝对禁止分页这些能力在本文基线下均未证实不应写进方案假设。实战说明Maven 依赖使用 JDK 8、Maven 3.6pom.xml只需加入核心依赖dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-pdfx/artifactIdversion4.0.0/version/dependency运行时由 Maven 传递引入 Apache PDFBox 3.0.x、ANTLR4 runtime 与 SLF4J API模板由 ANTLR4 解析、PDFBox 直接绘制无浏览器、无 headless Chrome、无本地动态库。首次接入先执行mvn dependency:tree排除版本冲突再运行静态模板验证链路。QuickStartPdf 完整示例以下类可作为普通 Java 程序直接运行输出当前目录的quick-start.pdfimportcom.github.paohaijiao.executor.JQuickPdfFactory;importjava.nio.file.Files;importjava.nio.file.Paths;publicclassQuickStartPdf{publicstaticvoidmain(String[]args)throwsException{Stringtemplatepdfbodyh1 style\fontSize:24;textAlignment:center;fontColor:#1f4e79\订单确认单/h1p客户${customer}/pp订单号${orderNo}/ptable style\width:520px;border:solid 1px #999\trth商品/thth数量/thth金额/th/trtrtdJava 技术书/tdtd2/tdtd98.00/td/tr/table/body/pdf;// 为本次文档绑定业务变量并执行模板byte[]pdfnewJQuickPdfFactory().bind(customer,张三).bind(orderNo,NO-2026001).executeContent(template);Files.write(Paths.get(quick-start.pdf),pdf);}}结果预期与验证执行后应得到可正常打开的quick-start.pdf标题居中呈蓝色变量替换为实际值表格带 1px 灰色边框。验证顺序固定为“文件生成 → 可打开 → 中文正常 → 数据一致 → 分页符合预期”失败时先查标签闭合与单引号再查绑定键名与样式。数据准备与选型边界报表通常在服务层把金额、日期与状态格式化为展示值再通过bind注入模板从而不被 ORM 字段名、空值与业务枚举牵着走列表用listli明细用table图片用image src... alt...分页可用样例验证过的htmlPageBreak或areaBreak指定。选型上相比 iText 与 PdfBox 的底层 API它更适合结构化文档与快速迭代相比浏览器截图它无需 Chrome部署更轻但完整网页兼容与浏览器专属 CSS 仍需评估其他方案。总结五个节点决定成败读入、解析、绑定、布局分页、渲染输出排查应逐层验证。语法固定文本用单引号变量用${name}资源用{name}样式以分号分隔且支持驼峰/连字符别名。工程固定先跑通静态模板再依次加入绑定、样式、分页与真实数据。适用边界与常见误区它面向规则明确的结构化业务文档不是完整 HTML/CSS 实现也不能替代底层绘图库最常见的错误是遗漏文本单引号、跨请求复用携带变量的工厂、把用户输入拼进模板以及在服务器上忽略中文字体。版本基线jquick-pdfx 4.0.0、JDK 8许可证与版本强相关上线前请核对 README 版本对照表更多示例见 GitHub 仓库。