jquick-pdf 交互式表单开发：按钮与复选框在签收确认场景的落地
引入
签收确认、复核勾选这类场景存在两种流程形态：纸质流程要求打印后在纸上打勾，电子流程希望直接在 PDF 里勾选并留痕。用底层 iText/PDFBox 手工创建 AcroForm，需要自行创建字段、设置 widget、处理外观，代码量与出错面都不小。jquick-pdf 把表单域作为模板元素提供，<button>、<checkbox>（含 checked 属性）、<comboBoxField>、<textArea> 都已出现在本地 sample 中。
需要提前划定边界：已证实的只有元素存在与 checked 属性；字段名、提交动作、外观细节等高级配置在已核实事实中未证实，本文不做任何假设。依赖为 io.github.paohaijiao:jquick-pdfx:4.0.0，JDK 8+。
核心讲解
表单域在模板中的位置
表单域与普通标签平级，写在 <pdf><body>…</body></pdf> 内即可，前后可用 <h1>、<p> 等元素做说明文字。一份签收回执页面通常包含四部分：标题、处理结果说明、若干复选框、一个提交按钮。复选框的标签文本用单引号包裹，作为该字段的可见文案。
<checkbox> 与 checked
checked 是布尔型标记属性，出现即表示初始为选中状态。示例中“同意”项默认勾选、“需复核”项默认未勾选，默认勾选状态是可设计的。样式属性同样可以施加在表单域上，示例用 fontColor:blue 区分重点项。初始状态由 checked 决定，因此“默认同意”与“默认不同意”应在业务层面确认后再定；勾选项的文案与顺序建议与纸质表单逐项对应，便于后续人工核对。
<button> 的角色
<button> 生成按钮类表单域，承载“提交/确认”这类动作入口，示例中按钮文本为 '提交'，也可用 fontColor 等样式调整外观。但必须清楚。因此在当前版本里，按钮的合理用法是完成表单骨架的视觉与结构，业务提交动作仍由外层应用承接——Web 页面、业务客户端或线下流程。
与版式元素配合，构成可打印的表单页
表单域本身只提供交互位置，版面秩序仍要靠通用元素组织。可用 <h1>~<h6> 建立标题层级，用 <p>、<span> 写说明与提示，用 <lineSeparator> 分隔说明区与勾选区，用带 border、padding 的 <div> 标注独立的说明块，用 <br>、<tab> 调整行内间距。当签字或备注区需要独立成页时，可用 <areaBreak> 或 <htmlPageBreak> 强制分页，避免与正文内容挤在同一页。这些元素与表单域同属模板标签，组合方式与普通文档一致。
阅读器兼容性是验收项而非可选项
表单域属于 PDF 的交互层，外观与可操作性由阅读器实现决定，因此“文本抽取正常”不能作为验收依据：文本抽取只能证明文字存在，证明不了字段是否可点击、勾选标记是否显示。验收至少覆盖两类阅读器（桌面端与浏览器内置阅读器），并分别检查字段可见性、勾选切换与打印效果。此外，含权限控制或加密的文档中表单域是否可编辑，也应单独实测。
适用场景与不适用场景
适合用表单域承载的场景有两个特征：勾选语义固定、结果由人工确认。典型是签收确认（收件人打勾表示已收到）与复核勾选（复核人逐项确认检查项）。不适合的场景同样明确：需要复杂校验或条件联动的表单（例如选了 A 才允许填 B）、需要把填写结果自动回传并触发流程的页签，以及字段数量多、取值需要数据字典约束的表单——这些需求放在业务系统内完成成本更低，PDF 只应承担最终的确认与归档形态。
表单版与静态版的分工
电子勾选能省去打印环节，但并非所有流程都适合。签收页、确认单这类“勾选结果需要被流程再消费”的场景适合提供可交互表单；而只作为对外凭证、要求长期不可篡改的文书，更适合直接输出静态文本，把勾选结果以文字形式写明。若两种用途并存，可以用同一份数据和同一套版式常量渲染两次：一份带表单域供填写与回传，一份纯静态供归档。这样做的好处是留痕链路清晰——可编辑版只是采集工具，静态版才是归档凭证。还有一个现实约束容易被忽略：表单域的勾选结果不会自动回到服务端，必须依靠回传、导入或人工录入，因此设计流程时要把这一步显式排进去，并给每份表单带上唯一标识，便于回填时与业务数据对应。
关键细节
- 元素清单：
<button>、<checkbox>、<comboBoxField>、<textArea>四类表单域，后两者见同系列另一篇； - 属性写法：
checked作为无值标记属性书写，样式统一写在style中，属性名驼峰与连字符互为别名（如fontColor与font-color）； - 不得添加未证实属性：字段名、提交 URL、动作类型都没有依据，写了可能得到“不报错但无效果”的假象，排查成本很高；
- 与文本混排：复选框与说明文本可作为独立元素依次输出，但精确的基线对齐效果需实测确认；把复选框放进表格单元格的排布方式同样未证实，稳妥做法是按纵向顺序排列勾选项；
- 尺寸与颜色：如需控制表单域尺寸，可用
width、height等尺寸属性（单位 px、pt、mm、cm、in，1px = 0.75pt）；fontColor支持颜色名、#RRGGBB、rgb()/rgba()； - 打印用途：同一份 PDF 既要电子填写又要打印时，两种用途分别验收，不能只测一种；
- 权限与留痕：审批类表单是流程的一环，服务端仍须保留最终审核记录，不能把 PDF 内的勾选当作唯一凭据；
- 文案与顺序：复选框的文案和排列顺序应与纸质表单逐项对应，减少人工核对时的歧义；
- 实例隔离：工厂实例承载本次导出的绑定值，建议一次导出新建一个实例；若要复用实例，需实测上一次的绑定值是否会带入下一次渲染。
实战说明
import com.github.paohaijiao.executor.JQuickPdfFactory; // 导入工厂
import java.nio.file.*; // 导入文件工具
public class FormDemo {
// 声明类
public static void main(String[] args) throws Exception {
// 声明入口
String template = "<pdf><body><h1>'审批回执'</h1>" // 创建模板
+ "<p>'处理结果：'</p>" // 添加说明
+ "<checkbox style=\"fontColor:blue\" checked>'同意'</checkbox>" // 添加已勾选项
+ "<checkbox>'需复核'</checkbox>" // 添加未勾选项
+ "<button style=\"fontColor:blue\">'提交'</button>" // 添加按钮
+ "</body></pdf>"; // 结束模板
byte[] pdf = new JQuickPdfFactory().executeContent(template); // 渲染 PDF
Files.write(Paths.get("approval-form.pdf"), pdf); // 保存 PDF
}
}
执行步骤与预期：
- 运行
FormDemo，得到approval-form.pdf； - 预期页面自上而下为标题“审批回执”、说明文字“处理结果：”、勾选项“同意”（默认选中、蓝色字体）、未勾选项“需复核”、按钮“提交”；
- 在桌面阅读器中打开，确认三个控件可识别、复选框可切换选中状态；再在浏览器内置阅读器中复测一次；
- 打印预览确认布局未错位，并确认打印件上勾选状态符合流程要求。
异常排查：控件不可见，检查阅读器是否处于表单编辑或高亮模式，并换一个阅读器复测；样式未生效，检查属性名与取值拼写；生成失败，检查元素是否闭合、字面量是否漏单引号。
验收清单（每项都要在两个以上阅读器中执行一次）：
- 字段可见性：复选框与按钮在页面上是否呈现为控件，而非一段普通文字；
- 交互性：未勾选项能否勾选、已勾选项能否取消，切换后外观是否即时更新；
- 状态保留：勾选后保存并重新打开，选中状态是否保留（阅读器保存行为需实测）；
- 打印结果：打印预览中勾选标记是否可见，布局是否与屏幕一致；
- 文本层：用文本抽取只能校验“同意”“需复核”“提交”等文案是否存在，不能作为表单可用性的证据；
- 文件信息：记录输出文件大小与控件数量，作为后续模板变更的对比基线。
生产注意事项：限制表单用途，仅用于签收确认、复核勾选等语义固定的简单场景；字段文案与纸质表单保持一致，减少歧义；表单文件与业务数据分别归档并记录模板版本；升级版本后重新做一次跨阅读器验收。
从场景取舍看，带表单域的版本适合“先勾选再回传”的短流程，纯静态版本适合长期归档；两种版本应由同一份业务数据和同一套版式常量渲染，模板版本号保持一致，避免同一业务出现两个版式不同的凭证。若填写结果需要入库，应在流程中安排导入与校验环节，而不是假设 PDF 会自动回传。
总结
关键结论：<button> 与 <checkbox> 是已验证可用的表单元素，checked 控制初始勾选状态，样式属性可作用于表单域；表单域的验收必须落到阅读器交互层面，而不是文本抽取层面。
边界与误区：最常见的误区是把 HTML 表单的行为预期直接搬到 PDF——按钮的提交动作、字段命名等属性在已核实事实中未证实，不能自行补全，服务端审核环节也不能省略；第二个误区是只看文本抽取结果就判定表单可用。
版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表，并重点复测表单域的交互与外观；更多示例见 GitHub 仓库。
