搞过Java里用POI生成Word的同学应该都有体会往docx里塞文字、画表格、插图片都还好说最容易被忽略也最容易翻车的是“纸张大小”和“页面边距”。我前阵子接了个合同自动生成的项目需求听起来特别简单——导出的Word能直接打印A4纸边距按公司红头文件那套来上3.7cm、下3.5cm、左2.8cm、右2.6cm。结果真上手之后发现poi 5.2.2操作Word的页面设置坑比想象中多单位不是厘米不是毫米是dxa设置对象不在XWPFDocument上而是藏在“节”里一不小心还会给文档塞出两个sectPr导致Word打开直接报“内容有问题”。这篇文章我就把这一路调通的经验包括底层结构、单位换算、完整代码和踩坑记录一次说清楚给同样在用POI做Word自动化的朋友做个参考。1. 真实场景里页面设置决定文档能不能直接用1.1 三种最典型的需求打印单据、公文排版、PDF导出先说为什么非要在代码里动纸张和边距。第一种是打印场景比如出库单、热敏小票、装箱单程序生成docx之后直接给到打印机纸张尺寸不对的话打出来要么截断要么留大片空白。第二种是公文或合同场景客户对版心有明确要求上面说的红头文件就是典型边距差一毫米都不行。第三种是Word转PDF很多人以为转PDF只需要调好内容就行实际上PDF每一页的尺寸和页边距完全继承自Word的页面设置源头没设对出来的PDF一塌糊涂。这三种场景的共同点是用户不会拿Word再手动调一遍页面设置。你交付的docx打开是什么样他们就直接用什么。所以页面设置必须在程序生成阶段就做好这正是我们要做的事情。1.2 只写内容不设页面到底会发生什么很多教程写POI操作Word上来就createParagraph、createRun、setText写完保存看起来任务完成了。但如果不去碰页面设置最终生成的docx里大概率没有显式的页面规格节点Word/WPS打开时会按自己的默认值处理。这个“默认值”就很微妙了。Word不同版本默认边距不完全一样WPS和Word的默认页边距也有差异。同一个文件在Office 2016里看是一页在WPS里可能变成两页开发机上打印正常客户机器上一打印就多出空白页。问题还不止边距——如果文档压根没有显式的节属性部分PDF转换组件甚至默认按Letter纸渲染导出PDF后页边距和纸张全是乱的。所以我的结论很明确只要你的文档最终要打印、要转PDF、要给别人看排版效果页面设置就是刚需不是可做可不做的优化项。2. 先搞懂页面设置藏在哪节、sectPr、XWPFSection三层关系2.1 Word里的“节”是什么页面设置在Word中不是全局属性而是挂在“节Section”上的。一个文档可以有多个节每个节可以有自己的纸张大小、边距、页眉页脚、页码格式等。比如一篇论文的正文用A4纵向某一页放个大表格要转成横向就是靠分节实现的。在OpenXML里节属性存放在w:sectPr节点中内部包含w:pgSz页面尺寸和w:pgMar页边距两个关键子节点。这个w:sectPr可能出现的位置有两处body级别的w:sectPr定义文档最后一节的属性也就是整个文档最终生效的页面设置。段落属性pPr里的w:sectPr代表分节符从该段落位置开始进入一个新节。大多数情况下我们处理的是单节文档所以只需要操作body级别的sectPr就够了。2.2 POI里的XWPFSection是什么POI 5.2.2对sectPr的封装有好几层。最底层是xmlbeans生成的CTSectPr对应w:sectPr节点中间是XWPFSection提供了setPageSize、setPageMargins这类面向使用者的方法最上层是XWPFDocument.getSections()理论上可以拿到文档所有节的列表但注意——它实际只返回body级别的那一个XWPFSection并不会自动收集段落pPr里藏着的分节符节属性。这是很多人踩坑的根源之一。所以实际操作中我推荐这样获取body级别的节CTSectPr ctSectPr doc.getDocument().getBody().isSetSectPr() ? doc.getDocument().getBody().getSectPr() : doc.getDocument().getBody().addNewSectPr(); XWPFSection section new XWPFSection(ctSectPr);判断一下isSetSectPr()很关键。有些模板文档自带sectPr直接用没问题但新建的XWPFDocument可能没有这个节点如果直接getSectPr()会返回null后面一调用就空指针。更危险的是不管三七二十一直接addNewSectPr()万一文档里已经有一个body级sectPr就可能生成两个同级的节属性节点轻则设置不生效重则文件结构非法打不开。2.3 单位换算dxa和厘米、毫米、磅的关系页面设置里所有长度单位都不是厘米而是dxa也叫twip全称是“twentieth of a point”也就是1磅的1/20。换算关系如下单位等于多少dxa1磅20 dxa1厘米约566.93 dxa1毫米约56.69 dxa1英寸1440 dxa这个换算不是拍脑袋定的1英寸72磅1磅20dxa所以1英寸1440dxa1英寸2.54厘米所以1厘米1440/2.54≈566.93dxa。我建议在代码里维护一个固定常量别每次手算private static final double DXA_PER_CM 1440.0 / 2.54; private static long cmToDxa(double cm) { return Math.round(cm * DXA_PER_CM); } private static long mmToDxa(double mm) { return Math.round(mm * DXA_PER_CM / 10); }为什么强调这个因为网上有些旧代码写的是setPageMargins(37, 35, 28, 26)然后注释写着“上下左右边距”。这完全是拿厘米数直接当dxa用实际渲染出来的边距连0.5毫米都不到打印出来文字快贴到纸边了。单位换算错了后面的所有操作全是白费。3. 设置纸张大小常量、自定义尺寸与横向打印的完整姿势3.1 A4纸在dxa里到底是多少先看代码最简单的方式是用POI自带的PageSize常量section.setPageSize(PageSize.A4);PageSize.A4对应的宽高是多少呢A4纸是210mm×297mm。按前面算的毫米转dxa210×56.69≈11906297×56.69≈16838。所以OpenXML里A4纵向就是w11906, h16838。PageSize类里还内置了A3、LETTER、LEGAL等常见规格用着很方便。但如果你只是要A4认准一个点PageSize.A4的宽是11906、高是16838。后面对比、调试、算版心宽度时这两个数字会反复用到。3.2 自定义纸张按毫米精确换算实际项目中经常遇到非标纸张。比如医院用的自助打印凭条、超市小票纸张宽度可能是80mm、高度不等。这时候没有现成常量必须自己算long widthDxa mmToDxa(80); long heightDxa mmToDxa(150); section.setPageSize(widthDxa, heightDxa);有一点要注意setPageSize的宽高参数传的是纸张在页面方向下的宽和高。如果你的自定义纸张本身没有“标准横向/纵向”的概念就直接传实际物理尺寸的宽高不用考虑太多。3.3 横向打印顺序先交换宽高再写方向属性想要A4横向很多人第一反应是“把方向设成横向”。XWPFSection确实有setOrientation(PageOrientation.LANDSCAPE)方法但实测下来有个细节这个方法只设置pgSz里的orient属性很多版本并不帮你自动交换宽高。也就是说你即使设置了landscape如果pgSz里依然是w11906, h16838Word可能仍然按纵向实际布局渲染或者某些阅读器里表现不一致。稳妥的写法是手动把宽高交换过来再设置方向两者一起做// A4 横向高变宽、宽变高 section.setPageSize(16838, 11906); CTSectPr ctSectPr ...; // 你之前拿到的节对象 CTPageSz pgSz ctSectPr.getPgSz(); pgSz.setOrient(STPageOrientation.LANDSCAPE);为什么要多写一行setOrient虽然很多Office版本主要靠宽高判断方向但orient字段是一个语义标记有些第三方PDF渲染库和较老版本的Word会优先读它。宽高换了、方向也写了才是双保险。反过来从横向改回纵向时同理把宽高换回来再把orient改成PORTRAIT。3.4 设置完怎么核对回读宽高设置完别急着保存可以先打印出来人工核对一下避免出现单位错乱这种低级问题System.out.println(page width section.getPageWidth()); System.out.println(page height section.getPageHeight());如果你看到A4横向打印出来的是16838 11906说明设置正确如果还是11906 16838说明方向处理的逻辑有问题。4. 页边距控制四个基础值之外的隐藏参数4.1 setPageMargins的参数顺序不要太自信XWPFSection设置页边距的方法是这个section.setPageMargins(long top, long right, long bottom, long left);注意顺序是上、右、下、左按顺时针来的不是上、下、左、右也不是上、左、下、右。我见过不止一次有人在这里传错顺序导致上下边距反了或者左右反了。如果你正好要设的是Word默认的“上下2.54cm、左右3.17cm”代码是这样// 上 2.54cm 1440 dxa // 右 3.17cm 1800 dxa // 下 2.54cm 1440 dxa // 左 3.17cm 1800 dxa section.setPageMargins(1440, 1800, 1440, 1800);为什么3.17cm对应1800dxa3.17×566.93≈1797但OpenXML历史上Word的默认右边距就是1800dxa约3.175cm我们沿用它就好。1英寸1440dxa所以2.54cm就是1440dxa这个最好记。4.2 用公文标准算一次边距你就彻底懂了回到我开头说的红头文件场景上3.7cm、下3.5cm、左2.8cm、右2.6cm。按照cmToDxa换算边距要求dxa计算实际值上3.7cm3.7×566.932098下3.5cm3.5×566.931984左2.8cm2.8×566.931587右2.6cm2.6×566.931474对应代码section.setPageMargins(2098, 1474, 1984, 1587);这里有个很实用的校验方法公文标准要求版心是156mm×225mm。A4纸张宽度11906dxa减去左右边距158714743061dxa版心宽是8845dxa除以56.69约等于156mm正确高度16838减去上下边距209819844082dxa版心高12756dxa约等于225mm。如果你算出来的版心宽高和预期对不上那一定是某个边距的数值换算错了。4.3 pgMar里还有页眉、页脚、装订线w:pgMar节点除了top、right、bottom、left四个基础边距还有三个属性header页眉距页面边缘、footer页脚距页面边缘、gutter装订线。setPageMargins一次只设置前四个基础值header、footer、gutter并不会被覆盖这一点有好有坏——好的是不会误伤已有设置坏的是如果你希望页眉页脚也统一控制得单独动手。手动设置这三个值需要拿到底层的CTPageMarCTPageMar pgMar ctSectPr.isSetPgMar() ? ctSectPr.getPgMar() : ctSectPr.addNewPgMar(); pgMar.setHeader(BigInteger.valueOf(720)); // 页眉距边缘 0.5 英寸 pgMar.setFooter(BigInteger.valueOf(720)); // 页脚距边缘 0.5 英寸 pgMar.setGutter(BigInteger.ZERO); // 装订线 0页眉页脚这些值在Word界面里叫“页眉页脚距边界”虽然大多数人不会去动它但如果你的模板原本有页眉页脚而你没有同步设置可能打印时页眉和正文重叠。这属于隐蔽参数不说很多人根本想不起来。5. 踩过的坑节重复、模板残留与跨软件差异5.1 addNewSectPr重复添加Word打开就报错这个坑我印象太深了。最早看一些旧文章直接写doc.getDocument().getBody().addNewSectPr()然后对返回的CTSectPr一顿操作。第一次跑没事第二次跑同一份文档发现页面设置没生效用Office打开还弹了一个“文件已损坏”的提示。原因是这样的如果body里已经存在一个sectPr节点你再调用addNewSectPr()就会再生成一个新的sectPr。而在OpenXML的schema里body级的sectPr有且只能有一个。两个同级的sectPr会导致文档结构非法Word可能忽略其中一个也可能直接报“无法读取的内容”。我现在的习惯是封装一个方法谁来了都不会错private static XWPFSection ensureBodySection(XWPFDocument doc) { CTSectPr ctSectPr doc.getDocument().getBody().isSetSectPr() ? doc.getDocument().getBody().getSectPr() : doc.getDocument().getBody().addNewSectPr(); return new XWPFSection(ctSectPr); }这套逻辑不只是针对新文档操作已有模板时同样适用因为模板带不带sectPr你很难确定。5.2 多节模板只改body级sectPr前面几节不改前面说了getSections()只代表body级那一节。如果客户给的模板文档里用了分节符前面那些章节的页面设置与最后一节可能不同。这时候你只改了body级的sectPr等于只改了最后一节前面的节该多大还多大打印出来依然乱套。要处理多节文档需要遍历每个段落看它的pPr里有没有sectPrfor (XWPFParagraph paragraph : doc.getParagraphs()) { CTPPr pPr paragraph.getCTP().getPPr(); if (pPr ! null pPr.isSetSectPr()) { CTSectPr sectPr pPr.getSectPr(); // 这里同样可以用 XWPFSection 来设置 XWPFSection section new XWPFSection(sectPr); section.setPageSize(PageSize.A4); section.setPageMargins(1440, 1800, 1440, 1800); } }注意表格内部的段落不在doc.getParagraphs()返回范围里如果你的模板结构非常复杂表格里也嵌了分节符那就要递归遍历body下的所有元素包括表格里的段落。生产代码里我建议写一个递归方法把body里所有层级的段落都翻一遍确保不遗漏。5.3 同样的dxaWord和WPS显示出来的厘米数不总一样做完页面设置后用WPS打开docx和用Word打开docx有时“页面设置”对话框里显示的厘米数会差那么零点零几。这是因为两个软件对dxa转厘米时的四舍五入规则不完全一致。比如2098dxa除以566.93精确结果约3.7003cmWord可能显示3.7cmWPS可能显示3.7cm或3.71cm。这种差异基本无伤大雅打印精度也没到要纠结0.001cm的程度。真正要注意的是自定义纸张你在代码里设了一个75mm宽的小票纸Word打开能找到“自定义”纸型WPS某些版本可能把它识成相近的通用纸型或者打印时驱动不支持就直接走默认纸型。这种情况不是POI能解决的需要你提前跟使用方确认他们的打印机驱动和软件版本。6. 完整可运行的Demo与更多玩法6.1 一个从零到一的页面设置Demo下面这段代码我按生产可用的标准写的创建文档、写一段文字、设置A4纵向、设置Word默认边距、输出文件。你可以直接抄去跑import java.io.FileOutputStream; import java.math.BigInteger; import org.apache.poi.xwpf.usermodel.*; import org.openxmlformats.schemas.wordprocessingml.x2006.main.*; public class WordPageSetupDemo { private static final double DXA_PER_CM 1440.0 / 2.54; public static void main(String[] args) throws Exception { try (XWPFDocument doc new XWPFDocument()) { XWPFParagraph paragraph doc.createParagraph(); XWPFRun run paragraph.createRun(); run.setText(A4 纵向上下 2.54cm左右 3.17cm); run.setFontSize(14); // 确保拿到唯一的 body 级节 CTSectPr ctSectPr ensureBodySectPr(doc); XWPFSection section new XWPFSection(ctSectPr); // A4 纵向 section.setPageSize(PageSize.A4); // 上 2.54cm右 3.17cm下 2.54cm左 3.17cm section.setPageMargins(1440, 1800, 1440, 1800); // 同时把页眉页脚距边界设为 0.5 英寸 CTPageMar pgMar ctSectPr.isSetPgMar() ? ctSectPr.getPgMar() : ctSectPr.addNewPgMar(); pgMar.setHeader(BigInteger.valueOf(720)); pgMar.setFooter(BigInteger.valueOf(720)); try (FileOutputStream out new FileOutputStream(demo-page-setup.docx)) { doc.write(out); } System.out.println(done, page width section.getPageWidth() , height section.getPageHeight()); } } private static CTSectPr ensureBodySectPr(XWPFDocument doc) { if (doc.getDocument().getBody().isSetSectPr()) { return doc.getDocument().getBody().getSectPr(); } return doc.getDocument().getBody().addNewSectPr(); } }这段代码跑出来的文件用Word打开页面设置A4纵向边距就是标准的“普通”模板水平。如果想把边距改成公分版式把setPageMargins那三个数学常量换成cmToDxa算出来的值就行。6.2 页面设置和表格宽度要联动页面边距设好之后立刻会遇到一个问题表格宽度该设多少A4纵向、左右边距各1800dxa时版心宽度是11906-1800-18008306dxa。你要做一张撑满版心的表格总宽度就应该设成8306dxa而不是随便写个“表格100%”了事。POI里设置表格总宽度是按底层CTTbl走的XWPFTable table doc.createTable(); CTTblPr tblPr table.getCTTbl().isSetTblPr() ? table.getCTTbl().getTblPr() : table.getCTTbl().addNewTblPr(); CTTblW tblW tblPr.isSetTblW() ? tblPr.getTblW() : tblPr.addNewTblW(); tblW.setW(BigInteger.valueOf(8306)); tblW.setType(STTblWidth.DXA);这一点特别容易踩页面边距设好了表格还是默认宽度或写死的宽度在Word里看表格超出页边距甚至超出纸张范围排版直接崩。页面设置和表格宽度永远是一起考虑的改了一个必须回头检查另一个。6.3 建议把页面设置抽成独立工具项目里如果多个模块都需要生成Word我强烈建议把页面设置这一套抽成独立的方法或工具类。输入参数就是纸型枚举、宽高厘米数、边距厘米数、方向内部负责换算dxa、确保节不存在重复、处理横向宽高交换。public static void setupPage( XWPFDocument doc, PageSize pageSize, double topCm, double bottomCm, double leftCm, double rightCm, PageOrientation orientation) { XWPFSection section ensureBodySection(doc); long width pageSize.getWidth(); long height pageSize.getHeight(); if (orientation PageOrientation.LANDSCAPE) { long tmp width; width height; height tmp; } section.setPageSize(width, height); section.setPageMargins( cmToDxa(topCm), cmToDxa(rightCm), cmToDxa(bottomCm), cmToDxa(leftCm)); // 方向属性单独设置 CTPageSz pgSz section.getCTPageSz(); pgSz.setOrient(orientation PageOrientation.LANDSCAPE ? STPageOrientation.LANDSCAPE : STPageOrientation.PORTRAIT); }抽完以后所有业务代码里只需要一行调用再也不会出现“一个文档写进来了边距却没人管”的情况。我自己的体会是POI操作Word页面设置这件事难点从来不在API本身而在于你愿不愿意把底层结构、单位体系和边界情况想清楚。只要把sectPr、dxa、多节这三个关键点搞明白了后面无论是做报表、合同还是公文模板都能稳稳当当。