1. 从度量单位无效说起为什么这么小的一件事能卡住一整天做Word相关开发的人早晚都会撞上一次类似word度量单位无效的诡异问题。我自己就曾经在服务端用Apache POI生成表格时明明把列宽参数传进去了生成的文档用WPS打开完全正常偏偏用微软Office打开后列宽变成了另外一套数值还有一次在调整行高时同一个数字在缩放选项里显示的是厘米在VBA里读出来却变成了磅怎么都对不上账。这种单位错乱在Office Open XMLOOXML生态里几乎是个常态。原因并不复杂OOXML从ECMA-376规范一路演进下来内部同时混用了好几套度量单位体系——Points磅、Inches英寸、EMUs、dxa、twips甚至还有半磅、百分之一毫米这些派生单位。每种单位服务于不同的对象字形高度用磅页面尺寸用英寸或dxaDrawingML矢量图形则一律用EMU。写代码的人如果只记住了一个单位的进制换一个场景就会踩坑。我翻译这篇Points、Inches和EMUs相关的规范解读文章时最大的感受是国外作者做的事其实特别基础就是把ECMA-376里散落的单位定义、换算关系和应用场景重新梳理了一遍。可就是这样一个主题在实际工程里救了我好几次。这篇博文我打算用译文精读落地实践两条线来写面向两类读者一类是好奇Word内部到底怎么存坐标和尺寸的普通用户另一类是真正要用POI、docx4j或直接手写XML去读写Word文件的开发者。读完以后你至少不会再被22、914400、1440、12700这些神奇数字搞迷糊。2. 先分清三件套Points、Inches和EMUs到底是什么2.1 Points不是像素它是印刷行业的度量基因Points磅缩写pt是桌面排版和印刷领域的老祖宗单位。它的定义很朴素1英寸等于72磅。也就是说1磅约等于0.3528毫米。为啥是72这个数字因为传统印刷行业把1英寸均匀分成72份每一份就是一磅这个习惯从铅字排版时代一直延续到了数字排版时代。在Word里磅主要用在两处一是字符的字体大小你看到字号栏里的小四是12磅五号是10.5磅本质上定义的都是文字的高度基准二是段落格式里的行距和间距比如段前6磅行距固定值20磅这些数值在底层的OOXML XML里通常存储为半磅单位的整数也就是说12磅字体存进去就是246磅间距存进去就是12。很多人在初学时会把pt和px混为一谈尤其是在写CSS写习惯了以后。屏幕上的像素和物理世界的磅之间没有固定比例它依赖设备DPI。96 DPI的显示器上1磅约等于1.333像素但在144 DPI的屏幕上1磅就约等于2像素。Word之所以能在不同设备上保持看起来差不多大就是因为它内部始终以磅为基准做渲染再按设备DPI换算成像素。理解这一点以后再看为什么同一份文档在不同电脑上印刷出来大小接近、屏幕预览却有差别就豁然开朗了。2.2 Inches是画面尺寸的口语单位在XML里却很少直接出现Inches英寸这个单位更好理解1英寸等于25.4毫米。但在OOXML内部英寸很少以浮点数形式直接出现它更多是作为人类可读的中间单位存在。比如在Word UI里设置页边距为1英寸落到XML里实际存的可能是1440 dxa或者914400 EMU。英寸在OOXML里有个非常有意思的作用它是EMU的定义锚点。一个英寸被拆成914400个EMU这个数字对于美制单位使用者来说并不算特别别扭但对于习惯公制的国内开发者来说就很反直觉。我当年第一次在DrawingML里看到cx914400时还以为是随便写的位数后来才反应过来这正是1英寸的EMU值。更让人头疼的是不同版本的Word在显示层和存储层之间做单位换算时精度损失会导致一些看似离谱的现象。比如你在UI里把表格宽度设成8.5厘米用工具打开XML一看底层存的可能是2413 dxa而你反向换算回来却发现不是精确的8.5厘米。这种误差不是bug而是单位换算过程中四舍五入的必然结果。2.3 EMUs为了矢量图形而生的一万分之一毫米精度EMU是English Metric Unit的缩写看名字像是英制公制混合单位实际上它是一种非常高精度的整数单位。1英寸 914400 EMU1毫米 36000 EMU也就是说EMU的精度大约是1/36000毫米远超人眼能够分辨的极限。这么高的精度主要为了什么答案很简单避免浮点数运算误差。如果你仔细翻阅office文档里DrawingML相关的XML会发现所有图形的宽度、高度、坐标、旋转中心、裁剪路径清一色用整型EMU存储。比如一个在Word里看起来是5厘米见方的矩形XML里对应的可能是wp:extent cx1800000 cy1800000/1800000除以3600001厘米的EMU数正好等于5精确没有任何小数位。EMU存在的意义就是让跨平台渲染矢量图形时坐标计算没有浮点误差这也是它精度定得如此夸张的根本原因。2.4 除了这三件套OOXML里还有几个隐藏单位规范解读类的文章如果不提dxa和twips那基本等于没讲全。dxa是DrawingML for WordprocessingML里用来度量页面和段落元素的单位1英寸 1440 dxa1磅 20 dxa。twips则是RTF格式时代留下的遗产1磅 20 twips也就是说dxa和twips数值上恰好一致这给开发者省了不少记忆负担。在OOXML里段落缩进、行距、表格宽度、页边距等样式值基本都以dxa为存储单位。举个例子页边距left1440表示左边距1英寸表格某一列的宽度w:w2400表示120磅特意设计成20的倍数本质就是为了和磅保持整数换算关系。很多POI老手应该对这个数值非常眼熟因为POI里设置表格列宽时传入的整数数组就是twips对应到XML里也正是dxa。3. 理解度量单位之前必须先理解隐含单位机制3.1 同一个XML属性单位可能是半磅也可能是整磅我说度量单位无效的问题十次里有八次出在隐含单位上。什么叫隐含单位就是XML属性给出的数值不带单位标识单位由属性本身的语义约定。最经典的例子是字体大小。在OOXML里字体大小属性w:sz的存储规则是半磅为单位。也就是说你想把字体设为12磅写进XML的不是12而是24w:rPr w:sz w:val24/ w:szCs w:val24/ /w:rPr24这个数字的意思是24个半磅即12磅。为什么规范要这么设计我个人的推测是早期字号的粒度往往就是0.5磅用半磅整数存储比浮点型存储更稳妥、更省空间。但这个设计给开发者挖了很大的坑——用POI读取字体大小时XWPFRun.getFontSize()返回的数值其实是半磅值如果你直接拿它去渲染成PDF或者做其他处理字体就会比预期大一倍。同样的问题也出现在行距上。w:spacing元素里的w:line如果类型是auto数值是240的倍数其含义是每行高度的1/240如果语义是exact或atLeast数值单位反而可能是磅或dxa具体要看上下文。这就导致同一个属性在不同取值策略下单位解释完全不同。代码里不做判断必然出错。3.2 表格宽度、缩进、间距从UI到XML的换算路径我专门画过一张Word UI数值到底层XML单位的对应表整理了很长时间核心换算路径大概是这样的对象UI显示单位底层XML单位换算示例字体大小磅半磅w:sz12磅 → 24段落行距磅/多倍行距dxa 或 1/240行距固定值20磅 → 400表格列宽厘米/磅dxa3.18厘米 → 1800页边距厘米/英寸dxa2.54厘米 → 1440图片尺寸厘米EMU5厘米 → 1800000缩进厘米/字符dxa 或 w:chars0.74厘米 → 420这张表能够解决90%的我明明设置了宽度打开文档却变了的困惑。很多情况下问题不是代码逻辑不对而是用户传入的数值被当成了一种单位底层却用另一种单位存储导致最终效果和预期相差一个常数倍。3.3 为什么分不清单位时改标尺单位为厘米会看起来无效Word UI里有一个非常著名的反直觉设置文件 → 选项 → 高级 → 显示 → 度量单位把单位从英寸改成厘米。不少用户改了以后发现标尺确实变成了厘米但段落-缩进-特殊格式-首行缩进里的数值还是2字符制表位设置里却变成了厘米。这算度量单位无效吗严格来说不算。原因是Word界面上不同功能组件各自绑定了一套独立单位系统。标尺跟随显示度量单位走首行缩进的默认单位是字符因为中文排版习惯以字符宽度为基准制表位又跟随度量单位走。用户以为有一个全局设置能统管一切实际上每个组件的单位是写死在功能逻辑里的。这个现象在英文社区被反复讨论过也是我翻译这篇度量单位文章的原始动机之一——很多人花大量时间试图修改配置让Word显示上统一却不知道问题的本质是Word内部并行的多套单位体系。4. 实操战场POI读写Word时的单位换算与避坑记录4.1 用POI设置表格列宽为什么老是不生效在Apache POI里操作Word表格列宽是很典型的单位披露不完整的场景。常见的写法是用XWPFTable.setColWidths(int[])这个方法的JavaDoc里明确写了单位是twips。twips和dxa数值上等价1英寸 1440 twips1厘米约等于567 twips。所以如果你要把一列设为8厘米宽传入的应该是8 * 567 4536左右。问题往往出在这里很多教程和答案里直接写table.setColWidths(new int[]{2400, 2400})理由是2400是标准宽度。但2400 twips是什么概念120磅约4.23厘米。如果你的页面是A4纸可用宽度大约17厘米两列各4.23厘米显然窄得离谱。可为什么网上还到处是这种写法因为那些示例多半是从英文文档里抄来的英文排版里单栏宽度本来就不宽加上表格自动调整过没细看就当成模板用了。更稳妥的写法是在XML节点层面直接操作dxa值。POI虽然提供了高层API但高层API之间的单位约定并不完全一致。比如CTTblWidth节点的setW(BigInteger)方法接收的就是dxa值。我自己习惯封装一个工具函数把所有外部传入的厘米或磅统一转成dxa再赋值public static int cmToDxa(double cm) { return (int) Math.round(cm / 2.54 * 1440); } public static int cmToTwips(double cm) { return cmToDxa(cm); } public static long cmToEmu(double cm) { return Math.round(cm / 2.54 * 914400); } public static int pointsToDxa(double points) { return (int) Math.round(points * 20); }这里我统一用厘米作为外部接口的单位因为国内用户和产品经理给需求时通常说的都是8厘米3厘米而不是227 twips或2.99英寸。换算时注意四舍五入dxa的粒度是1/1440英寸厘米换算过去后肯定有小数位直接截断可能会造成累计误差。4.2 图片大小和坐标EMU换算中的两大高频坑处理Word里Insert Picture或者浮动图片时POI的XWPFRun.addPicture需要传入InputStream、图片类型、文件名和尺寸尺寸的单位是px。这里让人晕的地方在于底层XML里存的却是EMU。POI会在addPicture内部自动把传入的px转换成EMU但它是按照96 DPI来算的。打个比方你传入width300、height200POI计算EMU的公式是px / 96 * 914400这在一个96 DPI的Windows屏幕上显示正好是300像素图片的实际物理尺寸。但如果你把同一份文档拿到Mac的Retina屏上打开Word会按系统缩放比例重新渲染实际显示出来的物理宽度可能更大或更小。也就是说addPicture里那个px只是一个逻辑像素映射到物理世界要依赖于渲染环境根本做不到绝对精确。如果你自己手写DrawingML比如往document.xml里塞一个wp:extent cx... cy.../你就必须保证EMU值算对。我最常看到的错误是把厘米转换成EMU时用错了系数——有人用914400除以2.54得36000去做毫米换算结果在厘米和毫米之间差了整整10倍图片直接变成巨无霸或者小到看不见。建议不管前端传入什么单位后端统一用一个转换服务处理避免散落在各处各算各的。4.3 POI-TL处理模板时如何在模板XML里直接锁定列宽POI-TLpoi-template是另一个高频被问到列宽设置无效的库。POI-TL本身走的是模板引擎路线它不会替你重新计算表格布局列宽完全取决于模板docx文件里最初设置的值。也就是说如果你用Word手动画了一个表格模板里列宽是自动调整的你往里面填充了很多内容以后POI-TL不会帮你重排最终Word打开时表格可能因为内容过多而被动扩展给人一种列宽设置无效的错觉。解决这个问题我的做法是在模板制作阶段就把表格的列宽固定死。具体操作是在Word里选中表格 → 表格属性 → 选项 → 取消勾选自动重调尺寸然后手动指定每一列的宽度。这时生成的XML里每一列会带一个w:tcW w:wxxxx w:typedxa/节点POI-TL填充时就不会再自适应了。如果模板文件已经生成但列宽没写死也可以用工具脚本把每个单元格的tcW和table的tblW统一改为固定值再配合w:tblLayout w:typefixed/使用。fixed布局是让Word忽略内容长度、强制使用指定宽度的关键没有这一项固定宽度也白搭。4.4 Java Word转PDF时单位换算误差引发的排版错乱Java生态里做Word转PDF大多走docx4j或apache poi openhtmltopdf的组合路线。docx4j在转换时会尽可能忠实于OOXML里的原始数值理论上单位换算这一层是透明的。但如果你在转PDF之前对文档做过内存中的修改比如用POI把某些段落行距重新设置了那么单位选错造成的偏差就会原封不动地传导到PDF里。我遇到过最典型的案例是用POI把Excel表格数据粘进Word文档并重新设置了行高代码里写的是row.setHeight(360)本意是3厘米。但XWPFTableRow.setHeight(int)接收的单位是twips360 twips换算过来只有0.95厘米行高明显缩水。后来把这个值改成row.setHeightInPoints(85)才勉强对得上。这就是同一个类里两个方法单位不一致的坑。所以我在代码审查时有个习惯凡是看到setHeight、setWidth、setColWidths这类方法名带数值参数的第一件事就是去JavaDoc里确认单位而不是猜。5. 单位换算对照表开发时要时刻放在手边的速查工具这里我整理了一份日常开发中最常用的换算速查表。建议可以直接放在工具类注释里或者做成常量不要再在代码里散落魔法数字。目标单位1英寸1厘米1毫米1磅dxa / twips1440566.93约56756.69约5720EMU9144003600003600012700Point磅7228.352.8351有几个数值建议硬背下来一是1440做Word页面布局相关操作天天会用到二是914400和360000做图片尺寸、DrawingML时会用到三是20它把磅和dxa连接起来。看一眼表就知道dxa体系的粒度是1/1440英寸EMU体系的粒度是1/914400英寸EMU的精度比dxa高了好几个数量级所以Graphics层的坐标才用EMU而不用dxa。下面是应对具体开发场景的换算建议传入POI高层的setColWidths、setHeight时确认方法是twips还是points单位避免混用手写XML节点时w:sz用半磅w:spacing区分line和before/after的语义再决定单位图片写入时建议用getEMU自己主动换算而不是依赖POI内置的px假设凡是UI传入尺寸统一在Controller层换算成EMU或dxa服务层不要出现这个值可能是像素也可能是磅的模糊状态解析别人的XML时不要凭属性名猜单位务必结合w:tblLayout、w:typedxa这类上下文判断6. 如何验证你算出来的单位是对的一个治好了我精神内耗的调试法很多开发者问我到底该信POI返回的值还是该信XML里的值。我的答案是以XML为准。POI返回的值大量经过二次封装和自动换算中间任何一步假设错了结果就不可信。直接解压docx文件用文本编辑器打开word/document.xml查看原始数值是验证单位问题的最终手段。实际操作流程很简单把出问题的docx文件复制一份把后缀改成zip解压后找到word/document.xml或者word/header1.xml等有问题的部件搜索对应的节点比如表格宽度就是w:tcW图片尺寸就是wp:extent把拿到的原始数值按上面的速查表换算回你期望的单位判断是否符合预期比如你在UI里设置了表格列宽为6厘米XML里w:tcW w:w3401/3401除以567约等于6这就对了。如果XML显示的是w:w12002.1厘米都不够那说明代码里传入的值肯定不对很可能是把像素或磅直接当twips传了。我调试时还会做一个动作先用Word里手动设置一个已知尺寸的图形比如5厘米宽的正方形保存后解压看XML里存的cx值。5厘米等于1800000 EMU这个值可以作为对照基准。如果代码生成的文件里cx1800000而Word里显示的还是不对那问题可能不在单位换算而在渲染环境的DPI缩放这时候就要去看系统显示设置而不是XML了。7. 本地化与版本差异为什么中文版Word更容易让人觉得单位无效用中文版Word的用户还有一个额外困扰——中文语言包和公制习惯让单位显示默认走厘米但OOXML底层是英制世界的产物。Word在显示层做了很多本地化适配改UI上的单位很容易但内部存储、打印布局、兼容模式下的生成逻辑仍然以英制单位为锚点。于是会出现显示为厘米、存储为英寸、计算用磅三种状态同时存在的局面。这也就是为什么度量单位无效这个说法在网上被大量讨论——用户改了一个地方的设置以为所有地方都会跟着变开发者改了一个地方的单位换算以为整个文档布局都会按预期调整。实际结果往往是一处生效了另一处纹丝不动。遇到这种情况不要靠猜按上面解压看XML原始值的方法定位问题效率会高得多。另外Word的兼容模式比如用新版本Word打开doc格式文档也是单位错乱的重灾区。doc和docx的底层单位体系不完全一致doc兼容层转换可能会把某些值放大或缩小最典型的就是图片尺寸差一点、表格宽度偏几个像素。如果你处理的是历史遗留的doc文档先另存为docx再操作能减少很多单位相关的诡异问题。8. 根据我这几年的实操经验最后分享几个小技巧我第一次系统梳理OOXML度量单位就是在被表格列宽无效折磨了两天之后痛定思痛的结果。后来我养成了一个不算麻烦的习惯项目里所有跟Word打交道的代码统一建一个WordUnitUtil工具类所有外部入参的尺寸都用厘米或磅表达内部换算成目标单位后再组装XML。这个习惯帮我少踩了无数坑。其次我强烈建议在代码仓库里留一个单位换算单测。不要看不起这几个看似简单的数学公式我见过太多因为把毫米和厘米搞混、把twips当成points传入而产生的事故。写一组固定输入的断言用例比如5厘米转EMU必须等于18000001英寸转dxa必须等于1440代码改动时跑一遍心里会踏实很多。最后如果你面对的读者不是开发者而是业务同事那我的建议是别让他们跟厘米以外的任何单位打交道。哪怕底层全部用EMU界面和配置文件里也应该只暴露厘米和磅。把Word的内幕留在工程层产品层越简单越好。这个经验是我在无数次我就改了个宽度怎么变了的售后沟通里总结出来的。
