Table Properties

Alignment

Word allows a table to be aligned between the page margins either left, right, or center.

The read/write Table.alignment property specifies the alignment for a table:

>>> table = document.add_table(rows=2, cols=2)
>>> table.alignment
None
>>> table.alignment = WD_TABLE_ALIGNMENT.RIGHT
>>> table.alignment
RIGHT (2)

Autofit

Word has two algorithms for laying out a table, fixed-width or autofit. The default is autofit. Word will adjust column widths in an autofit table based on cell contents. A fixed-width table retains its column widths regardless of the contents. Either algorithm will adjust column widths proportionately when total table width exceeds page width.

The read/write Table.allow_autofit property specifies which algorithm is used:

>>> table = document.add_table(rows=2, cols=2)
>>> table.allow_autofit
True
>>> table.allow_autofit = False
>>> table.allow_autofit
False

Specimen XML

The following XML represents a 2x2 table:

<w:tbl>
  <w:tblPr>
    <w:tblStyle w:val="TableGrid"/>
    <w:tblW w:type="auto" w:w="0"/>
    <w:jc w:val="right"/>
    <w:tblLook w:firstColumn="1" w:firstRow="1" w:lastColumn="0"
               w:lastRow="0" w:noHBand="0" w:noVBand="1" w:val="04A0"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="4788"/>
    <w:gridCol w:w="4788"/>
  </w:tblGrid>
  <w:tr>
    <w:tc/>
      <w:tcPr>
        <w:tcW w:type="dxa" w:w="4788"/>
      </w:tcPr>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:tcPr>
        <w:tcW w:type="dxa" w:w="4788"/>
      </w:tcPr>
      <w:p/>
    </w:tc>
  </w:tr>
  <w:tr>
    <w:tc>
      <w:tcPr>
        <w:tcW w:type="dxa" w:w="4788"/>
      </w:tcPr>
      <w:p/>
    </w:tc>
    <w:tc>
      <w:tcPr>
        <w:tcW w:type="dxa" w:w="4788"/>
      </w:tcPr>
      <w:p/>
    </w:tc>
  </w:tr>
</w:tbl>

Layout behavior

Auto-layout causes actual column widths to be both unpredictable and unstable. Changes to the content can make the table layout shift.

Semantics of CT_TblWidth element

e.g. tcW:

<w:tcW w:w="42.4mm"/>

<w:tcW w:w="1800" w:type="dxa"/>

<w:tcW w:w="20%" w:type="pct"/>

<w:tcW w:w="0" w:type="auto"/>

<w:tcW w:type="nil"/>


ST_MeasurementOrPercent
|
+-- ST_DecimalNumberOrPercent
|   |
|   +-- ST_UnqualifiedPercentage
|   |   |
|   |   +-- XsdInteger e.g. '1440'
|   |
|   +-- ST_Percentage e.g. '-07.43%'
|
+-- ST_UniversalMeasure  e.g. '-04.34mm'

Schema Definitions

<xsd:complexType name="CT_Tbl">  <!-- denormalized -->
  <xsd:sequence>
    <xsd:group    ref="EG_RangeMarkupElements"        minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="tblPr"       type="CT_TblPr"/>
    <xsd:element name="tblGrid"     type="CT_TblGrid"/>
    <xsd:choice                                       minOccurs="0" maxOccurs="unbounded">
      <xsd:element name="tr"        type="CT_Row"/>
      <xsd:element name="customXml" type="CT_CustomXmlRow"/>
      <xsd:element name="sdt"       type="CT_SdtRow"/>
      <xsd:group    ref="EG_RunLevelElts"             minOccurs="0" maxOccurs="unbounded"/>
    </xsd:choice>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CT_TblPr">  <!-- denormalized -->
  <xsd:sequence>
    <xsd:element name="tblStyle"            type="CT_String"        minOccurs="0"/>
    <xsd:element name="tblpPr"              type="CT_TblPPr"        minOccurs="0"/>
    <xsd:element name="tblOverlap"          type="CT_TblOverlap"    minOccurs="0"/>
    <xsd:element name="bidiVisual"          type="CT_OnOff"         minOccurs="0"/>
    <xsd:element name="tblStyleRowBandSize" type="CT_DecimalNumber" minOccurs="0"/>
    <xsd:element name="tblStyleColBandSize" type="CT_DecimalNumber" minOccurs="0"/>
    <xsd:element name="tblW"                type="CT_TblWidth"      minOccurs="0"/>
    <xsd:element name="jc"                  type="CT_JcTable"       minOccurs="0"/>
    <xsd:element name="tblCellSpacing"      type="CT_TblWidth"      minOccurs="0"/>
    <xsd:element name="tblInd"              type="CT_TblWidth"      minOccurs="0"/>
    <xsd:element name="tblBorders"          type="CT_TblBorders"    minOccurs="0"/>
    <xsd:element name="shd"                 type="CT_Shd"           minOccurs="0"/>
    <xsd:element name="tblLayout"           type="CT_TblLayoutType" minOccurs="0"/>
    <xsd:element name="tblCellMar"          type="CT_TblCellMar"    minOccurs="0"/>
    <xsd:element name="tblLook"             type="CT_TblLook"       minOccurs="0"/>
    <xsd:element name="tblCaption"          type="CT_String"        minOccurs="0"/>
    <xsd:element name="tblDescription"      type="CT_String"        minOccurs="0"/>
    <xsd:element name="tblPrChange"         type="CT_TblPrChange"   minOccurs="0"/>
  </xsd:sequence>

<!-- table alignment --------------------------------- -->

<xsd:complexType name="CT_JcTable">
  <xsd:attribute name="val" type="ST_JcTable" use="required"/>
</xsd:complexType>

<xsd:simpleType name="ST_JcTable">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="center"/>
    <xsd:enumeration value="end"/>
    <xsd:enumeration value="left"/>
    <xsd:enumeration value="right"/>
    <xsd:enumeration value="start"/>
  </xsd:restriction>
</xsd:simpleType>

<!-- table width ------------------------------------- -->

<xsd:complexType name="CT_TblWidth">
  <xsd:attribute name="w"    type="ST_MeasurementOrPercent"/>
  <xsd:attribute name="type" type="ST_TblWidth"/>
</xsd:complexType>

<xsd:simpleType name="ST_MeasurementOrPercent">
  <xsd:union memberTypes="ST_DecimalNumberOrPercent s:ST_UniversalMeasure"/>
</xsd:simpleType>

<xsd:simpleType name="ST_DecimalNumberOrPercent">
  <xsd:union memberTypes="ST_UnqualifiedPercentage s:ST_Percentage"/>
</xsd:simpleType>

<xsd:simpleType name="ST_UniversalMeasure">
  <xsd:restriction base="xsd:string">
    <xsd:pattern value="-?[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_UnqualifiedPercentage">
  <xsd:restriction base="xsd:integer"/>
</xsd:simpleType>

<xsd:simpleType name="ST_Percentage">
  <xsd:restriction base="xsd:string">
    <xsd:pattern value="-?[0-9]+(\.[0-9]+)?%"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="ST_TblWidth">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="nil"/>
    <xsd:enumeration value="pct"/>
    <xsd:enumeration value="dxa"/>
    <xsd:enumeration value="auto"/>
  </xsd:restriction>
</xsd:simpleType>

<!-- table layout ------------------------------------ -->

<xsd:complexType name="CT_TblLayoutType">
  <xsd:attribute name="type" type="ST_TblLayoutType"/>
</xsd:complexType>

<xsd:simpleType name="ST_TblLayoutType">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="fixed"/>
    <xsd:enumeration value="autofit"/>
  </xsd:restriction>
</xsd:simpleType>

<!-- table look -------------------------------------- -->

<xsd:complexType name="CT_TblLook">
  <xsd:attribute name="firstRow"    type="s:ST_OnOff"/>
  <xsd:attribute name="lastRow"     type="s:ST_OnOff"/>
  <xsd:attribute name="firstColumn" type="s:ST_OnOff"/>
  <xsd:attribute name="lastColumn"  type="s:ST_OnOff"/>
  <xsd:attribute name="noHBand"     type="s:ST_OnOff"/>
  <xsd:attribute name="noVBand"     type="s:ST_OnOff"/>
  <xsd:attribute name="val"         type="ST_ShortHexNumber"/>
</xsd:complexType>