Word allows contiguous table cells to be merged, such that two or more cells appear to be a single cell. Cells can be merged horizontally (spanning multple columns) or vertically (spanning multiple rows). Cells can also be merged both horizontally and vertically at the same time, producing a cell that spans both rows and columns. Only rectangular ranges of cells can be merged.
Diagrams like the one below are used to depict tables in this analysis. Horizontal spans are depicted as a continuous horizontal cell without vertical dividers within the span. Vertical spans are depicted as a vertical sequence of cells of the same width where continuation cells are separated by a dashed top border and contain a caret (‘^’) to symbolize the continuation of the cell above. Cell ‘addresses’ are depicted at the column and row grid lines. This is conceptually convenient as it reuses the notion of list indices (and slices) and makes certain operations more intuitive to specify. The merged cell A below has top, left, bottom, and right values of 0, 0, 2, and 2 respectively:
\ 0 1 2 3
0 +---+---+---+
| A | |
1 + - - - +---+
| ^ | |
2 +---+---+---+
| | | |
3 +---+---+---+
There are three ways to access a table cell:
Accessing the middle cell of a 3 x 3 table:
>>> table = document.add_table(3, 3)
>>> middle_cell = table.cell(1, 1)
>>> table.rows[1].cells[1] == middle_cell
True
>>> table.columns[1].cells[1] == middle_cell
True
A merge is specified using two diagonal cells:
>>> table = document.add_table(3, 3)
>>> a = table.cell(0, 0)
>>> b = table.cell(1, 1)
>>> A = a.merge(b)
\ 0 1 2 3
0 +---+---+---+ +---+---+---+
| a | | | | A | |
1 +---+---+---+ + - - - +---+
| | b | | --> | ^ | |
2 +---+---+---+ +---+---+---+
| | | | | | | |
3 +---+---+---+ +---+---+---+
A cell is accessed by its “layout grid” position regardless of any spans that may be present. A grid address that falls in a span returns the top-leftmost cell in that span. This means a span has as many addresses as layout grid cells it spans. For example, the merged cell A above can be addressed as (0, 0), (0, 1), (1, 0), or (1, 1). This addressing scheme leads to desirable access behaviors when spans are present in the table.
The length of Row.cells is always equal to the number of grid columns, regardless of any spans that are present. Likewise, the length of Column.cells is always equal to the number of table rows, regardless of any spans.
>>> table = document.add_table(2, 3)
>>> row = table.rows[0]
>>> len(row.cells)
3
>>> row.cells[0] == row.cells[1]
False
>>> a, b = row.cells[:2]
>>> a.merge(b)
>>> len(row.cells)
3
>>> row.cells[0] == row.cells[1]
True
\ 0 1 2 3
0 +---+---+---+ +---+---+---+
| a | b | | | A | |
1 +---+---+---+ --> +---+---+---+
| | | | | | | |
2 +---+---+---+ +---+---+---+
When two or more cells are merged, any existing content is concatenated and placed in the resulting merged cell. Content from each original cell is separated from that in the prior original cell by a paragraph mark. An original cell having no content is skipped in the contatenation process. In Python, the procedure would look roughly like this:
merged_cell_text = '\n'.join(
cell.text for cell in original_cells if cell.text
)
Merging four cells with content 'a', 'b', '', and 'd' respectively results in a merged cell having text 'a\nb\nd'.
Cell width and height, if present, are added when cells are merged:
>>> a, b = row.cells[:2]
>>> a.width.inches, b.width.inches
(1.0, 1.0)
>>> A = a.merge(b)
>>> A.width.inches
2.0
Collapsing a column. When all cells in a grid column share the same w:gridSpan specification, the spanned columns can be collapsed into a single column by removing the w:gridSpan attributes.
A key insight is that merged cells always look like the diagram below. Horizontal spans are accomplished with a single w:tc element in each row, using the gridSpan attribute to span additional grid columns. Vertical spans are accomplished with an identical cell in each continuation row, having the same gridSpan value, and having vMerge set to continue (the default). These vertical continuation cells are depicted in the diagrams below with a dashed top border and a caret (‘^’) in the left-most grid column to symbolize the continuation of the cell above.:
\ 0 1 2 3
0 +---+---+---+
| A | |
1 + - - - +---+
| ^ | |
2 +---+---+---+
| | | |
3 +---+---+---+
The table depicted above corresponds to this XML (minimized for clarity):
<w:tbl>
<w:tblGrid>
<w:gridCol/>
<w:gridCol/>
<w:gridCol/>
</w:tblGrid>
<w:tr>
<w:tc>
<w:tcPr>
<w:gridSpan w:val="2"/>
<w:vMerge w:val="restart"/>
</w:tcPr>
</w:tc>
<w:tc/>
</w:tr>
<w:tr>
<w:tc>
<w:tcPr>
<w:gridSpan w:val="2"/>
<w:vMerge/>
</w:tcPr>
</w:tc>
<w:tc/>
</w:tr>
<w:tr>
<w:tc/>
<w:tc/>
<w:tc/>
</w:tr>
</w:tbl>
In a horizontal merge, the <w:tc w:gridSpan="?"> attribute indicates the number of columns the cell should span. Only the leftmost cell is preserved; the remaining cells in the merge are deleted.
For merging vertically, the w:vMerge table cell property of the uppermost cell of the column is set to the value “restart” of type w:ST_Merge. The following, lower cells included in the vertical merge must have the w:vMerge element present in their cell property (w:TcPr) element. Its value should be set to “continue”, although it is not necessary to explicitely define it, as it is the default value. A vertical merge ends as soon as a cell w:TcPr element lacks the w:vMerge element. Similarly to the w:gridSpan element, the w:vMerge elements are only required when the table’s layout is not uniform across its different columns. In the case it is, only the topmost cell is kept; the other lower cells in the merged area are deleted along with their w:vMerge elements and the w:trHeight table row property is used to specify the combined height of the merged cells.
Each Row and Column object provides access to the collection of cells it contains. The length of these cell collections is unaffected by the presence of merged cells.
len() always bases its count on the layout grid, as though there were no merged cells.
One or both of the “diagonal corner” cells in a merge operation may itself be a merged cell, as long as the specified region is rectangular.
For example:
\ 0 1 2 3
+---+---+---+---+ +---+---+---+---+
0 | a | b | | | a\nb\nC | |
+ - - - +---+---+ + - - - - - +---+
1 | ^ | C | | | ^ | |
+---+---+---+---+ --> +---+---+---+---+
2 | | | | | | | | | |
+---+---+---+---+ +---+---+---+---+
3 | | | | | | | | | |
+---+---+---+---+ +---+---+---+---+
cell(0, 0).merge(cell(1, 2))
or:
0 1 2 3 4
+---+---+---+---+---+ +---+---+---+---+---+
0 | a | b | c | | | abcD | |
+ - - - +---+---+---+ + - - - - - - - +---+
1 | ^ | D | | | ^ | |
+---+---+---+---+---+ --> +---+---+---+---+---+
2 | | | | | | | | | | | |
+---+ - - - +---+---+ +---+---+---+---+---+
3 | | | | | | | | | | | |
+---+---+---+---+---+ +---+---+---+---+---+
cell(0, 0).merge(cell(1, 2))
Conversely, either of these two merge operations would be illegal:
\ 0 1 2 3 4 0 1 2 3 4
0 +---+---+---+---+ 0 +---+---+---+---+
| | | b | | | | | | |
1 +---+---+ - +---+ 1 +---+---+---+---+
| | a | ^ | | | | a | | |
2 +---+---+ - +---+ 2 +---+---+---+---+
| | | ^ | | | b | |
3 +---+---+---+---+ 3 +---+---+---+---+
| | | | | | | | | |
4 +---+---+---+---+ 4 +---+---+---+---+
a.merge(b)
A 3 x 3 table where an area defined by the 2 x 2 topleft cells has been merged, demonstrating the combined use of the w:gridSpan as well as the w:vMerge elements, as produced by Word:
<w:tbl>
<w:tblPr>
<w:tblW w:w="0" w:type="auto" />
</w:tblPr>
<w:tblGrid>
<w:gridCol w:w="3192" />
<w:gridCol w:w="3192" />
<w:gridCol w:w="3192" />
</w:tblGrid>
<w:tr>
<w:tc>
<w:tcPr>
<w:tcW w:w="6384" w:type="dxa" />
<w:gridSpan w:val="2" />
<w:vMerge w:val="restart" />
</w:tcPr>
</w:tc>
<w:tc>
<w:tcPr>
<w:tcW w:w="3192" w:type="dxa" />
</w:tcPr>
</w:tc>
</w:tr>
<w:tr>
<w:tc>
<w:tcPr>
<w:tcW w:w="6384" w:type="dxa" />
<w:gridSpan w:val="2" />
<w:vMerge />
</w:tcPr>
</w:tc>
<w:tc>
<w:tcPr>
<w:tcW w:w="3192" w:type="dxa" />
</w:tcPr>
</w:tc>
</w:tr>
<w:tr>
<w:tc>
<w:tcPr>
<w:tcW w:w="3192" w:type="dxa" />
</w:tcPr>
</w:tc>
<w:tc>
<w:tcPr>
<w:tcW w:w="3192" w:type="dxa" />
</w:tcPr>
</w:tc>
<w:tc>
<w:tcPr>
<w:tcW w:w="3192" w:type="dxa" />
</w:tcPr>
</w:tc>
</w:tr>
</w:tbl>
<xsd:complexType name="CT_Tc"> <!-- denormalized -->
<xsd:sequence>
<xsd:element name="tcPr" type="CT_TcPr" minOccurs="0"/>
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element name="p" type="CT_P"/>
<xsd:element name="tbl" type="CT_Tbl"/>
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
<xsd:element name="sdt" type="CT_SdtBlock"/>
<xsd:element name="proofErr" type="CT_ProofErr"/>
<xsd:element name="permStart" type="CT_PermStart"/>
<xsd:element name="permEnd" type="CT_Perm"/>
<xsd:element name="ins" type="CT_RunTrackChange"/>
<xsd:element name="del" type="CT_RunTrackChange"/>
<xsd:element name="moveFrom" type="CT_RunTrackChange"/>
<xsd:element name="moveTo" type="CT_RunTrackChange"/>
<xsd:element ref="m:oMathPara" type="CT_OMathPara"/>
<xsd:element ref="m:oMath" type="CT_OMath"/>
<xsd:element name="bookmarkStart" type="CT_Bookmark"/>
<xsd:element name="bookmarkEnd" type="CT_MarkupRange"/>
<xsd:element name="moveFromRangeStart" type="CT_MoveBookmark"/>
<xsd:element name="moveFromRangeEnd" type="CT_MarkupRange"/>
<xsd:element name="moveToRangeStart" type="CT_MoveBookmark"/>
<xsd:element name="moveToRangeEnd" type="CT_MarkupRange"/>
<xsd:element name="commentRangeStart" type="CT_MarkupRange"/>
<xsd:element name="commentRangeEnd" type="CT_MarkupRange"/>
<xsd:element name="customXmlInsRangeStart" type="CT_TrackChange"/>
<xsd:element name="customXmlInsRangeEnd" type="CT_Markup"/>
<xsd:element name="customXmlDelRangeStart" type="CT_TrackChange"/>
<xsd:element name="customXmlDelRangeEnd" type="CT_Markup"/>
<xsd:element name="customXmlMoveFromRangeStart" type="CT_TrackChange"/>
<xsd:element name="customXmlMoveFromRangeEnd" type="CT_Markup"/>
<xsd:element name="customXmlMoveToRangeStart" type="CT_TrackChange"/>
<xsd:element name="customXmlMoveToRangeEnd" type="CT_Markup"/>
<xsd:element name="altChunk" type="CT_AltChunk"/>
</xsd:choice>
</xsd:sequence>
<xsd:attribute name="id" type="s:ST_String" use="optional"/>
</xsd:complexType>
<xsd:complexType name="CT_TcPr"> <!-- denormalized -->
<xsd:sequence>
<xsd:element name="cnfStyle" type="CT_Cnf" minOccurs="0"/>
<xsd:element name="tcW" type="CT_TblWidth" minOccurs="0"/>
<xsd:element name="gridSpan" type="CT_DecimalNumber" minOccurs="0"/>
<xsd:element name="hMerge" type="CT_HMerge" minOccurs="0"/>
<xsd:element name="vMerge" type="CT_VMerge" minOccurs="0"/>
<xsd:element name="tcBorders" type="CT_TcBorders" minOccurs="0"/>
<xsd:element name="shd" type="CT_Shd" minOccurs="0"/>
<xsd:element name="noWrap" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="tcMar" type="CT_TcMar" minOccurs="0"/>
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
<xsd:element name="tcFitText" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="vAlign" type="CT_VerticalJc" minOccurs="0"/>
<xsd:element name="hideMark" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="headers" type="CT_Headers" minOccurs="0"/>
<xsd:choice minOccurs="0">
<xsd:element name="cellIns" type="CT_TrackChange"/>
<xsd:element name="cellDel" type="CT_TrackChange"/>
<xsd:element name="cellMerge" type="CT_CellMergeTrackChange"/>
</xsd:choice>
<xsd:element name="tcPrChange" type="CT_TcPrChange" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CT_DecimalNumber">
<xsd:attribute name="val" type="ST_DecimalNumber" use="required"/>
</xsd:complexType>
<xsd:simpleType name="ST_DecimalNumber">
<xsd:restriction base="xsd:integer"/>
</xsd:simpleType>
<xsd:complexType name="CT_VMerge">
<xsd:attribute name="val" type="ST_Merge"/>
</xsd:complexType>
<xsd:complexType name="CT_HMerge">
<xsd:attribute name="val" type="ST_Merge"/>
</xsd:complexType>
<xsd:simpleType name="ST_Merge">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="continue"/>
<xsd:enumeration value="restart"/>
</xsd:restriction>
</xsd:simpleType>