表格对象

Table objects

中文

表格对象是使用 Document 上的 add_table() 方法构建的。

英文

Table objects are constructed using the add_table() method on Document.

Table 对象

Table objects

class docx.table.Table(tbl: CT_Tbl, parent: t.ProvidesStoryPart)

Proxy class for a WordprocessingML <w:tbl> element.

add_column(width: Length)

Return a _Column object of width, newly added rightmost to the table.

add_row()

Return a _Row instance, newly added bottom-most to the table.

property alignment: WD_TABLE_ALIGNMENT | None

Read/write.

A member of WD_TABLE_ALIGNMENT or None, specifying the positioning of this table between the page margins. None if no setting is specified, causing the effective value to be inherited from the style hierarchy.

property autofit: bool

True if column widths can be automatically adjusted to improve the fit of cell contents.

False if table layout is fixed. Column widths are adjusted in either case if total column width exceeds page width. Read/write boolean.

cell(row_idx: int, col_idx: int) → _Cell

_Cell at row_idx, col_idx intersection.

(0, 0) is the top, left-most cell.

column_cells(column_idx: int) → list[_Cell]

Sequence of cells in the column at column_idx in this table.

columns

_Columns instance representing the sequence of columns in this table.

row_cells(row_idx: int) → list[_Cell]

DEPRECATED: Use table.rows[row_idx].cells instead.

Sequence of cells in the row at row_idx in this table.

rows

_Rows instance containing the sequence of rows in this table.

property style: _TableStyle | None

_TableStyle object representing the style applied to this table.

Read/write. The default table style for the document (often Normal Table) is returned if the table has no directly-applied style. Assigning None to this property removes any directly-applied table style causing it to inherit the default table style of the document.

Note that the style name of a table style differs slightly from that displayed in the user interface; a hyphen, if it appears, must be removed. For example, Light Shading - Accent 1 becomes Light Shading Accent 1.

property table_direction: WD_TABLE_DIRECTION | None

Member of WD_TABLE_DIRECTION indicating cell-ordering direction.

For example: WD_TABLE_DIRECTION.LTR. None indicates the value is inherited from the style hierarchy.

_Cell 对象

_Cell objects

class docx.table._Cell(tc: CT_Tc, parent: TableParent)

Table cell.

add_paragraph(text: str = '', style: str | ParagraphStyle | None = None)

Return a paragraph newly added to the end of the content in this cell.

If present, text is added to the paragraph in a single run. If specified, the paragraph style style is applied. If style is not specified or is None, the result is as though the 'Normal' style was applied. Note that the formatting of text in a cell can be influenced by the table style. text can contain tab (\t) characters, which are converted to the appropriate XML form for a tab. text can also include newline (\n) or carriage return (\r) characters, each of which is converted to a line break.

add_table(rows: int, cols: int) → Table

Return a table newly added to this cell after any existing cell content.

The new table will have rows rows and cols columns.

An empty paragraph is added after the table because Word requires a paragraph element as the last element in every cell.

property grid_span: int

Number of layout-grid cells this cell spans horizontally.

A "normal" cell has a grid-span of 1. A horizontally merged cell has a grid-span of 2 or more.

iter_inner_content() → Iterator[Paragraph | Table]

Generate each Paragraph or Table in this container in document order.

merge(other_cell: _Cell)

Return a merged cell created by spanning the rectangular region having this cell and other_cell as diagonal corners.

Raises InvalidSpanError if the cells do not define a rectangular region.

property paragraphs

List of paragraphs in the cell.

A table cell is required to contain at least one block-level element and end with a paragraph. By default, a new cell contains a single paragraph. Read-only

property tables

List of tables in the cell, in the order they appear.

Read-only.

property text: str

The entire contents of this cell as a string of text.

Assigning a string to this property replaces all existing content with a single paragraph containing the assigned text in a single run.

property vertical_alignment

Member of WD_CELL_VERTICAL_ALIGNMENT or None.

A value of None indicates vertical alignment for this cell is inherited. Assigning None causes any explicitly defined vertical alignment to be removed, restoring inheritance.

property width

The width of this cell in EMU, or None if no explicit width is set.

_Row 对象

_Row objects

class docx.table._Row(tr: CT_Row, parent: TableParent)

Table row.

property cells: tuple[_Cell, ...]

Sequence of _Cell instances corresponding to cells in this row.

Note that Word allows table rows to start later than the first column and end before the last column.

• Only cells actually present are included in the return value.

• This implies the length of this cell sequence may differ between rows of the same table.

• If you are reading the cells from each row to form a rectangular "matrix" data structure of the table cell values, you will need to account for empty leading and/or trailing layout-grid positions using .grid_cols_before and .grid_cols_after.

property grid_cols_after: int

Count of unpopulated grid-columns after the last cell in this row.

Word allows a row to "end early", meaning that one or more cells are not present at the end of that row.

Note these are not simply "empty" cells. The renderer reads this value and "skips" this many columns after drawing the last cell.

Note this also implies that not all rows are guaranteed to have the same number of cells, e.g. _Row.cells could have length n for one row and n - m for the next row in the same table. Visually this appears as a column (at the beginning or end, not in the middle) with one or more cells missing.

property grid_cols_before: int

Count of unpopulated grid-columns before the first cell in this row.

Word allows a row to "start late", meaning that one or more cells are not present at the beginning of that row.

Note these are not simply "empty" cells. The renderer reads this value and skips forward to the table layout-grid position of the first cell in this row; the renderer "skips" this many columns before drawing the first cell.

Note this also implies that not all rows are guaranteed to have the same number of cells, e.g. _Row.cells could have length n for one row and n - m for the next row in the same table.

property height: Length | None

Return a Length object representing the height of this cell, or None if no explicit height is set.

property height_rule: WD_ROW_HEIGHT_RULE | None

Return the height rule of this cell as a member of the WD_ROW_HEIGHT_RULE.

This value is None if no explicit height_rule is set.

property table: Table

Reference to the Table object this row belongs to.

_Column 对象

_Column objects

class docx.table._Column(gridCol: CT_TblGridCol, parent: Table | _Columns | _Rows)

Table column.

property cells: tuple[_Cell, ...]

Sequence of _Cell instances corresponding to cells in this column.

property table: Table

Reference to the Table object this column belongs to.

property width: Length | None

The width of this column in EMU, or None if no explicit width is set.

_Rows 对象

_Rows objects

class docx.table._Rows(tbl: CT_Tbl, parent: TableParent)

Sequence of _Row objects corresponding to the rows in a table.

Supports len(), iteration, indexed access, and slicing.

property table: Table

Reference to the Table object this row collection belongs to.

_Columns 对象

_Columns objects

class docx.table._Columns(tbl: CT_Tbl, parent: TableParent)

Sequence of _Column instances corresponding to the columns in a table.

Supports len(), iteration and indexed access.

property table: Table

Reference to the Table object this column collection belongs to.