在使用 Aspose.Words 生成 Word 表格时，经常需要合并单元格，例如表头占满整行、某一列跨多行等。如果不了解 Aspose.Words 的合并机制，很容易出现合并逻辑错误，例如 2×2 单元格合并配置错误的情况。

本文系统讲解 Aspose.Words 合并单元格的原理、配置方式、代码示例以及常见误区，并解释水平合并与垂直合并之间的区别。

---

一、Aspose.Words 单元格合并的核心原理

在 Aspose.Words 中，单元格合并不是一个“执行合并操作”，而是通过 为每个单元格标记合并状态 来实现。

核心控制属性位于：

CellFormat.HorizontalMerge
CellFormat.VerticalMerge

分别控制：

属性	作用
HorizontalMerge	控制单元格是否参与 横向合并
VerticalMerge	控制单元格是否参与 纵向合并

两者的值来自枚举：

Aspose.Words.Tables.CellMerge

定义如下：

public enum CellMerge
{
    None = 0,
    First = 1,
    Previous = 2
}

三个值的含义：

枚举值	含义
None	单元格不参与合并
First	合并区域中的第一个单元格
Previous	与前一个单元格合并

可以把它理解为：

每个合并区域都是一条“合并链”

例如：

First -> Previous -> Previous -> Previous

表示这些单元格组成一个合并区域。

---

二、横向合并结构示意

假设有一行 4 个单元格，其中前 3 个需要合并。

字符画结构：

+-----+-----+-----+-----+
|  A  |     |     |  B  |
+-----+-----+-----+-----+

逻辑标记如下：

+-----------+-----------+-----------+-----------+
| h:first   | h:previous| h:previous| h:none    |
| v:none    | v:none    | v:none    | v:none    |
+-----------+-----------+-----------+-----------+

解释：

单元格	HorizontalMerge
A	First
第二格	Previous
第三格	Previous
B	None

---

三、纵向合并结构示意

假设第一列三行需要合并：

+-----+-----+
|  A  |  B  |
+-----+-----+
|     |  C  |
+-----+-----+
|     |  D  |
+-----+-----+

逻辑标记：

+-----------+-----------+
| v:first   | v:none    |
| h:none    | h:none    |
+-----------+-----------+
| v:previous| v:none    |
| h:none    | h:none    |
+-----------+-----------+
| v:previous| v:none    |
| h:none    | h:none    |
+-----------+-----------+

---

四、最容易犯错的 2×2 合并案例

在官方文档示例中，只给出了两种情况：

• 单行横向合并
• 单列纵向合并

但是没有提供 同时跨行跨列（例如 2×2）合并 的完整示例。这会导致很多人在第一次实现多行多列合并时，按照直觉组合这两种示例，写出类似下面的配置：

+-----------+-----------+
| v:first   | v:none    |
| h:first   | h:previous|
+-----------+-----------+
| v:previous| v:previous|
| h:none    | h:previous|
+-----------+-----------+

乍一看似乎是合理的：

• 第一行做横向合并
• 第一列做纵向合并

但实际上这是 错误的配置。

原因在于：

在 Aspose.Words 中，每一行的横向合并链、每一列的纵向合并链都必须独立重新开始。

也就是说：

• 新的一行如果继续参与纵向合并，需要重新设置 VerticalMerge
• 同一行中如果存在横向合并链，需要重新设置 HorizontalMerge

因此正确写法应该是：

+-----------+-----------+
| v:first   | v:first   |
| h:first   | h:previous|
+-----------+-----------+
| v:previous| v:previous|
| h:first   | h:previous|
+-----------+-----------+

字符结构可以理解为：

+---------+---------+
|         |         |
|    A    |         |
|         |         |
+---------+---------+
|         |         |
|         |         |
|         |         |
+---------+---------+

关键理解：

• 第一行形成一条横向合并链
• 第一列形成一条纵向合并链
• 每一行、每一列都必须显式声明自己的 First 起点

如果理解为“合并区域是由横向链和纵向链交叉组成的结构”，就不会再写错这种配置。

五、4×4 表格合并中间 2×2 单元格示例

假设有一个 4×4 表格：

+---+---+---+---+
| A | B | C | D |
+---+---+---+---+
| E | F | G | H |
+---+---+---+---+
| I | J | K | L |
+---+---+---+---+
| M | N | O | P |
+---+---+---+---+

需要合并中间 2×2 区域：

F G
J K

合并后结构：

+---+---+---+---+
| A | B | C | D |
+---+---+---+---+
| E |       | H |
+---| merged|---+
| I |       | L |
+---+-------+---+
| M | N | O | P |
+---+---+---+---+

逻辑标记如下：

+-----------+-----------+-----------+-----------+
| none none | none none | none none | none none |
+-----------+-----------+-----------+-----------+
| none none | v:f h:f   | v:f h:p   | none none |
+-----------+-----------+-----------+-----------+
| none none | v:p h:f   | v:p h:p   | none none |
+-----------+-----------+-----------+-----------+
| none none | none none | none none | none none |
+-----------+-----------+-----------+-----------+

重点四个单元格：

位置	VerticalMerge	HorizontalMerge
F	First	First
G	First	Previous
J	Previous	First
K	Previous	Previous

---

六、使用 DocumentBuilder 创建合并单元格

如果使用 DocumentBuilder 创建表格，需要在插入单元格时设置合并属性。

示例：第一行横向合并。

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertCell();
builder.CellFormat.HorizontalMerge = CellMerge.First;
builder.Write("Text in merged cells.");

builder.InsertCell();
builder.CellFormat.HorizontalMerge = CellMerge.Previous;
builder.EndRow();

builder.InsertCell();
builder.CellFormat.HorizontalMerge = CellMerge.None;
builder.Write("Text in one cell.");

builder.InsertCell();
builder.Write("Text in another cell.");

builder.EndRow();
builder.EndTable();

doc.Save("HorizontalMerge.docx");

关键步骤：

步骤	说明
InsertCell	创建单元格
HorizontalMerge = First	开始合并
HorizontalMerge = Previous	继续合并
HorizontalMerge = None	结束合并

如果忘记设置 None，后续单元格可能继续被合并。

---

七、垂直合并示例

创建一个 两行一列合并 的表格：

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertCell();
builder.CellFormat.VerticalMerge = CellMerge.First;
builder.Write("Text in merged cells.");

builder.InsertCell();
builder.CellFormat.VerticalMerge = CellMerge.None;
builder.Write("Text in one cell");
builder.EndRow();

builder.InsertCell();
builder.CellFormat.VerticalMerge = CellMerge.Previous;

builder.InsertCell();
builder.CellFormat.VerticalMerge = CellMerge.None;
builder.Write("Text in another cell");

builder.EndRow();
builder.EndTable();

doc.Save("VerticalMerge.docx");

结构：

+---------+
|  A      |
| (First) |
+---------+
|         |
|Previous |
+---------+

---

八、如何判断单元格是否已合并

如果加载一个已有 Word 文件，可以读取属性判断。

示例代码：

Document doc = new Document("Table with merged cells.docx");

Table table = (Table)doc.GetChild(NodeType.Table, 0, true);

foreach (Row row in table.Rows)
{
    foreach (Cell cell in row.Cells)
    {
        Console.WriteLine(PrintCellMergeType(cell));
    }
}

检查两个属性：

cell.CellFormat.HorizontalMerge
cell.CellFormat.VerticalMerge

返回值含义：

返回值	含义
First	合并区域起点
Previous	合并区域延续
None	未合并

---

九、在已有表格中合并单元格

如果不是使用 DocumentBuilder 创建表格，而是修改已有表格，可以写一个工具函数。

internal void MergeCells(Cell startCell, Cell endCell)
{
    Table parentTable = startCell.ParentRow.ParentTable;

    Point startCellPos = new Point(
        startCell.ParentRow.IndexOf(startCell),
        parentTable.IndexOf(startCell.ParentRow));

    Point endCellPos = new Point(
        endCell.ParentRow.IndexOf(endCell),
        parentTable.IndexOf(endCell.ParentRow));

    Rectangle mergeRange = new Rectangle(
        Math.Min(startCellPos.X, endCellPos.X),
        Math.Min(startCellPos.Y, endCellPos.Y),
        Math.Abs(endCellPos.X - startCellPos.X) + 1,
        Math.Abs(endCellPos.Y - startCellPos.Y) + 1);

    foreach (Row row in parentTable.Rows)
    {
        foreach (Cell cell in row.Cells)
        {
            Point currentPos = new Point(row.IndexOf(cell), parentTable.IndexOf(row));

            if (mergeRange.Contains(currentPos))
            {
                cell.CellFormat.HorizontalMerge =
                    currentPos.X == mergeRange.X ? CellMerge.First : CellMerge.Previous;

                cell.CellFormat.VerticalMerge =
                    currentPos.Y == mergeRange.Y ? CellMerge.First : CellMerge.Previous;
            }
        }
    }
}

调用：

Document doc = new Document("Table with merged cells.docx");

Table table = doc.FirstSection.Body.Tables[0];

Cell start = table.Rows[0].Cells[0];
Cell end = table.Rows[1].Cells[1];

MergeCells(start, end);

doc.Save("MergeCellRange.docx");

这个方法可以合并：

• 多列
• 多行
• 任意矩形区域

---

十、Word 表格与 HTML 表格结构区别

理解这个差异很重要。

Word 表格结构

Word 表格是：

Table
 ├─ Row
 │   ├─ Cell
 │   ├─ Cell
 │   └─ Cell
 └─ Row
     ├─ Cell
     └─ Cell

特点：

• 每一行 独立
• 每行单元格数量可以不同
• 列宽可以不同

例如：

第一行
| 2cm | 1cm |

第二行
| 1cm | 2cm |

---

HTML 表格结构

HTML 表格是严格网格：

+----+----+----+
|    |    |    |
+----+----+----+
|    |    |    |
+----+----+----+

HTML 使用：

rowspan
colspan

例如：

<td colspan="2">
<td rowspan="3">

---

十一、修复丢失的横向合并标记

某些 Word 版本 不会保存 HorizontalMerge 标记。

表现为：

• Word 显示已合并
• 代码读取不到合并

解决方法：

table.ConvertToHorizontallyMergedCells();

示例：

Document doc = new Document("Table with merged cells.docx");

Table table = doc.FirstSection.Body.Tables[0];

table.ConvertToHorizontallyMergedCells();

该方法会：

1. 检测单元格宽度
2. 自动补充 Merge 标记
3. 转换为标准合并结构

---

十二、HTML rowspan / colspan 转换逻辑

单行跨列

rowSpan == 1
colSpan > 1

结构：

First -> Previous -> Previous

代码：

HorizontalMerge = CellMerge.First
HorizontalMerge = CellMerge.Previous

---

单列跨行

rowSpan > 1
colSpan == 1

结构：

First
Previous
Previous

---

跨行跨列

规则：

左上角
First First

第一行
First Previous

第一列
Previous First

其他
Previous Previous

代码：

if (i == 0 && j == 0)
{
    VerticalMerge = CellMerge.First;
    HorizontalMerge = CellMerge.First;
}
else if (i == 0 && j > 0)
{
    VerticalMerge = CellMerge.First;
    HorizontalMerge = CellMerge.Previous;
}
else if (i > 0 && j == 0)
{
    VerticalMerge = CellMerge.Previous;
    HorizontalMerge = CellMerge.First;
}
else
{
    VerticalMerge = CellMerge.Previous;
    HorizontalMerge = CellMerge.Previous;
}

---

十三、常见问题

1.为什么合并一个区域后整个表都合并了？

原因：

后续单元格仍然保持

CellMerge.Previous

解决方法：

在合并区域之后设置

CellMerge.None

---

十四、总结

Aspose.Words 合并单元格的本质是：

通过标记每个单元格的合并状态来构建合并结构。

核心规则：

1. 合并区域起点必须是 First
2. 后续单元格必须是 Previous
3. 不参与合并必须是 None
4. 横向和纵向合并链需要分别维护

理解这些规则后，就可以正确构造：

• 横向合并
• 纵向合并
• 任意矩形区域合并
• HTML rowspan / colspan 转换。