ADR-0010：行内图像、共享行布局与 DOCX 媒体

• 状态：已采纳
• 日期：2026-10-14

背景

图像此前只能作为独立绘制或块组件，无法在段落中与文字一起换行。DOCX 适配器也没有嵌入媒体与 DrawingML 映射，转换会拒绝图片或要求显式损失。

决策

模型新增不可变 ImageResource、InlineImage 与 InlineContent，不暴露 AWT、PDFBox 或后端对象。资源复制并有界验证显式 PNG／JPEG 字节；不访问网络或系统文件。新增图片标记列表与有序混排工厂，保留旧文本构造器，来源仍为原文 UTF-16。

默认文本路径用 JDK GraphicAttribute 将图片作为不可拆的行内对象参与文字测量和双向定位。图片几何进入 TextLine.images()；分页重定位保留它。行框保持现有固定行距语义，容纳不了图片时失败。绘制层把预定矩形转成普通图片命令，PDF、SVG、PNG 不再排版。调用级解码缓存按内容哈希复用，结束后释放，不建立全局资源缓存。

DOCX 直接映射模型，输出标准嵌入关系、内容类型、媒体部件和 wp:inline/pic:pic，图片链接使用 a:hlinkClick。导入按运行内文字／绘制顺序还原来源位置，单元格合并段落时偏移图片位置。严格拒绝未知图片变换、路径越界和外部资源；损失模式省略不支持绘制并给出诊断。媒体、绘制 XML 和整个包均受预算约束，写流前完成导出检查。

替代方案

块组件不能表达同一行的文字包围图片；在 PDF 后端追加图片又会失去共享换行与 DOCX 语义。让图像携带可变像素或 AWT 对象会泄漏实现与所有权，因此模型保存编码快照，绘制时转为既有 RGB／alpha 值对象。可变行高会改变现有分页契约，本批继续固定行距。

影响与验证

模型内部使用 JDK java.desktop 的 ImageIO，无第三方运行依赖；公共签名仅使用 JDK 基础类型和项目类型。文本模块公开几何引用模型，因此将其模型依赖声明为 api。记录分量增加需要调用方重新编译，保留旧构造器只保证既有源代码调用方式。

测试覆盖资源不可变、来源、双向混排、缺字策略、行框边界、分页与重复表头、模板和脚注保留、标准 DOCX 往返、媒体去重、恶意关系、损失诊断与借用流。独立工具验证全部 PDF 页面、图片 CTM／链接矩形、OOXML 媒体与替代文字、静态图片输出及 DOCX 往返的像素结果，详见验收记录。

替代文字不等于 PDF/UA 标签支持。完整 Word 兼容、动态行内域、结构化阅读顺序、连续分栏、多浮动区及合并格拆页继续独立实现。