POI 5.2.4 合并多PPTX时目标幻灯片宽高被源文件覆盖不一致

Question

在使用 Apache POI 5.2.4 合并多个 PPTX 文件时，常见问题为：**目标演示文稿（target SlideShow）的幻灯片页面尺寸（如 16:9 或 4:3）被源 PPTX 中的 SlideMaster 或 SlideLayout 的默认尺寸覆盖，导致合并后幻灯片宽高不一致（如部分页变为 A4 尺寸或自定义比例），破坏整体排版与视觉统一性。** 该问题源于 `XMLSlideShow#appendSlide()` 或手动克隆 `XSLFSlide` 时，POI 默认继承源幻灯片所属 `XSLFSlideLayout` 和 `XSLFSlideMaster` 的 `cx/cy` 属性（即 `p:sldSz` 元素），而未主动重置或对齐至目标文档的 `presentation.xml` 中定义的全局幻灯片尺寸。即使调用 `slide.setSlideNumber()` 或 `slide.importContent()`，也无法自动修正底层 `p:sldSz` 配置。开发者常误以为合并仅复制内容，实则样式与页面元数据亦被深度携带，需显式干预 `CTPresentation` 的 `sldSz` 节点或重建布局关联，否则导出后易出现缩放异常、内容裁切或打印错位等问题。

Answer 1

```html

一、现象层：合并后幻灯片尺寸“悄然失守”

使用 XMLSlideShow.appendSlide() 合并多个 PPTX 时，目标文档中原本统一的 16:9（如 12192000×6858000 EMU）页面比例被部分插入幻灯片“带偏”——导出预览可见某些页自动缩放为 A4（8418000×5953000 EMU）或 4:3（10000000×7500000 EMU），导致内容错位、图表裁切、动画锚点漂移。该问题在 PowerPoint 客户端中不可见（因 UI 强制重绘适配），但通过 File → Info → Properties → Advanced Properties → Slides 可验证单页实际 p:sldSz 值已异化。

二、机制层：POI 的布局继承链与 sldSz 传播路径

• XSLFSlide 构造时绑定其所属 XSLFSlideLayout，而 Layout 又引用 XSLFSlideMaster
• XSLFSlideMaster 的底层 CTSlideMaster 包含 ctSldSz（即 p:sldSz），该值直接继承自源 PPTX 的 presentation.xml 根节点
• 调用 appendSlide() 时，POI 复制整个 <p:sld> DOM 节点树，包括嵌套的 <p:sldSz> 声明，且不触发目标文档 CTPresentation.sldSz 的覆盖校验

三、诊断层：定位异常 sldSz 的三步法

1. 用 ZipInputStream 解压目标 PPTX，提取 ppt/presentation.xml，检查根节点：<p:presentation ...><p:sldSz cx="12192000" cy="6858000"/>
2. 对每个插入幻灯片，获取其 slide.getXmlObject().getCSld().getSldSz()，比对 cx/cy 是否与上一步一致
3. 若不一致，说明该 slide 的 layout/master 仍携带源文件元数据——此时 slide.getSlideLayout().getSlideMaster().getXmlObject().getSldSz() 必然不同

四、解决方案层：双轨修复策略（代码+流程图）

核心原则：**解耦源布局依赖，强制锚定目标 presentation 尺寸**。

// ✅ 步骤1：重置单张幻灯片的 sldSz（关键！）
CTSlide ctSlide = slide.getXmlObject();
if (ctSlide.isSetCSld() && ctSlide.getCSld().isSetSldSz()) {
    ctSlide.getCSld().unsetSldSz(); // 清除继承的尺寸
}
// ✅ 步骤2：显式注入目标尺寸（从 targetPres 获取）
CTPresentation targetPres = targetShow.getPackage().getPartsByContentType(
    "application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml")
    .get(0).getPackagePart().getInputStream();
// 实际推荐：复用 targetShow.getPresentation().getSldSz() 的 cx/cy 值
CTSlideSize sldSz = targetShow.getPresentation().getSldSz();
ctSlide.getCSld().setSldSz(sldSz);

graph LR A[appendSlide 或 clone slide] --> B{是否保留源 SlideMaster?} B -->|是| C[继承源 sldSz → 尺寸污染] B -->|否| D[剥离 layout/master 关联] D --> E[手动设置 slide.setSlideLayout
targetShow.getSlideMasters().get(0).getSlideLayouts().get(0)] E --> F[强制写入 targetPres.getSldSz()] F --> G[尺寸统一]

五、进阶实践：构建鲁棒的 PPTX 合并工具类

方法	作用	是否必需
normalizeSlideSize(slide, targetShow)	清除 slide 及其 layout/master 的 sldSz，并重设	✅ 是
rebindToTargetMaster(slide, targetShow)	将 slide.layout 指向 targetShow 首个 master 的默认 layout	✅ 是（防字体/主题错乱）
copyEmbeddedFonts(slideSrc, slideDst)	避免因 font fallback 导致文本重排（间接影响视觉比例）	⚠️ 推荐

六、避坑指南：被低估的“隐性依赖”

除 sldSz 外，以下元数据同样随 slide 深度携带，需同步归一化：

• p:notesSz（备注页尺寸，影响打印布局）
• p:clrMapOvr（颜色映射覆盖，导致主题色阶偏移）
• p:transition 中的 speed 和 advTm（过渡时间不一致引发节奏断裂）

七、验证层：自动化尺寸一致性断言

在 CI/CD 流程中嵌入如下校验逻辑，杜绝人工漏检：

for (XSLFSlide s : targetShow.getSlides()) {
    CTSlideSize actual = s.getXmlObject().getCSld().getSldSz();
    CTSlideSize expected = targetShow.getPresentation().getSldSz();
    assert actual.getCx() == expected.getCx() && actual.getCy() == expected.getCy()
        : String.format("Slide %d size mismatch: %dx%d vs %dx%d", 
            s.getSlideNumber(), actual.getCx(), actual.getCy(), 
            expected.getCx(), expected.getCy());
}

八、原理延伸：为何 POI 不默认修复？

Apache POI 遵循 Open XML ECMA-376 规范的“最小侵入”设计哲学：它忠实地序列化/反序列化 XML 结构，而非充当 PowerPoint UI 的语义代理。PPTX 标准允许每张幻灯片拥有独立 sldSz（用于多尺寸演示场景，如主讲页+备注页混合），因此 POI 将尺寸决策权交还给开发者——这既是灵活性的馈赠，也是专业性的门槛。

```