做Java后端的人几乎没有不认识Apache POI的。我用它做Office文档解析、生成和模板填充最高频的场景就是操作Word。最近接到一个新需求客户要求导出的Word报告必须是A4纸张、上下左右边距固定直接把页面设置写死在程序里。看似简单但真正在poi 5.2.2操作Word时纸张大小和边距的配置藏在底层XML里不少人在这一步就卡住了。这篇内容我按自己完整做过一遍的路子来梳理去哪里拿pageSize、怎么设纸张、怎么设边距、以及各种单位错乱和多节文档的坑。写完你可以直接用这套代码生成一份页面规整的Word文档也适合那些做自动报表、合同导出、打印单据生成的Java开发者参考。1. 先说清楚纸张和边距在Word里到底存在哪1.1 为什么页面设置的关键是“节”很多人上手就找“设置页面大小”的API结果发现XWPFDocument里并没有setPageSize这样的方法。这是因为Word的文档模型里页面尺寸和边距并不属于某个“页面”而是属于“节Section”。一个Word文档可以只有一个节也可以有多个节每个节都可以有自己的纸张大小、方向、边距、页眉页脚等设置。分节符前后的内容互不影响。可以这么理解如果把一篇文档比作一套房子节就是一个个独立的房间纸张和边距是这个房间的“墙线”和“家具边界”。打开Word的“布局”选项卡或者在“页面设置”里看到“应用于整篇文档”还是“插入点之后”本质上就是在跟节打交道。如果你只修改某一段之后的页面设置Word其实会自动在该位置插入一个分节符。所以在POI里思路很直接想办法拿到目标节的sectPrSection Properties再修改里面的pgSzPage Size和pgMarPage Margin。本文后续所有代码底层操作的都是这两个XML节点。只要理解了这一层再去看那些五花八门的POI报错信息基本都能自己定位问题。1.2 POI 5.2.2的底层对象关系Apache POI处理Word的OOXML格式对外暴露的是XWPFDocument、XWPFParagraph、XWPFTable这些“高级对象”但页面设置这种接近元数据的东西藏在底层XML里。具体关系是这样XWPFDocument.getDocument()拿到org.openxmlformats.schemas.wordprocessingml.x2006.main.Document也就是CTDocumentCTDocument.getBody()拿到CTBody这是文档正文容器CTBody.getSectPr()拿到CTSectPr它就是节的属性对象CTSectPr里有两个关键子对象CTPageSz对应XML节点 w:pgSz和CTPageMar对应 w:pgMar。所以一条调用链路是CTSectPr sectPr document.getDocument().getBody().getSectPr();拿到sectPr之后纸张大小和边距都通过它来改。这个命名确实有点绕但把闭环理解之后再去看官方API和源码就不会发懵。CTSectPr、CTPageSz这些类都是schemas的生成类方法名直白比如getPgSz()、addNewPgSz()、setW(BigInteger)。实际使用中不需要记住全部掌握常用的几个就够了。2. 环境准备与核心API速览2.1 Maven依赖与版本选择我用的是Apache POI 5.2.2依赖坐标如下dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.2/version /dependency选5.2.2而不是更早的4.x主要考虑三点一是5.2.x属于较新的稳定版本对JDK8及以上支持很成熟二是很多封装POI的工具库比如各类word模板引擎都以5.x为基准版本兼容性更好三是在xmlbeans的依赖管理上5.2.2内部协调得比较顺基本一个依赖就能把poi核心和ooxml相关类都带进来不太会出现类冲突。有一点要特别提醒只引入poi这个构件是不包含XWPF相关类的必须引入poi-ooxml。导入之后XWPFDocument、CTSectPr这些类就在classpath里了。2.2 核心API对照与单位换算先给一张我在做页面设置时常用的API对照表方便后面看代码类/接口常用方法作用XWPFDocumentgetDocument()获取底层CTDocumentCTBodygetSectPr() / addNewSectPr()获取或新建节属性CTSectPrgetPgSz() / addNewPgSz()获取或新建纸张大小对象CTSectPrgetPgMar() / addNewPgMar()获取或新建页边距对象CTPageSzsetW(BigInteger) / setH(BigInteger)设置页面宽、高单位twipsCTPageSzsetOrient(STPageOrientation)设置页面方向CTPageMarsetTop/setBottom/setLeft/setRight设置上下左右边距单位twipsCTPageMarsetHeader/setFooter/setGutter设置页眉页脚边距与装订线接下来说单位这是最容易出错的地方。OOXML页面设置里的所有尺寸单位都是twips英文也叫“缇”。这个单位的概念是1英寸等于1440 twips1厘米约等于566.929 twips1毫米约等于56.6929 twips。所以当你拿到一个边距值“1440”时别把它当成像素或者磅它其实就是2.54厘米。我习惯在代码里放两个换算方法后面到处都用得到。常用纸型对照表也列一下纸型宽度twips高度twips对应毫米A41190616838210×297A31683823811297×420Letter1224015840216×279B5998414172176×250注意横向时宽高需要互换这个在3.2节细说。3. 实战设置纸张大小3.1 A4纵向最常用的配置直接上代码。声明一个XWPFDocument往里面随便写一行字然后设置A4纵向import java.io.FileOutputStream; import java.math.BigInteger; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPageSz; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSectPr; import org.openxmlformats.schemas.wordprocessingml.x2006.main.STPageOrientation; public class WordPageSetupDemo { public static void main(String[] args) throws Exception { XWPFDocument doc new XWPFDocument(); doc.createParagraph().createRun().setText(页面设置示例); // 拿到节配置没有就新建 CTSectPr sectPr doc.getDocument().getBody().getSectPr(); if (sectPr null) { sectPr doc.getDocument().getBody().addNewSectPr(); } // 纸张大小A4纵向宽11906高16838 CTPageSz pageSize sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(new BigInteger(11906)); pageSize.setH(new BigInteger(16838)); pageSize.setOrient(STPageOrientation.PORTRAIT); try (FileOutputStream out new FileOutputStream(a4_portrait.docx)) { doc.write(out); } } }这里有个细节new XWPFDocument()创建出的空文档body里不一定存在sectPr节点。所以稳妥写法是先getSectPr()判空为空再addNewSectPr()。很多帖子里直接调sectPr.getPgSz()结果空指针原因就在这里。A4的宽度11906来自210×56.6929约等于11906高度16838来自297×56.6929约等于16838。不用死记后面我会给出标准换算方法放到工具类里直接调用即可。3.2 A3横向别忘了同时交换宽高横向是另一个高频需求。打印票据、宽表格、折线图报表经常要把A3横着放。代码里需要注意的点比较多先看一个容易犯错的写法CTPageSz pageSize sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(new BigInteger(23811)); pageSize.setH(new BigInteger(16838)); pageSize.setOrient(STPageOrientation.LANDSCAPE);如果你把A3纵向的原始尺寸直接照搬再配上LANDSCAPE那确实是一个“横向的笨蛋”宽高没有交换方向虽然标了横向但页面还是竖版的比例。正确做法是横向时宽度等于原来纵向的高度高度等于原来纵向的宽度// A3横向宽16838原高高23811原宽 pageSize.setW(new BigInteger(16838)); pageSize.setH(new BigInteger(23811)); pageSize.setOrient(STPageOrientation.LANDSCAPE);换A4横向同理宽16838高11906。记住一句口诀横向就是宽高互换再加orient等于LANDSCAPE。顺序不重要最终宽高必须是互换后的值。为什么必须互换因为OOXML的w:pgSz节点里w属性永远表示“当前方向下的页面宽度”。如果不交换Word打开后会看到页面方向是横向的但内容区域的长宽比不对打印出来更是错乱。这个坑我在生成报告时踩过一次当时排查了半天最后用压缩工具打开document.xml才发现w和h没有交换。3.3 自定义纸张从“毫米”到twips的换算有些场景用不到A4这种标准纸型比如打印送货单、标签纸、卷式小票。常见的是自定义纸张比如100mm×150mm的小卡片。这时最靠谱的方式是提供毫米值通过公式换算成twips。换算逻辑很简单1英寸 25.4毫米1英寸 1440 twips所以毫米转twips的工具方法可以这样写public static BigInteger mmToTwips(double mm) { double twips mm * 1440.0 / 25.4; return BigInteger.valueOf(Math.round(twips)); }用这个方法设置自定义纸型CTPageSz pageSize sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(mmToTwips(100)); // 宽100mm pageSize.setH(mmToTwips(150)); // 高150mm pageSize.setOrient(STPageOrientation.PORTRAIT);注意Math.round的使用因为结果是浮点数直接强转long会丢掉精度。BigInteger.valueOf的参数是long正好接收Math.round的返回值。实测下来四舍五入后的值不会出现边界上的“差1”问题而直接用double强转long在极端情况下可能出现舍入不一致。补充一点Word的自定义纸张尺寸是有范围限制的大约是0.1英寸到22英寸之间超出范围后Word打开会提示“页面设置无效”。所以对用户输入尺寸最好做校验比如高度和宽度至少大于1mm否则生成的文档可能在别人的电脑上打不开。4. 实战设置页边距4.1 快速设置四边等距纸张设完接下来是页边距。还是通过CTSectPr里的CTPageMar来做。如果要统一四边边距比如都是2厘米CTPageMar pageMar sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar(); pageMar.setTop(mmToTwips(20)); pageMar.setBottom(mmToTwips(20)); pageMar.setLeft(mmToTwips(20)); pageMar.setRight(mmToTwips(20));这里用到的setTop/setBottom/setLeft/setRight单位同样是twips。Word的默认边距是上下2.54cm左右3.17cm用twips表示就是上下1440、左右1800。如果你只想改某一边比如让右边距窄一点容纳表格也可以单独setRight其他边保持原值。建议不要一次性把这四个值全部写死成相同尺寸除非业务明确要求。很多导出文档打开后看起来内容挤在左侧多半就是左边距和右边距设成了不合适的绝对值忽略了Word默认的装订线或页边距差异。4.2 分项设置边距与页眉页脚间距CTPageMar不止上下左右它还包含header、footer、gutter三个字段。header表示页眉区域距离页面顶部的距离footer表示页脚区域距离页面底部的距离gutter是装订线预留边距。假如文档需要打印后装订预留0.8cm装订线并且页眉距离顶部1.5cmpageMar.setGutter(mmToTwips(8)); pageMar.setHeader(mmToTwips(15)); pageMar.setFooter(mmToTwips(15));这三个字段不常被注意到但在做正式合同、标书、毕业论文这类文档时装订线和页眉距离经常是硬性要求。我在处理一个客户的标书模板时就差在gutter没设置导致装订后左侧文字被遮住。后来把gutter设成8mm再配合左侧边距适当缩小问题就解决了。需要留个心header和footer的值会影响Word中页眉页脚的可视范围。如果页眉里放了内容但header值太小会出现页眉和正文打架的现象。这类问题去检查页边距里的header属性比在页眉内容上瞎调试要快得多。4.3 基于现有模板微调边距很多时候不是从零创建Word而是读取一个模板docx只改边距然后另存为。这时最好先读出现有值再按需修改CTSectPr sectPr doc.getDocument().getBody().getSectPr(); if (sectPr ! null sectPr.isSetPgMar()) { CTPageMar pageMar sectPr.getPgMar(); // 打印现有的上边距注意转回毫米方便观察 System.out.println(top twipsToMm(pageMar.getTop().longValue()) mm); // 修改左边距为2cm pageMar.setLeft(mmToTwips(20)); } else { // 没有边距定义就直接新建 sectPr.addNewPgMar(); sectPr.getPgMar().setLeft(mmToTwips(20)); }这里的twipsToMm是反向换算public static double twipsToMm(long twips) { return twips * 25.4 / 1440.0; }模板微调的坑在于模板可能有多个节。如果body.getSectPr()返回null不代表全文没有边距只是说最后一个节没有显式sectPr而中间某个节可能定义了独立边距。这个问题专门放到第5章讲。5. 常见问题与排查技巧实录5.1 单位搞错打印出来尺寸不对症状生成文档在Word里看着是A4打印出来却比A4小一圈或者页边距明显偏大/偏小。原因把毫米、厘米、磅这些单位当成twips填进了setW/setH/setTop。比如有人想设2cm边距直接setTop(2)结果得到的是2 twips约0.0035厘米几乎看不见边距反过来写setTop(200)也会差出一个数量级。排查方法生成docx后用压缩工具打开找到word/document.xml搜索pgSz和pgMar两个节点。比如w:pgSz w:w11906 w:h16838/ w:pgMar w:top1440 w:right1800 w:bottom1440 w:left1800 w:header720 w:footer720 w:gutter0/对照之前给的纸型表一眼就能看出值是否正确。如果w11906期望A4说明单位没有问题如果看到一个很小的数比如“210”那一定是你把毫米直接填进去了。我自己的习惯是代码里全部用mmToTwips()不直接写数字。这样即使后面调整纸型只要改mm值可读性和维护性都好很多。5.2 新文档没有sectPr空指针和“设置了但没效果”症状一sectPr.getPgSz()直接抛空指针。 症状二明明调用了setW/setH打开Word一看还是默认Letter大小。这两个现象都指向同一个根源文档里根本没有sectPr节点或者有sectPr但你的修改没有作用到正确位置。对于new XWPFDocument()创建的空文档大多数情况下body里没有现成的sectPr必须先addNewSectPr()。更隐蔽的是第二种你的代码是这么写的CTBody body doc.getDocument().getBody(); body.addNewSectPr().addNewPgSz().setW(...);然后后续又调用body.addNewP()新增段落。这时POI把新段落追加到了body子元素列表的末尾可能被放在了sectPr之后。OOXML规范要求sectPr必须是body的最后一个子元素一旦顺序不对Word打开时可能忽略你的页面设置甚至提示文档损坏。稳妥做法是先创建好所有段落、表格内容最后再去设置sectPr或者每次设置完页面后不要再往body里追加元素。如果实在需要追加内容就重新获取body.getSectPr()再将sectPr元素移到末尾。5.3 多节文档改了最后一节前面的没变一个文档有多个节时body.getSectPr()只代表最后一个节。前面的节其sectPr存在于各节最后一个段落的pPr里。比如一份方案封面页是A4纵向正文要A3横向这就是典型的多节设置。处理办法是遍历所有段落找到带sectPr的段落for (XWPFParagraph paragraph : doc.getParagraphs()) { if (paragraph.getCTP().getPPr() ! null paragraph.getCTP().getPPr().isSetSectPr()) { CTSectPr paragraphSectPr paragraph.getCTP().getPPr().getSectPr(); // 这里就是该段所在节的属性可以修改 } }如果你只是想全局统一还有一种简单方案先把文档所有段落级sectPr删除只保留body最后那个sectPr这样全文就合并成单个节再设置页面属性。注意这个操作会破坏原有的分节结构比如分栏、独立页眉页脚都会失效所以只在确定不需要分节时使用。5.4 横向设置后内容方向不对忘记交换宽高前面3.2节已经强调过横向必须宽高互换orient为LANDSCAPE。这里再补一个容易忽略的点如果模板已经存在pgSz但你只setOrient(LANDSCAPE)没有设置宽高那么Word打开后页面还是原来的长宽比。排查技巧直接在document.xml里检查w:pgSz的w和h。如果w11906、h16838说明是A4纵向如果w16838、h11906且orientlandscape才是A4横向。任何方向异常第一反应就是看这两个数字是不是互换状态。6. 进阶把页面设置封装成工具方法6.1 通用页面设置工具一个项目里处理多套模板、多类文档时把页面设置封装成公共方法能省很多时间。下面这个工具类支持传纸型、方向、边距同时兼容“已有sectPr”和“无sectPr”的情况public class WordPageUtil { public static void setupPage(XWPFDocument doc, int widthMm, int heightMm, STPageOrientation orient, Double marginMm) { CTSectPr sectPr doc.getDocument().getBody().getSectPr(); if (sectPr null) { sectPr doc.getDocument().getBody().addNewSectPr(); } CTPageSz pageSize sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); boolean landscape orient STPageOrientation.LANDSCAPE; if (landscape) { pageSize.setW(mmToTwips(heightMm)); pageSize.setH(mmToTwips(widthMm)); } else { pageSize.setW(mmToTwips(widthMm)); pageSize.setH(mmToTwips(heightMm)); } pageSize.setOrient(orient); if (marginMm ! null) { CTPageMar pageMar sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar(); BigInteger margin mmToTwips(marginMm); pageMar.setTop(margin); pageMar.setBottom(margin); pageMar.setLeft(margin); pageMar.setRight(margin); } } }注意横向的处理我这里的参数widthMm、heightMm是“用户直观理解的宽高”。比如A4纸物理上是210mm宽、297mm高如果横着用调用方传入宽297、高210内部再做一次交换确保最终pgSz里的w永远是当前方向下的宽度。这个设计更贴近业务人员的理解方式。如果你习惯用“纸张物理宽高”那就别做交换直接传A4的210和297内部再处理方向方案不同但思路一致。重点是不管怎么封装最终落到pgSz的w和h必须是“当前方向下的宽高”。6.2 页面设置和其他POI操作的组合顺序除了页面设置POI处理Word时还会频繁遇到写标题、插表格、合并单元格、设置字体、插入图片。页面设置应该在写内容之前还是之后做我的建议是先设置页面再填充内容。原因很实际——表格宽度、页眉内容高度都依赖可用页面宽度。比如你在A4纵向、左右边距各2cm的前提下想放一个占满可用宽度的表格那么表格总宽是21cm - 4cm 17cm。你在代码里把17cm换算成twips后设置到表格单元格。如果页面设置放在填充内容之后表格宽度就得事后矫正很麻烦。实际组合示例// 1. 先建文档并设置A4纵向、边距2cm XWPFDocument doc new XWPFDocument(); WordPageUtil.setupPage(doc, 210, 297, STPageOrientation.PORTRAIT, 20.0); // 2. 再插入一个宽度为17cm的表格 double usableWidthMm 210 - 20 - 20; // 170mm XWPFTable table doc.createTable(3, 3); // 设置表格总宽度 table.setWidth( mmToTwips(usableWidthMm)); table.setTableAlignment(TableRowAlign.CENTER);这里用setTableAlignment让表格居中看起来更协调。类似地页眉高度也会影响正文可用区域但普通业务文档很少动它知道有header这个字段就行。还有一个小经验如果同一个报告要给不同客户用不同纸型不要把纸型和边距写死在业务代码里而是做成配置项或字典表修改时不需要改动程序。我在一个打印项目中就是维护了一张paper_config配置字段包括paper_code、width_mm、height_mm、orientation、margin_top等模板生成时动态读取一劳永逸。就我个人的使用习惯来说POI操作Word页面设置的核心不在代码量而在对“节”“twips单位”“多节归属”这三个点的理解。第一次做的时候我也踩过单位换算的坑后来把mmToTwips和twipsToMm两个方法写进公共类之后几乎再没出过问题。最后再分享一个实用小技巧生成完docx后不要只在Word里看效果顺手用压缩软件打开word/document.xml检查pgSz和pgMar的数值。这个动作对排查“奇怪样式”非常快能省掉不少反复打开Word确认的时间。如果你也正在用POI 5.2.2操作Word的纸张和边距建议直接把文中的工具方法抄进项目再按自己业务调一下参数基本就能覆盖80%的页面设置需求。