PDF模板必须是XFA或AcroForm格式才能用XML填充，普通PDF不支持；AcroForm为当前主流，XFA已逐步淘汰；字段名须与XML节点名严格一致（含大小写及嵌套扁平化），且需校验XML结构。
PDF模板必须是XFA或AcroForm格式才能用XML填充
普通PDF无法直接用XML数据填充，只有两种PDF支持XML数据绑定：Adobe的XFA表单（已逐步淘汰但仍有遗留系统在用）和标准AcroForm表单（带命名字段）。如果你手里的PDF是“导出为PDF”的Word生成物、截图转PDF或纯版式PDF，xml根本不会被识别——工具会静默失败或报Field not found类错误。
验证方法：用Adobe Acrobat打开PDF → 右键任意表单域 → “属性” → 查看“常规”页签中的“字段名称”是否非空；或用pdfinfo -f 1 your.pdf（Linux/macOS）检查是否含Form: AcroForm字样。
Java推荐iText7 + xmlworker（仅限AcroForm）
iText7本身不解析XML，需配合xmlworker或手动映射字段。更稳妥的做法是用PdfAcroForm加载XML后逐字段赋值。注意：iText7.2+已移除对XFA的支持，只处理AcroForm。
- 确保PDF字段名与XML节点名严格一致（区分大小写），例如XML中
INV-2024-001 invoice_no - 嵌套XML（如
Alice customer.name或customer_name（取决于你解析逻辑） - 日期/数字字段需提前格式化为PDF字段接受的字符串，比如
date字段填"2024-05-20"而非"2024-05-20T00:00:00Z"
PdfDocument pdfDoc = new PdfDocument(new PdfReader("template.pdf"), new PdfWriter("filled.pdf"));
PdfAcroForm form = PdfAcroForm.getAcroForm(pdfDoc, true);
Document xmlDoc = Jsoup.parse(new File("data.xml"), "UTF-8");
Elements fields = xmlDoc.select("*");
for (Element e : fields) {
String name = e.tagName();
String value = e.text();
if (form.getField(name) != null) {
form.getField(name).setValue(value);
}
}
pdfDoc.close();
Python用pypdf + lxml（轻量、无依赖、仅AcroForm）
pypdf（v3.0+）可读写AcroForm字段，不依赖Java环境，比reportlab或weasyprint更适合已有PDF模板的场景。XML解析用lxml.etree最稳，避免xml.etree.ElementTree对命名空间或编码的隐式处理出错。
立即学习“Java免费学习笔记（深入）”；
- 字段名含空格或点号（如
ship.to.city）需用form.get_fields()确认实际键名，PDF可能自动转为ship_to_city - 多值字段（如复选框）要设
"/Yes"或"/Off"，不能只传字符串"Yes" - 中文XML务必声明编码：
，否则lxml可能误判为ASCII导致乱码
from pypdf import PdfReader, PdfWriter
from lxml import etree
reader = PdfReader("template.pdf")
writer = PdfWriter()
writer.append(reader)
tree = etree.parse("data.xml")
root = tree.getroot()
for field in reader.get_fields().values():
key = field.field_name
elem = root.find(key)
if elem is not None and field.field_type == "/Tx":
field.value = elem.text or ""
with open("filled.pdf", "wb") as f:
writer.write(f)
别跳过XML Schema校验这一步
生产环境里，XML结构错一个层级、少一个必填字段，PDF填充就可能漏填或崩溃。用xsd文件做预校验比事后查PDF更高效。Python可用lxml.is_valid()，Java可用SchemaFactory。
常见陷阱：XML默认命名空间（xmlns="http://example.com/ns"）会让find("field")返回None，必须注册命名空间前缀或用.xpath("//ns:field", namespaces={"ns": "..."} )。
如果模板字段名来自数据库或配置中心，XML结构又常变，建议把字段映射关系抽成JSON配置，而不是硬编码字段名到Java/Python里——改一次PDF字段就得改两处代码，非常容易脱节。
