企业官网建设流程全解析

做过演示文稿自动化的人大概都遇到过同一个尴尬：脚本跑得干干净净，产出的文件打开一看，本该是表格的地方要么被拆成十几个互不相干的文本框，要么整块变成一张位图，想改个字都得重新生成一版。问题不在渲染，而在生成阶段——表格从来就不是"把文字摆成几行几列"这么简单的事，它是一套带网格语义、带合并关系、带边框归属规则的结构化对象。ppt-master 里专门拆出来的表格执行器分支（Executor Table Branch），干的正是这件脏活：把上游排版阶段产出的语义单元格网格，编译成 PPTX 里真正的原生表格对象。这篇就把这套构建规范从头到尾捋一遍，包括数据结构怎么定、a:tbl 骨架怎么搭、合并单元格怎么写才不会崩、边框为什么总画双线、行高为什么永远比算出来的高。写给已经能生成幻灯片、但在表格这一关卡住的人，也写给打算自己写一套导出管线、想知道哪些坑可以提前绕开的人。

1. 语义单元格网格的输入契约：执行器到底在编译什么

表格执行器这个名字容易让人误会，好像它负责"画表格"。它其实不画，它做的是编译——输入是一种与渲染无关的中间表示，输出是 DrawingML 里的 a:tbl 子树。编译器的第一原则是输入契约必须严格，一旦上游给的网格本身是"歪"的（合并关系不自洽、行列数不齐、锚点指向越界），下游再怎么补救都是在给脏数据打补丁。所以这一层要先说清楚：网格该长什么样，以及为什么它不能更简单。

1.1 为什么二维字符串数组撑不起这个分支

最直觉的做法是让上游传一个string[][]，执行器按行列铺开就完事。这个方案在纯文本表格上能跑，但只要出现合并单元格就立刻崩塌。原因很直白：二维数组是"每个格子都必须存在"的稠密结构，而合并单元格在语义上是"一个格子占据了多个位置"，那些被占据的位置在数据层面根本不该有独立内容。

有人会用空字符串占位，比如把合并区域里被覆盖的格子填成""。这招在渲染简单 HTML 时勉强能用，因为它靠浏览器自己算 rowspan 的占位；但在 PPTX 里，被合并的单元格必须显式写成带hMerge="1"或vMerge="1"的空壳a:tc，且不能带任何文本内容。如果执行器分不清"这个空格子是真的空"还是"这个格子是被合并掉的占位"，它就只能二选一，两种选择都会错：当成真空格子写，表格里会多出一堆空单元格，边框全部多画；当成占位写，用户真正想要留白的单元格就消失了。

再加一层，二维数组还丢掉了类型语义。真实排版里，表头行、汇总行、数值列、备注列的处理方式完全不同——表头要加粗、要居中、要底色；数值列要右对齐、要用等宽数字；备注列要允许换行、字号更小。这些信息如果只能靠在字符串里塞标记（比如**加粗**）来表达，等于把富文本解析的负担又塞回执行器，越写越乱。

所以输入必须是对象网格，而不是字符网格。这是整个分支的第一条硬规矩。

1.2 一份能稳定跑通的网格数据结构

我在项目里用的是"单元格对象 + 稀疏覆盖"的组合：表格本体持有行列数与列宽定义，单元格以(row, col)为键存放在映射里，只记录"锚点单元格"，被合并覆盖的位置不存任何东西。执行器在生成阶段再根据跨度展开成稠密结构，这一步叫"矩形化展开"，后面会细说。

一个够用的单元格对象大概包含这些字段：

注意runs和text的优先级关系要写死：只要runs非空就完全忽略text，不做拼接合并。早期我试过"用 text 当兜底、runs 当增强"，结果同一段内容被渲染两遍，排查了半天才发现是这里的分支没互斥。

还有一个容易被忽略的字段——colWidths。列宽不属于单元格，属于表格。它必须由上游给定或由执行器求解，绝不能留给渲染引擎自适应。理由在第 2 章展开。

1.3 矩形化与合并锚点归一：编译前的第一道清洗

拿到稀疏网格之后，第一件事不是写 XML，而是做三件清洗，顺序不能换。

第一件，越界裁剪。检查每个锚点的row + rowSpan <= rowCount且col + colSpan <= colCount，超出的直接裁到边界，并打一条警告日志。这一步看着多余，但上游算错宽度的情况非常常见，尤其表格是从别的格式转换过来的时候。不裁的话，后面对齐列宽时会出现数组越界，报错信息还指不到源头。

第二件，重叠检测。用一张rowCount × colCount的标记矩阵，按行列顺序遍历所有锚点，把它覆盖的每个位置打上标记。如果某个位置被打第二次，说明两个单元格抢同一块地，这是数据错误，必须抛出来，不能"后者覆盖前者"——静默覆盖会让用户看到一张缺了行的表，比直接报错难查十倍。

第三件，稠密展开。按tr顺序逐行生成，对每个位置判断：如果它是某个锚点的原点，生成完整a:tc并带上gridSpan/rowSpan；如果它被某个锚点覆盖但不是原点，生成占位a:tc，带hMerge="1"（水平方向被覆盖）或vMerge="1"（垂直方向被覆盖）。

这里有个细节值得单独说：当一个单元格同时被水平和垂直覆盖时（比如一个 2×2 合并区域里的右下角），该写hMerge还是vMerge？我的做法是优先写hMerge="1"。原因是 PowerPoint 在解析时对 hMerge 的处理更宽容，而部分第三方渲染器在遇到vMerge但同行左侧没有可合并源时会直接把整行错位。实测下来，全用hMerge表示"这一格是别人的地盘"，只在纯垂直合并的列上才用vMerge，兼容性最好。

另外，合并锚点单元格本身必须显式带上rowSpan和colSpan，即使值是 1 也可以省略（省略即视为 1），但只要是大于 1 就必须写。有些实现喜欢只在锚点上写 span、不给被覆盖格子写 merge 标记，指望渲染器自己推——这在 PowerPoint 里多数时候能显示对，另存一次或者进别的软件就散了。

2. 把网格编译成 a:tbl：骨架、顺序与单位换算

清洗完的网格还是数据，接下来才是真正的编译。这一章讲三件事：XML 骨架长什么样、尺寸怎么换算成 EMU、合并单元格的四种属性怎么落。这三件事里的任何一件出错，产出的文件都可能"能打开但显示不对"，而这类问题最难调试，因为文件本身不报错。

2.1 a:tbl 的最小骨架与不能乱动的元素顺序

先看一个最小可用骨架，两列一行，能跑通所有主流渲染器：

<p:graphicFrame> <p:nvGraphicFramePr> <p:cNvPr id="7" name="Table 1"/> <p:cNvGraphicFramePr> <a:graphicFrameLocks noGrp="1"/> </p:cNvGraphicFramePr> <p:nvPr/> </p:nvGraphicFramePr> <p:xfrm> <a:off x="914400" y="1524000"/> <a:ext cx="4572000" cy="740000"/> </p:xfrm> <a:graphic> <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/table"> <a:tbl> <a:tblPr firstRow="1" bandRow="0"> <a:tableStyleId>{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}</a:tableStyleId> </a:tblPr> <a:tblGrid> <a:gridCol w="2286000"/> <a:gridCol w="2286000"/> </a:tblGrid> <a:tr h="370840"> <a:tc> <a:txBody> <a:bodyPr/> <a:lstStyle/> <a:p> <a:r> <a:rPr lang="zh-CN" sz="1400" b="1"/> <a:t>指标</a:t> </a:r> </a:p> </a:txBody> <a:tcPr anchor="ctr"/> </a:tc> <a:tc> <a:txBody> <a:bodyPr/> <a:lstStyle/> <a:p> <a:r> <a:rPr lang="zh-CN" sz="1400" b="1"/> <a:t>数值</a:t> </a:r> </a:p> </a:txBody> <a:tcPr anchor="ctr"/> </a:tc> </a:tr> </a:tbl> </a:graphicData> </a:graphic> </p:graphicFrame>

这段骨架里，有四处顺序是 schema 强制的，错了就直接损坏文件：a:tbl下必须是tblPr→tblGrid→ 若干个tr；a:tc下必须是txBody→tcPr，tcPr在前会报错；a:tcPr里边框（lnL/lnR/lnT/lnB）必须在填充之前，填充必须在headers之前；a:txBody下必须是bodyPr→lstStyle→ 段落。lstStyle可以为空但不能省，很多生成器图省事直接跳过，PowerPoint 通常能容错，但在一些解析严格的工具里会直接判为非法。

还有一个坑：p:xfrm的a:ext必须和表格实际宽高一致。cx应该等于所有gridCol的w之和，cy应该等于所有tr的h之和。不一致时，会出现"表格本身按 gridCol 渲染，但选中框和占位按 ext 显示"的分裂现象，用户拖动一下就会看到表格突然跳变。我现在的做法是先算好列宽行高，再回填xfrm，保证两处数字同源。

2.2 列宽与行高的 EMU 换算，以及"看起来对但渲染不对"的根源

PPTX 的尺寸单位是 EMU（English Metric Unit），换算关系记住了就不会出错：1 英寸 = 914400 EMU，1 厘米 = 360000 EMU，1 磅 = 12700 EMU。

为什么不用磅或厘米？因为 EMU 是整数单位，能整除英寸和厘米的常见分数（1/2、1/4、1/8 英寸都是整数），避免浮点误差累积。这是设计上的取舍，我们照做就行——所有尺寸计算完成后再统一转 EMU 并取整，中途不要反复换算。

列宽的来源通常有三种：上游显式给定、按内容比例分配、平均分配。我优先用第一种，第二种作为兜底。按内容比例分配的具体做法是：先估算每列内容在字号下的文本宽度，加左右边距，取最大值作为"理想宽度"，再按总可用宽度做等比缩放。缩放的时侯要注意最小值约束——不要让任何一列缩到比"最长的不可断词 + 边距"还窄，否则会出现单个字符被挤到下一行的情况，视觉上非常难看。

行高的算法更微妙。a:tr的h属性在规范里的语义是最小高度，不是固定高度。内容超了，渲染器会把行撑开；内容不够，行也不会缩。这就解释了为什么你算出一个精确值写进去，打开文件还是发现行更高——多半是渲染器算出的"文字行高 + 上下边距"大于你给的值。关于这一点，第 4 章会给出求解模型。

2.3 合并单元格：gridSpan / rowSpan / hMerge / vMerge 的四件套

四个属性的分工要记清楚，混用是必崩的：

• gridSpan：写在锚点a:tc上，表示这一格横向占几列，缺省 1；
• rowSpan：写在锚点a:tc上，表示纵向占几行，缺省 1；
• hMerge="1"：写在被横向覆盖的a:tc上，表示"我这格是右边某格的地盘"；
• vMerge="1"：写在被纵向覆盖的a:tc上，表示"我这格是上面某格的地盘"。

关键点在于：一张表里a:tc的总数永远等于 rowCount × colCount，合并只改变哪一格是"实体"、哪一格是"占位"，绝不减少节点数量。这是最容易搞错的地方，很多人以为合并就是把节点删掉，结果生成出来行列全乱。

举个具体例子，一个 3×3 网格，中间那个 2×2 区域合并：

(0,0) (0,1) (0,2) (1,0) [====合并锚点====] (2,0) [====占位========]

展开后的 XML 片段是这样的：

<a:tr h="370840"> <a:tc><a:txBody>…</a:txBody><a:tcPr/></a:tc> <a:tc><a:txBody>…</a:txBody><a:tcPr/></a:tc> <a:tc><a:txBody>…</a:txBody><a:tcPr/></a:tc> </a:tr> <a:tr h="370840"> <a:tc><a:txBody>…</a:txBody><a:tcPr/></a:tc> <a:tc gridSpan="2" rowSpan="2"> <a:txBody>…</a:txBody><a:tcPr/> </a:tc> <a:tc hMerge="1"><a:txBody><a:bodyPr/><a:lstStyle/><a:p/></a:txBody><a:tcPr/></a:tc> </a:tr> <a:tr h="370840"> <a:tc><a:txBody>…</a:txBody><a:tcPr/></a:tc> <a:tc vMerge="1"><a:txBody><a:bodyPr/><a:lstStyle/><a:p/></a:txBody><a:tcPr/></a:tc> <a:tc hMerge="1"><a:txBody><a:bodyPr/><a:lstStyle/><a:p/></a:txBody><a:tcPr/></a:tc> </a:tr>

三个占位格都必须有完整结构，a:txBody里放一个空段落即可，a:tcPr可以留空但标签不能少。占位格里千万不能写文字，写了也不会显示，但会让后续做内容检索的工具读出一堆脏数据。

还有一个隐藏约束：锚点的gridSpan必须和它右侧连续的hMerge数量对上，rowSpan必须和下方连续的vMerge数量对上。渲染器会做交叉校验，对不上时行为未定义——有的版本直接忽略合并，有的版本把表格截断。执行器在输出前应该跑一遍自校验，把这类不一致拦在写文件之前。

3. 视觉还原：边框、填充、文字属性往哪一层写

结构对了只是能用，视觉对了才算好看。这一章集中处理四类属性，它们有一个共同特点：都能写在多个层级上，但只有一个层级是对的。写错层级不会报错，只会出现"属性被覆盖""某几格颜色不一样""文字大小莫名其妙变了"这类玄学现象。

3.1 边框的归属约定：相邻单元格为什么会画出双线

PPTX 里每个单元格拥有自己的四条边：a:lnL（左）、a:lnR（右）、a:lnT（上）、a:lnB（下），没有任何"表格级边框"的概念。这就带来一个必然问题：A 格的右边和 B 格的左边是同一条物理线，两边都设置会发生什么？

答案是重叠绘制。边框线以单元格边界为中线，向两侧各扩展一半宽度。两个相邻单元格各设 1 磅黑线，视觉上仍然是一条 1 磅黑线（因为完全重合），不会变成 2 磅。但如果一边设黑、一边设红，最终颜色就取决于绘制顺序，不同引擎的结果可能不同。

所以要建立一套归属约定，让每条物理边只被一方声明。我在执行器里采用的是"左上和右下"规则：

• 每个单元格负责绘制自己的上边和左边；
• 最右一列额外负责右边，最后一行额外负责下边。

这样每条物理线恰好被声明一次，颜色宽度完全可控。代价是如果用户想给某个单元格单独加右边框，执行器需要把这条边"转移"给右侧邻居的左边，而不是直接写在它自己的 lnR 上。这个转换逻辑要小心处理跨行跨列的合并区域——合并区域内部不应该有任何边框，边界框要按合并后的外轮廓来算。

顺带说一个实际踩过的坑：边框宽度不能设得太细。a:ln w="0"在某些渲染器里会被当成"无边框"，在另一些里会被当成"最细的线"，行为不一致。宽度为 0 时，正确做法是完全省略该a:ln元素，或者写<a:ln><a:noFill/></a:ln>，后者语义最明确。

3.2 填充与条纹：把表格样式剥到单元格粒度

a:tblPr上的firstRow、firstCol、lastRow、lastCol、bandRow、bandCol这六个布尔属性，控制的是内置表格样式的启用开关。它们配合a:tableStyleId使用，能一键获得首行加粗、隔行变色等效果。

听起来很省事，但我不建议依赖它。原因有三：内置样式的 GUID 表在不同版本的办公软件里并不完全一致，有些版本找不到指定的样式会静默回退到默认样式；样式效果是"叠加"在单元格属性之上的，一旦你又在单元格上设了填充，谁覆盖谁要看具体实现；用户想改一个格子的颜色时，改完发现整张表的条纹效果没了，体验很糟。

我的做法是把样式全部"剥"到单元格粒度：a:tblPr只保留firstRow之类的语义标记（方便用户后续在界面里一键切换），实际的颜色全部通过每个a:tcPr的<a:solidFill>写死。隔行变色的效果由执行器根据行号自行计算：奇数行用一种底纹，偶数行用另一种，首行单独用强调色。

这样做出来的文件，每个格子的外观都是自洽的，用户随便改哪一格都不影响其他格。代价是文件体积大一点，但表格通常没多少格子，这点体积无所谓。

填充的写法要按 schema 来，a:tcPr里的填充元素必须在所有边框元素之后：

<a:tcPr anchor="ctr" marL="91440" marR="91440" marT="45720" marB="45720"> <a:lnL w="6350"><a:solidFill><a:srgbClr val="D9D9D9"/></a:solidFill></a:lnL> <a:lnR w="6350"><a:solidFill><a:srgbClr val="D9D9D9"/></a:solidFill></a:lnR> <a:lnT w="6350"><a:solidFill><a:srgbClr val="D9D9D9"/></a:solidFill></a:lnT> <a:lnB w="6350"><a:solidFill><a:srgbClr val="D9D9D9"/></a:solidFill></a:lnB> <a:solidFill><a:srgbClr val="F2F2F2"/></a:solidFill> </a:tcPr>

注意w="6350"就是 0.5 磅（6350 / 12700 = 0.5）。细线用 6350，常规线用 12700，粗线用 25400，这套数值记住能省不少来回试的时间。

3.3 字体落点：rPr、defRPr、lstStyle 三选一的判断标准

文字属性可以写在三个地方，作用范围从大到小：

• a:lstStyle里的a:lvl1pPr/a:defRPr：作用于整个文本框或单元格内所有段落的默认样式；
• a:pPr里的a:defRPr：作用于该段落，但只对没有显式rPr的 run 生效；
• a:r里的a:rPr：作用于该 run，优先级最高。

判断标准很简单：只要内容是可以精确控制的，就全部写在a:rPr上。原因还是覆盖关系——写在 lstStyle 里的样式，会被段落级覆盖，段落级又会被 run 级覆盖，一旦三层都有值，调试时根本分不清最终生效的是哪一层。全写 run 级虽然啰嗦，但所见即所得。

有一个必须写的属性：lang。中文内容要写lang="zh-CN"，不写的话，某些引擎会按默认语言选字体，中文可能落到一个不含中文字形的字体上，显示成方框。这个坑很隐蔽，因为大部分环境下系统会自动回退到中文字体，只有在特定配置的机器上才暴露。

字号用sz，单位是百分之一磅，14 磅写sz="1400"。这个单位很容易漏掉那个 00，写成sz="14"就是 0.14 磅，字小到看不见。

还有一个小细节：每个段落的末尾建议补一个<a:endParaRPr lang="zh-CN" sz="1400"/>。它不承载内容，但决定了空行的高度和光标停留时的样式。不写的话，用户点进单元格按回车新增一行，新行的字号会跳回默认值。

3.4 内边距与垂直锚点：行高被悄悄撑开的那 4 个属性

a:tcPr上有四个内边距属性：marL、marR、marT、marB，再加上anchor（垂直对齐，取值t/ctr/b）和anchorCtr（是否水平居中整个文本块）。这几个属性是"行高比预期高"的头号嫌疑人。

默认值大概是：左右各 0.1 英寸（91440 EMU），上下各 0.05 英寸（45720 EMU）。也就是说，即使单元格里一个字都没有，行高也已经吃掉了约 0.1 英寸的垂直空间。如果你的行高算出来是 0.25 英寸，减去上下边距只剩 0.15 英寸，勉强放得下 10 磅字；换成 14 磅字，行高就会被撑到 0.3 英寸以上。

所以行高求解必须把边距算进去，公式是：

最小行高 = 行数 × 字号磅值 × 行距系数 × 12700 + marT + marB + 边框宽度

行距系数经验值取 1.2（单倍行距的实际渲染高度通常略大于字号本身，因为包含字体 ascent 和 descent）。14 磅单行、默认边距、0.5 磅边框的情况下，算出来大约是 14 × 1.2 × 12700 + 45720 × 2 + 12700 ≈ 317500 EMU，约 0.347 英寸。而 PowerPoint 里新建表格的默认行高是 370840 EMU，比这个值大一些——说明官方留了冗余。我在实现里把系数放大到 1.28，让生成的行高更接近默认手感，效果比精确计算更讨喜。

如果确实想让表格紧凑，可以把marT和marB降到 22860 EMU（0.025 英寸）。但不要设成 0，边距为 0 时文字会贴着边框线，视觉上非常挤，而且某些引擎在边距为 0 时对首行文字的裁剪会有 bug。

4. 尺寸求解：表格总宽、行高与溢出之间的三方博弈

到这一章，结构写对了，属性也写对了，剩下的就是最难量化的部分：宽度给多少、行高给多少、内容放不下怎么办。这三个问题互相牵制——放宽了表格超出版面，压窄了文字换行变多行高被撑高，缩字号又影响可读性。没有完美解，只有取舍。

4.1 文本测宽的近似模型

要算列宽，先得知道一段文字大概有多宽。精确做法是加载字体文件读字形度量表，但那样需要把字体文件打进产物，不现实。所以我用的是近似模型，实测误差在可接受范围内。

模型的基本假设是：一个字符的宽度约等于它的 em 尺寸乘以一个系数。中文汉字、全角标点系数取 1.0；拉丁字母小写平均取 0.52；大写取 0.68；数字取 0.55；空格取 0.28；半角标点取 0.3。混合文本按字符类别加权求和：

文本宽度(EMU) = Σ(字符类别系数) × 字号磅值 × 12700 × 安全系数

安全系数取 1.08，用来吃掉字体差异和字距微调带来的误差。经验上，思源黑体、苹方这类无衬线中文字体的汉字宽度确实接近 1 em，而某些偏窄的字体（比如部分压缩字型）实际宽度只有 0.9 em，安全系数能覆盖这个区间。

有几个特例要单独处理：连续的数字和字母不会被断行，所以一段ABCDEFG应该按整体宽度算，不能按单个字符累加后再允许拆分；URL、文件名、代码片段这类"不可断词"，必须保证所在列至少能容下它，否则会出现一个字被挤到下一行的尴尬画面。

还有一点容易被忽略：中英文混排时的自动断行规则。中文可以在任意字符间断行，英文只能在空格和连字符后断行，数字通常不断行。求解列宽时如果按"最长不可断单元"来算，能得到视觉上最舒服的结果，代价是列可能偏宽。这个取舍在窄表格上要反过来——宁可让英文单词被硬断，也要保证整体不超宽。

4.2 行高两段式求解

行高不能一次性算完，要分两段。

第一段算"内容高度"：对单元格里的文本，按最终确定的列宽做一次模拟换行，数出实际行数，再乘以"字号 × 行距系数"。

第二段算"几何高度"：内容高度加上下边距加边框宽度，得到该单元格需要的行高。

一行里所有单元格的需求高度可能不一样（有的换了两行，有的一行），取最大值作为这一行的h。这是必须的，因为行高是行级属性，不能一格一格设。

这里有个反直觉的点：如果你的表格里有合并单元格（rowSpan > 1），那一行的行高不能简单按本行内容算，还要考虑合并区域跨了几行、总高度够不够。我的处理方式是先把所有非合并行的需求高度算出来，再检查每个跨行合并区域，如果它跨越的若干行高度之和小于该区域内容需要的高度，就按比例把这部分差额分摊到这几行上。分摊时优先加在内容行数最少的行上，视觉上更均衡。

4.3 超宽表格的三种收敛策略

版面宽度是硬约束，表格内容宽度是软约束。当两者冲突时，有三种处理方式，各有适用场景。

策略一：等比压缩列宽。按当前列宽比例整体缩放，让总宽等于可用宽度。优点是实现简单，表格比例不变形；缺点是文字全部换行，行高飙升，原本一页能放下的表变成两页。适合内容本来就不多的场景。

策略二：按内容弹性压缩。先算出每列的"最小可接受宽度"（最长不可断单元的宽度加边距），把总宽减去这些最小宽度之和，剩下的空间按"理想宽度减最小宽度"的比例分配。这样宽列被压得多，窄列基本不动，视觉上更自然。这是我最常用的策略。

策略三：降字号 + 换布局。当前两种都压不下去（比如列数太多，每列最小宽度加起来就超了），只能降字号。经验值是每次降 1 磅，降到 9 磅为止——再小就不可读了。如果 9 磅还超宽，说明这张表根本不该按表格呈现，应该在上游就换成别的形式，比如拆成两张表、或者改成条目式列表。

我在执行器里把三种策略串成一条链：先试策略二，失败试策略一（允许行高增加），再失败走策略三，最后兜底抛一个"表格超宽"的警告，让上游决定要不要拦截。这个顺序不能反，因为降字号是不可逆的视觉损失，能不动就不动。

顺便提一个实操经验：表格总宽最好不要顶满版面宽度。留 5% 左右的右侧余量，视觉上更透气，而且用户后续想加一列时也有空间。我在默认配置里把可用宽度设成版面宽度的 95%，改起来只是一个常量。

5. 校验与回归：怎么证明产物是"原生表格"而不是一堆文本框

生成完不代表结束。表格这个对象有个特殊性：它有很多种"看起来差不多但本质不同"的实现方式。写字框拼出来的、写图片贴上去的、写 HTML 转过来的，在截图里可能一模一样，但用户一编辑就原形毕露。所以必须有一套校验机制，确认产出的是真正的 a:tbl。

5.1 结构自检的六条硬指标

每次生成后，执行器会跑一遍自检，六条全过才算成功：

第六条是我后来加的。最初生成的表格里，纯空白单元格的a:txBody里一个段落都没有，文件能打开、显示也正常，但用户点进那个格子想打字时，光标不出现，要先点一下别的地方再点回来才行。补一个空段落就解决了。

自检失败时不要直接写文件，而是把失败项和上下文打到日志里。这类问题如果等到用户打开文件才发现，排查成本要高一个数量级。

5.2 跨引擎渲染差异的兜底写法

同一个 PPTX 文件，在不同的渲染引擎里打开，表格的显示可能有细微差异。这不是 bug，是规范里留了实现空间。我遇到过几类典型差异：

行高表现不一致。有的引擎严格按h作为最小高度，内容超了才撑；有的引擎会额外加一点点余量。应对办法是把h算得比理论值大 3% 到 5%，让各家都在这个区间内，不会出现某一家行高明显偏小导致文字贴边。

边框绘制顺序不一致。相邻单元格颜色不同时，最终颜色可能不同。应对办法就是前面说的归属约定，每条物理边只声明一次，从根本上消除歧义。

默认字体回退不一致。单元格没指定字体时，各家用的默认字体不同，中文可能在衬线体和无衬线体之间跳。应对办法是每个a:rPr都显式写latin、ea、cs三个字体属性，不给回退留空间。

空段落高度不一致。完全空的段落，有的引擎给 0 高度，有的给一个字号高度。应对办法是给endParaRPr写上明确的字号。

这四条兜底做完之后，同一份文件在主流引擎里的显示差异基本控制在 1 到 2 像素内，肉眼看不出来。

5.3 一套最小可用的回归用例

回归用例不用多，覆盖边界就够。我维护的是一份十来条的清单，每次改动执行器都跑一遍：

1. 单格表格（1×1），验证最小结构；
2. 单行多列（1×8），验证列宽分配与总宽约束；
3. 多行单列（8×1），验证行高累加；
4. 2×2 全合并，只有锚点有内容；
5. L 形合并（一个 2×2 锚点 + 一个 1×2 横向合并），验证不同形状混合；
6. 超长中文不分词，验证换行与行高撑开；
7. 超长英文单词，验证不可断词处理；
8. 全空表格，验证占位与空段落；
9. 极端列数（20 列），验证收敛策略降级；
10. 表格跨版面边界，验证宽度约束触发。

每一条都配上"期望的a:tc数量"和"期望的h总值"两个数值断言，再加上一次人工目视。数值断言能拦住 90% 的结构性回归，剩下 10% 靠看图。

有一点要提醒：回归用例里一定要有"含合并 + 含边框覆盖"的组合场景。因为合并和边框这两块逻辑耦合最紧——合并区域的内部边要消掉、外轮廓边要保留，很多 bug 只在这个组合下暴露。

我自己在这套东西上折腾最久的地方，其实不是 XML 怎么写，而是"什么时候该停"。第一版我试图把每一处尺寸都算得精确无误，结果生成出来的表格反而死板——行高卡得太紧，用户想加一行注释就没地方；列宽算得太准，用户改个数字就被截断。后来把所有的尺寸计算统一乘了一个宽松系数，留足余量，文件看着舒服了，用户改起来也顺手。

第二个体会是关于校验的。一开始我觉得自检是浪费时间，生成完直接写文件多快。直到有一次批量生成两百页，其中一页的合并单元格算错了一格，导致整页排版错乱，而我是在用户反馈里才知道的。从那以后自检就成了硬性流程，宁可慢几十毫秒，也不让有问题的文件流出去。

最后分享一个调试小技巧：如果怀疑某个表格的结构有问题，把 PPTX 后缀改成 zip 解压，进ppt/slides/目录找到对应的 XML，用任意格式化工具展开，重点看a:tblGrid里gridCol的数量和a:tr里a:tc的数量对不对得上。这两个数字一对不上，问题基本就锁定在合并展开那一步了。这个方法比反复生成、反复打开快得多。