如何用Apache POI在Word文档首页左侧添加跨页垂直矩形形状

你之前用段落插入图片的方式会导致形状仅绑定单个段落，出现重叠问题，正确的做法是给首页添加锚定在页面的浮动矩形形状，通过首页专属页眉来实现，让形状固定在页面左侧，从顶部延伸到底部。

实现步骤及代码示例 #

以下是基于Apache POI 5.x版本的Java代码实现：

1. 初始化文档并获取页面尺寸
   先获取Word页面的实际高度，用来设置矩形高度，确保覆盖整个页面垂直范围：

XWPFDocument doc = new XWPFDocument();
// 获取文档节属性，用于读取页面尺寸
CTSectPr sectPr = doc.getDocument().getBody().getSectPr();
if (sectPr == null) sectPr = doc.getDocument().getBody().addNewSectPr();
CTPageSz pageSz = sectPr.getPgSz();
// 页面高度（单位：twip，1twip=1/1440英寸）
long pageHeight = pageSz.getH().longValue();

2. 创建首页专属页眉
   设置文档的首页单独页眉，确保矩形仅在首页显示：

XWPFHeaderFooterPolicy headerFooterPolicy = doc.createHeaderFooterPolicy();
// 创建仅首页生效的页眉
XWPFHeader firstPageHeader = headerFooterPolicy.createHeader(XWPFHeaderFooterPolicy.FIRST);

3. 添加垂直矩形形状
   在首页页眉中插入锚定到页面的矩形，设置位置、尺寸和样式：

// 创建承载形状的段落
XWPFParagraph para = firstPageHeader.createParagraph();
XWPFRun run = para.createRun();

// 定义矩形形状
CTShape ctShape = run.getCTR().addNewDrawing().addNewInline().addNewGraphic().addNewGraphicData().addNewSp();
// 指定形状类型为矩形
ctShape.addNewSpPr().addNewPrstGeom().setPrst(STShapeType.RECT);

// 设置矩形尺寸：宽度设为200twip（可自行调整），高度与页面一致
CTTransform2D transform = ctShape.getSpPr().addNewXfrm();
transform.addNewExt().setCx(200 * 20); // 单位转换：1twip=20EMU
transform.addNewExt().setCy(pageHeight * 20);

// 将形状锚定到页面左侧，与页面边距无间隔
CTAnchor anchor = run.getCTR().getDrawing().getInline().changeToAnchor();
anchor.setDistT(0);
anchor.setDistL(0);
anchor.setDistB(0);
anchor.setRelativeHeight(pageHeight);
// 设置锚定参考为页面
anchor.addNewPositionH().setRelativeFrom(STRelFromH.PAGE);
anchor.addNewPositionV().setRelativeFrom(STRelFromV.PAGE);

// 设置矩形填充颜色（示例为深蓝色）
CTSolidColorFillProperties fill = ctShape.getSpPr().addNewSolidFill();
fill.addNewSrgbClr().setVal(new byte[]{0x1E, 0x3A, 0x8A});

// 移除矩形边框
ctShape.getSpPr().addNewLn().addNewNoFill();

4. 写入输出文档

try (FileOutputStream out = new FileOutputStream("output.docx")) {
    doc.write(out);
}
doc.close();

关键说明 #

• 用首页专属页眉确保矩形仅在首页显示，不会影响其他页面
• 通过CTAnchor将形状锚定到页面而非段落，彻底避免和正文内容重叠
• 矩形高度与页面高度绑定，保证从顶部延伸到底部
• 可根据需求修改矩形的宽度、填充色、边框等样式

内容的提问来源于stack exchange，提问作者Bharath Naidu Yenumula