jquick-pdf 可编辑 PDF 表单：textArea 与 comboBoxField 开发教程
引入
服务端导出的 PDF 并不总是终稿：客户回访表、服务申请单、内部登记表往往需要接收方在阅读器里继续补填。可编辑表单的价值正在于此——同一份文件既承载系统已生成的数据，又留出人工补充的输入区，减少二次录入。用底层 iText/PDFBox 手工设置文本域与组合框，需要逐个处理字段与外观；jquick-pdf 把这两类控件做成模板元素：<textArea> 用于多行输入，<comboBoxField> 用于受限取值。
依赖为 io.github.paohaijiao:jquick-pdfx:4.0.0，JDK 8+。
核心讲解
两个元素的分工
<textArea> 提供多行文本输入区，适合备注、描述、意见等长度不可预期的内容；<comboBoxField> 提供下拉式取值控件，适合类型、渠道、优先级等取值受限的字段。两者都以标签形式写在 <pdf><body> 内，与前后用于说明的 <p> 共同构成一张表单版面。样式属性对二者同样可用，示例中分别用 width:420px;height:80px 与 width:220px 声明尺寸。
尺寸决定可填写空间
按 1px = 0.75pt 换算，420px ≈ 315pt ≈ 111mm，80px = 60pt。宽度决定单行可容纳的字符量，高度决定可见行数；因此建议按“填写两到三行备注”的预期给足高度，而不是压到临界值。换句话说，尺寸在这里表达的是业务预期，而不是精确的字数控制。
下拉选项的现状与替代做法
<comboBoxField> 目前可确认的是元素本身与尺寸样式，选项集合、默认值、字段名等属性均未证实。工程上有两种做法：
- 版面上把候选项以文本形式列出（例如用
<p>或<list>/<li>说明可选类型），下拉域只承担填写入口； - 取值校验放到提交之后的业务环节，由后端按枚举白名单校验人工填写结果。
这两种做法升级后也容易迁移，比猜测属性名更稳妥。版面上可以这样表达：
<p>'类型可选值：合同、发票、其他'</p>
<comboBoxField style="width:220px">'请选择'</comboBoxField>
表单组合与提交环节
把 <textArea>、<comboBoxField> 与 <checkbox>、<button> 放在同一个 <body> 内，就能拼出一张完整表单页：文本提示用 <p>，勾选用 <checkbox>（checked 控制初始状态），动作入口用 <button>。需要注意的是，表单动作协议（提交地址、字段名等）未实现（pdf 是静态，不是动态的），因此闭环应设计为“PDF 采集 + 业务系统导入校验”，而不是依赖 PDF 内部的提交能力。
可编辑 PDF 在服务端导出流程中的价值与限制
价值体现在三点：一次导出即可完成“系统数据 + 人工补充”；填写方无需登录业务系统即可录入；PDF 便于本地留存与归档。限制同样明确：填写结果的取回依赖阅读器与后续流程，当前 API 未提供把表单数据回传服务端的通道，因此 PDF 表单更适合作为采集载体，最终数据仍需人工或流程导入后再落库。这个定位直接决定设计取舍：字段不宜过多，校验要简单，关键信息应带唯一标识（如单号），便于回填时与业务数据对应。
可编辑字段与数据绑定的区别
${name} 是渲染期的文本替换，绑定值在生成 PDF 的那一刻就已经固定；而 <textArea>、<comboBoxField> 是交互域，值由填写者在阅读器里输入，两者不在同一层。混淆二者会带来典型问题：把本该由用户填写的字段写成 ${变量}，生成时值为空，看起来像“控件坏了”；反过来，把系统产出的数据写成可编辑域，数据在客户端就可能被随意修改。判断原则很清晰——由系统产出、不允许改动的内容用绑定文本，由填写人补充的内容才用表单域。由于当前 API 未证实提供读取回填值的通道，关键业务数据不应放进可编辑域。
适用与不适用场景
客户回访、服务申请、内部登记这类“先发文件、后补信息”的场景适合可编辑表单：一次导出即完成系统数据与人工补充的结合，填写方无需登录业务系统即可录入。不适合的场景有三类：一是取值严格受限、必须与后端枚举一致的字段，因为选项集合属性难以在控件层约束；二是需要即时校验或联动显示的表单，这类能力依赖阅读器脚本，而 API 中未提供对应配置；三是要求强留痕、不可篡改的文书，可编辑域本身带来修改风险。判断标准可以归结为两个问题：内容是否允许填写者自由输入，结果是否需要回流。若答案偏向“受限”“联动”“强留痕”，应改用 Web 表单或直接输出静态文本。
关键细节
- 字面量：示例中的
'请填写备注'、'请选择'均为单引号包裹的文本字面量；变量可用${name}注入，已注册资源用&{name}； - 属性别名：驼峰与连字符写法等价，尺寸写成
width:420px、height:80px即可； - 属性：
option、value、fieldName等不得自行添加，写了可能出现无效果却不报错的情况； - 中文文本：项目内置 CJK 字体（
jquick-pdf-font），中文无需额外配置即可渲染；若显式指定字体，应先确认资源已注册； - 混排：
<textArea>、<comboBoxField>可与<checkbox>、<button>组合成完整表单页，但动作协议需由后端实现； - 验收维度：可访问性（键盘与标签能否定位）、打印效果、移动端阅读器表现，三者分开测试。
实战说明
import com.github.paohaijiao.executor.JQuickPdfFactory; // 导入工厂
import java.nio.file.*; // 导入文件工具
public class EditableFormDemo {
// 声明类
public static void main(String[] args) throws Exception {
// 声明入口
String template = "<pdf><body><h1>'客户信息'</h1>" // 创建文档
+ "<p>'备注'</p><textArea style=\"width:420px;height:80px\">'请填写备注'</textArea>" // 添加输入区域
+ "<p>'类型'</p><comboBoxField style=\"width:220px\">'请选择'</comboBoxField>" // 添加下拉字段
+ "</body></pdf>"; // 结束模板
byte[] pdf = new JQuickPdfFactory().executeContent(template); // 执行渲染
Files.write(Paths.get("editable-form.pdf"), pdf); // 写出文件
}
}
执行步骤与预期：
- 运行
EditableFormDemo，得到editable-form.pdf； - 预期页面包含标题“客户信息”、“备注”说明文字、一个 420px × 80px 的多行输入区（内含提示文本“请填写备注”）、“类型”说明文字与一个 220px 宽的下拉控件；
- 在目标阅读器中试填：多行区域可输入含换行的文本，下拉控件可展开选择；
- 保存并重新打开文件，确认填写内容保留（阅读器的保存行为需实测）。
验收清单：
- 控件识别：两个域在阅读器中是否呈现为可填写控件，而非一行普通文本；
- 输入能力：多行区域能否换行输入，下拉控件能否展开并选择候选项；
- 打印效果：打印预览中控件位置与说明文字是否对齐，输入区是否被裁切；
- 移动端表现：在移动端阅读器中确认控件可点击、字号不溢出；
- 可访问性：键盘 Tab 能否落到控件上，标签是否可被识别；
- 归档一致性：记录输出文件大小与模板版本，便于对比后续变更。
异常排查：控件显示为普通文本，先换一个阅读器复测，再检查阅读器是否处于表单编辑模式；尺寸未生效，检查样式属性名与单位是否写全；中文提示文本异常，确认字体资源可用；渲染报错，检查标签闭合与字面量单引号。
生产注意事项：导出接口需鉴权并按需限制导出量；表单字段与业务字段建立映射清单，避免同名歧义；归档时记录模板版本，便于日后定位填写内容对应的版式；若填写结果需要回流入库，应在流程中安排导入与校验环节，而不是假设 PDF 会自动回传。
总结
关键结论：<textArea> 与 <comboBoxField> 是已确认的表单元素，分别承担多行输入与受限取值；尺寸样式决定可填写面积，中文可依赖内置字体渲染；可编辑 PDF 的合理定位是采集载体，而不是数据回传通道。
边界与误区：选项集合、字段名、默认值等属性未证实，需要受限取值时应先用“版面文本 + 后端校验”替代，而不是猜测属性名；另一个常见误区是只验证“能生成 PDF”就上线，忽略阅读器兼容性、打印与移动端表现。
版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表，重点复测表单元素的属性支持范围；更多示例见 GitHub 仓库。
