跳到正文

ADR-0083:可编辑 XML 源码与普通资源 ZIP ​

状态:已采纳。

背景 ​

现有 XML 模板已经表达变量、条件、循环、动态表格、片段、分节和页区,并编译到 DocumentTemplate。编辑和复用模板需要保存源码及显式资源,不能以渲染后的文档替代仍含占位符的模板。

决策 ​

在 export4j-adapter-template 增加 XmlTemplateBundle,保存主 XML、命名片段、PNG/JPEG、显式字体字节及可选许可文本。使用普通 ZIP 和固定路径约定,XML 仍采用既有版本 1 语法。单文件 XML 继续直接使用 XmlTemplate,不要求打包。

编辑器读取原始源码,使用独立 Builder 替换指定条目。未修改内容保持原字节;不承诺 ZIP 容器元数据或压缩字节不变。重新打开后仍由 XmlTemplate 编译,DocumentTemplate 绑定,不新增解释器、模型序列化协议或自定义文件扩展名。

包读取与草稿保存仅检查容器、资源和预算;编译与绑定分别沿用已有诊断。字体保持不透明字节,角色、集合成员、引擎配置和绑定数据由运行时明确提供。许可文本随资源保存。

读取不落盘或外联,校验经典 ZIP 的中央目录、局部流、CRC、名称和累计预算;输出流借用,路径输出同目录临时写入并原子替换。错误、超限和取消不可通过损失策略忽略。

结果 ​

模板可编辑、保存、重开并绑定不同数据,无新增模块或第三方依赖。标准压缩工具可直接查看源码及资源。任意语义文档到 XML、原生格式恢复信息和跨格式无损往返不由模板资源打包完成,继续独立跟踪与验收。

API 和路径约定见指南,行为、独立 ZIP 输入、Maven 调用方及实际 PDF/DOCX 见验收。