Export4j

简体中文

English

简体中文

English

外观

研发路线与验收 ​

本文以立项文档为范围基线。当前提供 PDF／DOCX／HTML／Markdown 文档生成、SVG／PNG 静态输出，以及明确子集内的导入、编辑和转换；复杂排版、原生 OpenType、单向长表、PDF 编辑与标准处理分别有专项证据。已实现范围及限制以支持矩阵和缺口表为准，以下历史阶段不代表当前仍待完成状态。可选 HTML 设计器及四套业务样例已完成。跨平台／阅读器矩阵、正式分发及更多格式继续按原有独立缺口验收。

阶段总览 ​

阶段目标核心交付物
一验证项目基础与 PDF 最小闭环可构建核心库、PDF 示例和基础自动化测试
二建立可靠的字体与文本排版字体契约、测量、换行和混排测试集
三实现自动布局与分页多页报告、跨页表格和布局诊断
四建立多格式适配体系DOCX 基础导入导出、SVG 输出和兼容性矩阵
五完善性能、稳定性与正式发布性能基线、稳定 API、SBOM 和发布制品

阶段按能力推进，不预设日期、人力或未经测量的性能指标。

阶段一：项目基础与 PDF 最小闭环 ​

范围：建立 Gradle 多模块项目、最小文档模型、Graphics API、Display List 和 PDFBox 后端。先实现显式定位的文字、路径、图片与页面设置。

验收要求：

  1. 提交完整 Gradle Wrapper，Java 21 环境能够构建并运行基础自动化测试。
  2. 公共 API 不暴露 PDFBox 类型，核心模块不反向依赖 PDF 后端。
  3. 通过 Document Model 或 Graphics API 生成包含文字、图片、图形和基本页面设置的 PDF。
  4. 示例可按文档命令执行，资源来源和输出位置明确。
  5. 输出可由独立 PDF 工具解析、渲染，并保存验证记录。
  6. 自研源文件有 Apache-2.0 声明；直接、传递依赖与示例资源都有许可证审查记录。
  7. 基础测试覆盖页面尺寸、坐标、资源输出和失败路径的释放行为。
  8. README、架构文档与真实构建、能力范围一致。

完成最小闭环不代表支持自动换行、中文字体回退、复杂塑形或自动分页。

阶段一交付包含 5 个实际模块，当时语义模型提供页面尺寸与元数据。段落语义与分页在阶段三首批实现，当前绘制能力与限制见绘制 API。

构建、测试和独立 PDF 工具证据见阶段一验收记录。

阶段二：字体与文本排版 ​

范围：字体加载、字形映射、度量、普通换行、对齐、缩进、行距、中文及中英文混排。

验收要求：

  1. 测量与绘制使用一致的字体及字形数据。
  2. 样本覆盖中文、混排、Unicode 边界和缺字；明确尚不支持的复杂脚本。
  3. 字体嵌入、文本提取与 Unicode 映射经过实际输出验证。
  4. 字体回退顺序固定，缺字和回退行为可诊断。
  5. 固定字体与配置时，行布局结果可复现。

本阶段已实现静态 TrueType 加载、Unicode 字形映射、显式回退、嵌入与子集化，以及普通水平文字的测量、换行和行布局。原有 5 个模块之外新增字体与文本模块，未提前创建分页模块。

字体、混排、Unicode 边界、几何、预算和 PDF 一致性的证据见阶段二验收记录。复杂塑形、完整中文禁则、富文本行内样式与自动分页不包含在本阶段结果中。

阶段三：自动布局与分页 ​

首批已完成段落语义节点、页面内容区域、段前段后间距、保持整块与按完整行跨页。新增布局模型和布局核心，DocumentLayout 保存页面与来源映射，ParagraphLayout 保持段落内部结果的职责。

证据见段落分页验收、表格验收和组件验收。基础表格支持固定／比例列宽、单元格换行、自动行高、不可分割行和重复表头。标准组件支持页眉页脚、最终页码、图像、形状、线条和水印；目录、书签、评论与基础可填写表单已进入 PDF 首版。定位支持绝对、锚点和比例模式；普通正文组件整块流动，PageableComponent 按有序片段续页。

进阶批次已实现最低片段行数、保持相邻、分节模板、富文本、合并图文表格、嵌套续页、编号／引用、注释、透明图像和中文表单，见进阶验收。生产批次进一步提供多栏、矩形绕排、文本表格拆行、脚注续页与换行引用；后续复杂脚本已进入公共段落路径，并扩展富文本单元格、外链、自动列宽与末页平衡，详见能力指南。

多浮动组件支持首片段多个矩形的逐行避让、封闭行带跳过和整体移页，见调用指南。任意轮廓与跨页浮动锚点进一步按实际曲线行带布局，保留原文位置及真实子流续排，见阶段九十九。

当前页连续文字分栏已支持剩余高度、完整续栏、两栏／三栏、最低行数移页和后续正文接续，见调用指南及独立验收。混合组件、嵌套流与表格后续已接入区域 SPI，支持图片整块移动、逐栏表头和完整合并行组，见混合分栏指南及验收。文字／混合流变栏宽与平衡见阶段五十九，变宽最低多行策略见阶段六十三；原子语义表格及完整行续排已接入变宽区域；纵向 owner、递归子树与组件网格的变宽续排已由阶段九十九完成。

正文行内动态字段、页码／编号引用和注释锚点已实现。字段固定宽度，最终分页后解析；脚注跟随标记实际所在行，见字段指南及验收。语义表格单元格进一步支持页码和引用字段、逐页重复表头及拆行来源，见表格字段验收。DOCX 原生四类字段及显式宽度导入已补齐，见DOCX 字段验收。单元格注释标记、任意组件字段、长表区域流、自动字段宽度重排和结构化可访问性仍属后续范围。

范围：约束与尺寸计算、段落流式布局、表格列宽与行高、跨页处理、页眉页脚、页码和重复表头。

验收要求：

  1. 生成多页报告，内容顺序正确，无非预期丢失或重复。
  2. 表格跨页与重复表头正确，声明单元格和不可分割行的支持范围。
  3. 空页面、超长段落、超大图片和超高行具有明确行为。
  4. 分页保证推进；不可容纳内容不会导致无限循环。
  5. 布局诊断能够定位相关节点和页面。
  6. 建立固定环境下的视觉回归与几何断言，能解释基线差异。

阶段四：多格式支持 ​

首批 DOCX 语义子集、SVG 和 PNG ZIP 已实现并独立验证。DOCX 后续补充富文本／行内图片单元格、标准媒体资源与外部超链接，见行内图像验收；阶段二十五／二十六进一步接入原生 gridSpan／vMerge。默认页区的图片／表格／页码与分节映射已在阶段四十二验收；复杂图片变换、更广页区变体、递归格内容及交互映射仍有限。早期原生字段样例通过 Word 16.0 更新及 PDF 导出实测，新合并样例的保存／导出不能沿用该结论；重复表头 PAGE 明确拒绝，一般 Word／LibreOffice 的视觉兼容仍未覆盖。DOCX 的未知结构、继承与编号覆盖须报损或拒绝；静态输出拒绝交互 extras。静态 PDF 选页／合并／提取子集已在阶段二十二验收，通用分析／导入／编辑仍属后续范围。

范围：DOCX 基础导入导出、SVG 输出，以及按实际需求选定的 PDF 导入、分析或编辑能力。

验收要求：

  1. DOCX 通过文档模型导入导出，不以 PDF 坐标指令代替语义结构。
  2. 对段落、表格、样式和资源建立支持矩阵与往返样本。
  3. SVG 在独立工具中解析和显示，覆盖文字、图形与资源处理。
  4. 不支持、降级和无法无损转换的特性均有明确诊断。
  5. PDF 扩展声明具体能力，不宣称任意 PDF 可无损恢复语义模型。

阶段五：性能、稳定性与正式发布 ​

首批稳定性验证通过 4 线程 24 次 PDF 导出和 2,500 段落实际导出；已完成真实 Edge 表单保存重开、隔离 Maven 调用方、BOM 与 SBOM。它们不等同于长期压力容量、RSS 测量或发布完成。下一阶段依据实际文档补充缺陷回归、容量测量、公共 API 冻结与应用兼容；远程 CI 与正式发布仍需独立验证。

后续补充两端对齐、可选严格中文禁则、富文本标题／列表和常用编写入口。新增 2 线程、6 份各 26 页混合报告，采样独立 JVM 的 Windows 工作集、私有字节和句柄，并验证取消／输出超限恢复。该证据仍属于有界工作负载，不代表长期泄漏或容量保证，见阶段十三。

取消／超时／进度／原子文件写入已有实现；AES-256、选定 PDF/A-1b／2b／3b／4f、显式 PDF/UA-1 和离线 PAdES B／T／LT／LTA 使用各自独立入口及验收，见标准指南。语义长表、重放及磁盘索引 PDF和本轮有限持续压力已完成；跨系统／阅读器矩阵继续归 GAP-14.2。具体范围见能力矩阵。

固定列普通文字已接入独立单向源和逐页 PDF，见阶段二十四。布局丢弃页／真实 PDF 各 1k／10k／100k 行及 64 MiB 堆布局控制共 7 组独立 JVM 通过；100k PDF 为 1,786 页、325.281 秒。结果同时记录观察堆、Windows 工作集／私有字节／句柄、吞吐、临时盘及退出文件清理。PDFBox 页树仍累计；这不完成一般文档恒内存或持续容量目标。

范围：性能基线、大文档内存、资源缓存、并发隔离、API 稳定和开源治理。已记录单任务 5,000 段落基线及堆内存池峰值之和；尚不等于并发容量、RSS 或发布性能保证。

验收要求：

  1. 性能记录包含样本、硬件、JDK、预热、并发与测量方法。
  2. 大文档与并发样本验证峰值内存、资源释放和任务隔离。
  3. 异常输入、预算超限和资源不足时行为可预测。
  4. 公共 API、版本兼容策略、迁移说明和用户文档完整。
  5. 许可证清单、必要的 NOTICE、SBOM 和发布检查通过。
  6. 私密安全报告渠道可用，自动化构建、测试和发布流程已实际运行。
  7. 发布制品可以在干净的调用方项目中解析依赖并运行示例。

验收记录 ​

能力补齐的逐项推进见能力缺口表。第一批补充普通嵌套文字自然续页与显式合并格完整行拆分；语义表格统一、富文本字段合并、样式贯通及静态表单仍按独立验收推进，不能由同名链式入口推断完成。

第二批已补充静态表单公共组件并移除 ADR 私有勾选绘制器，见阶段十六。评估同时修正定位表格的外链损失边界。下一项先让组件 IR 保留语义、来源和变换，再贯通字段／外链并接入语义表格区域流；默认样式贯通仍独立验收。

第三批实现组件语义插槽和固定视口 SemanticTable，保留最终字段、图文外链、字体角色及单元格来源，见语义组合 API和阶段十七。长语义表格区域流、重复呈现及默认样式仍独立推进。

第四批接入语义表格区域续排，保持短首区、完整行、逐栏表头字段、拆行图片与最终链接，并区分唯一来源和实际片段，见阶段十八。固定组件仍要求单片段，DOCX 嵌套与长合并网格字段继续开放；下一优先项是默认样式贯通。

第五批完成未设置文字样式／颜色的嵌套继承，贯通正文组件、网格和静态表单；保留显式覆盖、加入时快照、固定行框及原子组件宽度。329 项测试、4 页独立样式验收通过，见阶段十九。逐属性级联保留开放；下一优先项为长合并网格语义字段，其后为安全声明式模板。

第六批完成标准长合并格内的语义表格续排及合法网格表头重复；复用一次测量游标，保留最终字段、富文本、图文外链及内 Table 来源，见阶段二十。345 项测试、8 页独立输出检查、15 组历史回归通过。任意递归网格拆分、DOCX 嵌套和统一合并 Table 模型仍开放；下一项为安全声明式模板子集。

以下阶段记录保留当时的实现与限制；当前支持状态以缺口表及最新 API 为准，不将已被后续阶段补齐的内容继续计为缺失。

每次阶段验收记录对应提交或版本、构建命令、验证工具及版本、输入资源、结果与限制。记录存入对应变更说明或独立验收文档，不能只用任务勾选代替证据。

第七批补充离线声明式 XML，将文本报告结构编译到既有语义模板；支持变量、条件、循环、动态长表和显式图片，严格拒绝未知内容及外部资源。绑定同时修正大数子类、追加前预算及循环工作计费。378 项测试、4 页独立渲染、DOCX／SVG、新模块本地坐标及三组历史回归通过，见阶段二十一。Markdown、HTML/CSS 和设计器仍开放；下一项按 GAP-08 扩充复杂文字与阅读器语料。

第八批补充六脚本两条路径的文字一致性及实际搜索／选区语料、严格 Markdown、XML 四类字段／一级编号／静态图文外链和独立静态 PDF 处理适配器。472 项测试、35 页新增输出逐页检查、18 组历史回归、最终 PDF/A、本地 SBOM／坐标及新隔离调用方通过，见阶段二十二。轮廓提取与选区、通用 PDF 编辑、HTML/CSS 和 DOCX 合并／嵌套仍有明确缺口。下一项是显式逐属性级联；所有剩余单元及依赖见执行计划。

第九批完成六项组件文字属性的具名覆盖／逐项恢复，保留父级其他属性、旧完整样式语义、网格／作用域快照及固定行框。490 项测试、6 页新输出、22 组历史回归、新隔离调用方通过，见阶段二十三。下一项是固定列单向长表源；PDFBox 页树内存与全量 IR／Display List 必须分开测量，主题及可编辑字段样式仍独立。

第十批完成固定列普通文字的一次性行源、逐行测量／逐页绘制、同步 PDF 和扁平摘要。552 项测试、8 页新输出、23 组历史回归、当前隔离调用方与 7 组独立 JVM 通过，见阶段二十四。采样脚本 PS5.1 空退出码修复后从新 ID 重跑，全部退出临时文件数／字节为 0；64 MiB 堆完成 100k 行布局。GAP-09 按子集改为部分支持，下一项先贯通语义 columnSpan 与标准 DOCX gridSpan，rowSpan／递归格内容及持续容量继续独立推进。

第十一批贯通语义列合并、物理列来源、最终字段／图文链接、Java／XML 绑定与标准 DOCX gridSpan，见阶段二十五。592 项测试、8 页新输出、24 组历史验收、新隔离调用方通过。Word 实际读取／字段更新成功，保存及导出阻塞，保存回读仍开放。下一项为语义 rowSpan／vMerge，首批以二维覆盖、确定行高及连通组整体移页闭环，跨页拆分纵向合并组与递归格内容单列。

第十二批完成语义跨行合并、二维真实锚点、全覆盖行、确定行高／连通组及标准 DOCX vMerge，见阶段二十六。641 项测试、7 页新输出、25 组历史验收、新隔离调用方及独立 PDF/A 验证通过。Word 只读加载和原生页码更新有证据，原探针的错误行数假设／COM 收尾失败如实保留，未保存或导出。下一单元为块格与原子内表设计：先扩展全树来源、预算、模板与最终字段／链接，再接标准 DOCX 双向映射；完整递归续排、纵向拆组及一般 Word 保存兼容仍独立。

第十三批完成有界多段格与两层原子内表，见阶段二十七。694 项测试、6 页新输出、26 组历史验收、新调用方与独立 PDF/A 通过；链式结构、全树 ID／预算、层级来源、字段／图文链接及标准双网格／尾段已贯通。下一切面为 XML 可读格结构；更深递归续排、纵向拆组和 Word 保存仍开放。

第十四批完成可读 XML p／table／p、独立格式和 Each／Rows 副本内引用，见阶段二十八。711 项测试、7 页新输出、27 组历史回归、新调用方及独立 PDF/A 通过。旧 DOCX 被占用时改用独立验证目录，保留原文件和进程。下一项按单向富文本长表设计推进单向长表的有界纯富文本与显式字体角色，不引入未来引用或隐式资源。

第十五批完成单向长表的有界纯富文本、显式字体角色、逐格／逐行空运行预算及全行预检，见阶段二十九。732 项测试、6 页新输出、28 组历史回归、新调用方及 9 组独立 JVM 通过。容量例从手算改为实际累计并重采全部富文本组；PDFBox 累计对象、未来语义和持续容量仍开放。下一项为 GAP-04 编写时语义主题／命名完整样式，沿用六项组件继承与显式值优先。

第十六批完成 Java 编写时主题快照、正文／六级标题／便利语义表格默认值、命名完整样式和组件富文本便利入口，见阶段三十。753 项测试、9 页独立 PDF／SVG／DOCX 输出与新调用方通过；默认输出、显式12 pt／黑色／零值、局部继承和固定行框保持。下一独立单元为 XML 静态样式名称与主题初始化，保留 XML 旧配置范围；全局字体角色级联、可编辑字段、完整品牌主题和持续容量继续独立。

阶段四十三新增语义 HTML／Markdown 导出，支持静态自包含 HTML5、CommonMark/GFM 内容与逐功能 ERROR／WARN／IGNORE。默认严格，合并／块格在 Markdown 中仅按明确策略展开，字段使用未解析标记；见API与验收。

阶段四十四至五十六依次完成语义编辑／字面替换、通用 Markdown／离线 HTML/CSS输入、统一转换、DOCX 原包文字与样式级联，以及 PDF 页／被动对象编辑、组合、渲染提取、优化、文字替换、光栅脱敏及语义恢复的明确子集。全部按实际输出、损失预检／结果和隔离制品验收。PDF 恢复按行／字号推断并需显式表格网格；脱敏新建图片 PDF，损失搜索和矢量编辑。完整标准、任意文档无损往返、设计器和长期容量仍不属于这些已交付目标；详见执行计划。

阶段九十四至九十七进一步完成跨状态文字／图片实例编辑、选择性脱敏、扩展表单／批注／FDF／XFDF／XFA，以及自动多栏／段落／有线无线表格／合并嵌套恢复的明确子集。1,634 项测试、全新 Maven 调用方和对应独立输出验收通过。选定 PDF/A、离线 PAdES 和 PDF/UA-1 的既有子项目标均已验收；生成样例及已有标签文件两页、修复后模型第一页的实际辅助阅读器证据分别登记，模型其余页未捕获读屏的覆盖限制明确保留。当前状态以缺口表为准。

阶段九十八验收 GAP-03／08／09／21 的四个固定单元：变宽行内格纵向 owner 续排、逐字形竖排、有界单向纵向合并及填充／描边透明度与 SVG 变换。GAP-04／07 的既定样式／模板目标按已存在的阶段证据关闭；完整 CSS 和设计器分别只在 GAP-18.1／13 跟踪。当时尚未完成的递归块格变宽续排、可变／彩色字体、PDF 累计对象控制、CMYK／专色与渐变已由阶段九十九补齐。

GAP-03／08／09／21：原剩余清单已完成 ​

本轮按原剩余清单统一推进，未增加编号或删减关闭条件：变宽递归格／组件网格与轮廓锚点；可变／CFF2／彩色字体、方向塑形与静态 CFF 原生 PDF；单次语义长表、显式重放与磁盘索引 PDF；CMYK／ICC／专色、混合／透明组、渐变／图案和 SVG 本地资源。当前接口见变宽续排、轮廓浮动、原生文字、语义重放及高级图形。最终构建、独立输出及容量结果统一登记在阶段九十九。

历史阶段中的“下一项”及“仍开放”描述保留当时范围，当前状态以缺口表和最新验收为准；不把已经完成的既定内容重复加入后续队列。HTML/CSS 的文档布局扩展已由阶段一百零四验收，完整浏览器功能不属于该明确子集。

GAP-12／14／18：原生语义、CSS 布局与分发检查 ​

阶段一百零三完成 DOCX 有类型浮动图／真实文本框、图片变换、评论／六类修订／控件／旧式表单／目录，GAP-12.1／12.2 明确子集均已验收。真实 Word 字段更新、编辑、保存重开与发布 JAR 回读通过，4 页原生页面、4 页 Word PDF 和 4 页语义投影 PDF 完成独立渲染及逐页复查；五包标准校验零错误。验收脚本改为强类型 Office 互操作后解决导出超时，生成／转换链路在无桌面且禁止加载打印类的 JVM 下通过，不依赖打印驱动、打印服务或 Word。既有目录缓存由调用方显式刷新，不以强制全局重算破坏表单当前值。

阶段一百零四验收 GAP-18.1 的静态选择器、媒体／分页、Flex／Grid、尺寸及定位：14 页 PDF、8 份 SVG、Chromium 源几何、四项负控制和真实损失通过。阶段一百零五完成 API 固定基线和兼容门禁、本地完整签名分发及实际坐标 JAR 摘要对账。提交 cc132e7 的 Java 21 三平台构建和临时密钥签名分发远端 CI 均已通过；正式版本／身份／命名空间、Central 上传及远端消费继续保留未验。本地统一构建 1,783 项测试通过，跨平台应用／阅读器行为与正式发布分别验收。

阶段一百零六固定 0.1.0-rc.1 候选 API，新增依赖公告门禁与四格式 16 条路径／32 份输出的互转语料；DOCX 包完整性和完整输入预算缺陷已修复，jsoup 升至 1.23.2。1,787 项 Java 测试、73 次控制检查、互转 8 页及 CSS 14 页独立渲染、本地临时签名与实际坐标消费通过。本批新增 CI 尚无远端证据，正式发布未执行；已知公告查询无命中不等于无漏洞。

阶段一百零七完成 Windows Word 四页复查、控件实际编辑保存重开，以及 PDF 搜索、视觉选择、表单填写保存重开和最终 JAR 回读；修复 DOCX 现代布局模式声明及 PDF 应用元数据兼容。1,792 项测试、固定语料与无打印依赖验证通过；本轮字节未重新签名，浏览器前台交互、其他平台、新远端 CI 和正式发布分别保留未验。

阶段一百零八完成 GAP-13：独立 HTML 应用直接编辑既有 XML／ZIP，保留变量／条件／循环与显式资源，提供真实分页预览、8 步撤销、保存重开和六格式损失预检。四套业务样例共 24 份输出、11 页独立渲染及 11 项失败控制通过；构建 1,804 项 Java 测试、库 API 对比和隔离调用方通过。该阶段未完成独立项为 GAP-14.2、GAP-14.3、GAP-22，未执行正式发布。

2026-11-05，候选版 0.1.0-rc.1 已使用正式身份签名并发布到 Maven Central，17 个模块的 82 个制品远端字节、签名和校验一致，16 个库与 BOM 的 Central 隔离消费及文档输出验证通过，见发布记录与流程。GAP-14.3 继续保留稳定 API 与稳定版验收；新增手动 Maven／GitHub Release 工作流尚无 GitHub 实际运行证据，不以本地演练替代远端 CI。