Table Rows and Cells

A table row is defined using a <tr> element, which is analogous to the HTML <tr> tag. The <tr> element acts as a container for a row of cells with the table’s content.

A <tr> element has one formatting child element, <trPr>, which defines the row properties (such as the row’s width) and whether it can split across a page. Each property is defined by an individual child element under the <trPr> element. The complete set of table row properties can be found on the definition for the <trPr> element. As well, a table row can contain two types of content: custom markup (custom XML or structured document tags), and table cells.

The cells in a row contain the table’s content and are defined by <tc> elements, which are analogous to HTML <td> tags.

A <tc> element has one formatting child element, <tcPr>, which defines the properties for the cell. Each unique property is specified by a child element of this element. The complete set of table cell properties can be found on the definition for the <tcPr> element. As well, a table cell can contain any valid block-level content, which allows for the nesting of paragraphs and tables within table cells.

In the example below, the <tcW> element defines the width of the cell, where the attribute @w is the value in twips. Here the width of the cell is 8,856 units, where units are defined by the attribute type. In this case, dxa represents twips.

<w:tr>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="8856" w:type="dxa"/>
    </w:tcPr>
    <w:p/>
  </w:tc>
</w:tr>

The <tc> element contains the cell's content, which, in this case, is an empty <p> element.

Consider a table having one cell, which contains the text “Hello, world”:

This table's content is represented by the following XML:

<w:tr>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="1770" w:type="dxa"/>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:t>Hello, World</w:t>
      </w:r>
    </w:p>
  </w:tc>
</w:tr>

At both the row and cell levels, the properties must also specify how the rows and cells will be placed on the table grid.

The <trPr> element contains information about the number of grid units which should be omitted ('skipped') before and after the row is complete using the <gridBefore> and <gridAfter> elements, allowing rows to start at different columns on the grid, as well as a preferred width for that leading/trailing space using the <wBefore> and <wAfter> elements. The <tcPr> element also contains grid information pertaining to how many grids a cell spans using the <gridSpan> element, which determines how many grid units are consumed by the current cell, as well as a preferred width for that cell using the <tcW> element.

In the earlier complex table having two rows of two differently sized cells, a consumer shall represent that table containing three grid columns (one per distinct vertical line). Consider the following XML for the first row of that table:

<w:tr>
  …
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="5145" w:type="dxa" />
      <w:gridSpan w:val="2" />
    </w:tcPr>
    <w:p />
  </w:tc>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="2145" w:type="dxa" />
    </w:tcPr>
    <w:p/>
  </w:tc>
</w:tr>

Again, the <gridSpan> element is the number of grid columns that cell spans when being laid out on the table grid. In this example, the first cell of the first row contains two grid columns. As well, the cell specifies its preferred width using the <tcW> element, which tells the consumer the width desired by that cell at layout time.

It is important to note that every width in a table is a preferred width - because the table must satisfy the grid at all times, conflicting table properties must be resolved by overriding preferred widths in a specific manner, shown below.