企业官网建设流程全解析

1. 从"度量单位无效"说起：为什么这么小的一件事能卡住一整天

做Word相关开发的人，早晚都会撞上一次类似"word度量单位无效"的诡异问题。我自己就曾经在服务端用Apache POI生成表格时，明明把列宽参数传进去了，生成的文档用WPS打开完全正常，偏偏用微软Office打开后列宽变成了另外一套数值；还有一次在调整行高时，同一个数字在缩放选项里显示的是厘米，在VBA里读出来却变成了磅，怎么都对不上账。

这种"单位错乱"在Office Open XML（OOXML）生态里几乎是个常态。原因并不复杂：OOXML从ECMA-376规范一路演进下来，内部同时混用了好几套度量单位体系——Points（磅）、Inches（英寸）、EMUs、dxa、twips，甚至还有半磅、百分之一毫米这些派生单位。每种单位服务于不同的对象：字形高度用磅，页面尺寸用英寸或dxa，DrawingML矢量图形则一律用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磅字体存进去就是24，6磅间距存进去就是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里看到cx="914400"时还以为是随便写的位数，后来才反应过来这正是1英寸的EMU值。

更让人头疼的是，不同版本的Word在显示层和存储层之间做单位换算时，精度损失会导致一些看似离谱的现象。比如你在UI里把表格宽度设成"8.5厘米"，用工具打开XML一看，底层存的可能是2413 dxa，而你反向换算回来却发现不是精确的8.5厘米。这种误差不是bug，而是单位换算过程中四舍五入的必然结果。

2.3 EMUs：为了矢量图形而生的一万分之一毫米精度

EMU是English Metric Unit的缩写，看名字像是"英制公制混合单位"，实际上它是一种非常高精度的整数单位。1英寸 = 914400 EMU，1毫米 = 36000 EMU，也就是说EMU的精度大约是1/36000毫米，远超人眼能够分辨的极限。这么高的精度主要为了什么？答案很简单：避免浮点数运算误差。

如果你仔细翻阅office文档里DrawingML相关的XML，会发现所有图形的宽度、高度、坐标、旋转中心、裁剪路径，清一色用整型EMU存储。比如一个在Word里看起来是"5厘米见方"的矩形，XML里对应的可能是：

<wp:extent cx="1800000" cy="1800000"/>

1800000除以360000（1厘米的EMU数）正好等于5，精确没有任何小数位。EMU存在的意义，就是让跨平台渲染矢量图形时坐标计算没有浮点误差，这也是它精度定得如此夸张的根本原因。

2.4 除了这三件套，OOXML里还有几个"隐藏单位"

规范解读类的文章如果不提dxa和twips，那基本等于没讲全。dxa是DrawingML for WordprocessingML里用来度量页面和段落元素的单位，1英寸 = 1440 dxa，1磅 = 20 dxa。twips则是RTF格式时代留下的遗产，1磅 = 20 twips，也就是说dxa和twips数值上恰好一致，这给开发者省了不少记忆负担。

在OOXML里，段落缩进、行距、表格宽度、页边距等样式值基本都以dxa为存储单位。举个例子，页边距left="1440"表示左边距1英寸；表格某一列的宽度w:w="2400"表示120磅；特意设计成20的倍数，本质就是为了和磅保持整数换算关系。很多POI老手应该对这个数值非常眼熟，因为POI里设置表格列宽时，传入的整数数组就是twips，对应到XML里也正是dxa。

3. 理解度量单位之前，必须先理解"隐含单位"机制

3.1 同一个XML属性，单位可能是"半磅"也可能是"整磅"

我说"度量单位无效"的问题，十次里有八次出在隐含单位上。什么叫隐含单位？就是XML属性给出的数值不带单位标识，单位由属性本身的语义约定。最经典的例子是字体大小。

在OOXML里，字体大小属性w:sz的存储规则是"半磅为单位"。也就是说，你想把字体设为12磅，写进XML的不是12，而是24：

<w:rPr> <w:sz w:val="24"/> <w:szCs w:val="24"/> </w:rPr>

24这个数字的意思是"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单位的对应表，整理了很长时间，核心换算路径大概是这样的：

这张表能够解决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 twips，1厘米约等于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来算的。

打个比方，你传入width=300、height=200，POI计算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-TL（poi-template）是另一个高频被问到"列宽设置无效"的库。POI-TL本身走的是模板引擎路线，它不会替你重新计算表格布局，列宽完全取决于模板docx文件里最初设置的值。也就是说，如果你用Word手动画了一个表格，模板里列宽是自动调整的，你往里面填充了很多内容以后POI-TL不会帮你重排，最终Word打开时表格可能因为内容过多而被动扩展，给人一种"列宽设置无效"的错觉。

解决这个问题，我的做法是在模板制作阶段就把表格的列宽固定死。具体操作是：在Word里选中表格 → 表格属性 → 选项 → 取消勾选"自动重调尺寸"，然后手动指定每一列的宽度。这时生成的XML里，每一列会带一个<w:tcW w:w="xxxx" w:type="dxa"/>节点，POI-TL填充时就不会再自适应了。如果模板文件已经生成但列宽没写死，也可以用工具脚本把每个单元格的tcW和table的tblW统一改为固定值，再配合<w:tblLayout w:type="fixed"/>使用。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)接收的单位是twips，360 twips换算过来只有0.95厘米，行高明显缩水。后来把这个值改成row.setHeightInPoints(85)才勉强对得上。这就是同一个类里两个方法单位不一致的坑。所以我在代码审查时有个习惯：凡是看到setHeight、setWidth、setColWidths这类方法名带数值参数的，第一件事就是去JavaDoc里确认单位，而不是猜。

5. 单位换算对照表：开发时要时刻放在手边的速查工具

这里我整理了一份日常开发中最常用的换算速查表。建议可以直接放在工具类注释里，或者做成常量，不要再在代码里散落魔法数字。

有几个数值建议硬背下来：一是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:type="dxa"这类上下文判断

6. 如何验证你算出来的单位是对的：一个治好了我精神内耗的调试法

很多开发者问"我到底该信POI返回的值，还是该信XML里的值"。我的答案是：以XML为准。POI返回的值大量经过二次封装和自动换算，中间任何一步假设错了，结果就不可信。直接解压docx文件，用文本编辑器打开word/document.xml，查看原始数值，是验证单位问题的最终手段。

实际操作流程很简单：

1. 把出问题的docx文件复制一份，把后缀改成zip
2. 解压后找到word/document.xml，或者word/header1.xml等有问题的部件
3. 搜索对应的节点，比如表格宽度就是<w:tcW>，图片尺寸就是<wp:extent>
4. 把拿到的原始数值按上面的速查表换算回你期望的单位，判断是否符合预期

比如你在UI里设置了表格列宽为6厘米，XML里<w:tcW w:w="3401"/>，3401除以567约等于6，这就对了。如果XML显示的是w:w="1200"，2.1厘米都不够，那说明代码里传入的值肯定不对，很可能是把像素或磅直接当twips传了。

我调试时还会做一个动作：先用Word里手动设置一个已知尺寸的图形，比如5厘米宽的正方形，保存后解压看XML里存的cx值。5厘米等于1800000 EMU，这个值可以作为对照基准。如果代码生成的文件里cx=1800000，而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必须等于1800000""1英寸转dxa必须等于1440"，代码改动时跑一遍，心里会踏实很多。

最后，如果你面对的读者不是开发者，而是业务同事，那我的建议是：别让他们跟"厘米"以外的任何单位打交道。哪怕底层全部用EMU，界面和配置文件里也应该只暴露厘米和磅。把Word的内幕留在工程层，产品层越简单越好。这个经验，是我在无数次"我就改了个宽度，怎么变了"的售后沟通里总结出来的。