Table class
Table class
Represents a table in a Word document. To learn more, visit the Working with Tables documentation article.
Remarks
Table is a block-level node and can be a child of classes derived from Story or InlineStory.
Table can contain one or more Row nodes.
A minimal valid table needs to have at least one Row.
Inheritance: Table → CompositeNode → Node
Constructors
| Name | Description |
|---|---|
| Table(doc) | Initializes a new instance of the Table class. |
Properties
| Name | Description |
|---|---|
| absolute_horizontal_distance | Gets or sets absolute horizontal floating table position specified by the table properties, in points. Default value is 0. |
| absolute_vertical_distance | Gets or sets absolute vertical floating table position specified by the table properties, in points. Default value is 0. |
| alignment | Specifies how an inline table is aligned in the document. |
| allow_auto_fit | Allows Microsoft Word and Aspose.Words to automatically resize cells in a table to fit their contents. |
| allow_cell_spacing | Gets or sets the “Allow spacing between cells” option. |
| allow_overlap | Gets whether a floating table shall allow other floating objects in the document to overlap its extents when displayed. Default value is True. |
| bidi | Gets or sets whether this is a right-to-left table. |
| bottom_padding | Gets or sets the amount of space (in points) to add below the contents of cells. |
| cell_spacing | Gets or sets the amount of space (in points) between the cells. |
| count | Gets the number of immediate children of this node. (Inherited from CompositeNode) |
| custom_node_id | Specifies custom node identifier. (Inherited from Node) |
| description | Gets or sets description of this table. It provides an alternative text representation of the information contained in the table. |
| distance_bottom | Gets or sets distance between table bottom and the surrounding text, in points. |
| distance_left | Gets or sets distance between table left and the surrounding text, in points. |
| distance_right | Gets or sets distance between table right and the surrounding text, in points. |
| distance_top | Gets or sets distance between table top and the surrounding text, in points. |
| document | Gets the document to which this node belongs. (Inherited from Node) |
| first_child | Gets the first child of the node. (Inherited from CompositeNode) |
| first_row | Returns the first Row node in the table. |
| has_child_nodes | Returns True if this node has any child nodes.(Inherited from CompositeNode) |
| horizontal_anchor | Gets the base object from which the horizontal positioning of floating table should be calculated. Default value is RelativeHorizontalPosition.COLUMN. |
| is_composite | Returns True if this node can contain other nodes.(Inherited from Node) |
| last_child | Gets the last child of the node. (Inherited from CompositeNode) |
| last_row | Returns the last Row node in the table. |
| left_indent | Gets or sets the value that represents the left indent of the table. |
| left_padding | Gets or sets the amount of space (in points) to add to the left of the contents of cells. |
| next_sibling | Gets the node immediately following this node. (Inherited from Node) |
| node_type | Returns NodeType.TABLE. |
| parent_node | Gets the immediate parent of this node. (Inherited from Node) |
| preferred_width | Gets or sets the table preferred width. |
| previous_sibling | Gets the node immediately preceding this node. (Inherited from Node) |
| range | Returns a Range object that represents the portion of a document that is contained in this node. (Inherited from Node) |
| relative_horizontal_alignment | Gets or sets floating table relative horizontal alignment. |
| relative_vertical_alignment | Gets or sets floating table relative vertical alignment. |
| right_padding | Gets or sets the amount of space (in points) to add to the right of the contents of cells. |
| rows | Provides typed access to the rows of the table. |
| style | Gets or sets the table style applied to this table. |
| style_identifier | Gets or sets the locale independent style identifier of the table style applied to this table. |
| style_name | Gets or sets the name of the table style applied to this table. |
| style_options | Gets or sets bit flags that specify how a table style is applied to this table. |
| text_wrapping | Gets or sets Table.text_wrapping for table. |
| title | Gets or sets title of this table. It provides an alternative text representation of the information contained in the table. |
| top_padding | Gets or sets the amount of space (in points) to add above the contents of cells. |
| vertical_anchor | Gets the base object from which the vertical positioning of floating table should be calculated. Default value is RelativeVerticalPosition.MARGIN. |
Methods
| Name | Description |
|---|---|
| accept(visitor) | Accepts a visitor. |
| accept_end(visitor) | Accepts a visitor for visiting the end of the table. |
| accept_start(visitor) | Accepts a visitor for visiting the start of the table. |
| append_child(new_child) | Adds the specified node to the end of the list of child nodes for this node. (Inherited from CompositeNode) |
| auto_fit(behavior) | Resizes the table and cells according to the specified auto fit behavior. |
| clear_borders() | Removes all table and cell borders on this table. |
| clear_shading() | Removes all shading on the table. |
| clone(is_clone_children) | Creates a duplicate of the node. (Inherited from Node) |
| convert_to_horizontally_merged_cells() | Converts cells horizontally merged by width to cells merged by CellFormat.horizontal_merge. |
| ensure_minimum() | If the table has no rows, creates and appends one Row. |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified object type. (Inherited from Node) |
| get_ancestor(ancestor_type) | Gets the first ancestor of the specified NodeType. (Inherited from Node) |
| get_child(node_type, index, is_deep) | Returns an Nth child node that matches the specified type. (Inherited from CompositeNode) |
| get_child_nodes(node_type, is_deep) | Returns a live collection of child nodes that match the specified type. (Inherited from CompositeNode) |
| get_text() | Gets the text of this node and of all its children. (Inherited from Node) |
| index_of(child) | Returns the index of the specified child node in the child node array. (Inherited from CompositeNode) |
| insert_after(new_child, ref_child) | Inserts the specified node immediately after the specified reference node. (Inherited from CompositeNode) |
| insert_before(new_child, ref_child) | Inserts the specified node immediately before the specified reference node. (Inherited from CompositeNode) |
| next_pre_order(root_node) | Gets next node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| node_type_to_string(node_type) | A utility method that converts a node type enum value into a user friendly string. (Inherited from Node) |
| prepend_child(new_child) | Adds the specified node to the beginning of the list of child nodes for this node. (Inherited from CompositeNode) |
| previous_pre_order(root_node) | Gets the previous node according to the pre-order tree traversal algorithm. (Inherited from Node) |
| remove() | Removes itself from the parent. (Inherited from Node) |
| remove_all_children() | Removes all the child nodes of the current node. (Inherited from CompositeNode) |
| remove_child(old_child) | Removes the specified child node. (Inherited from CompositeNode) |
| remove_smart_tags() | Removes all SmartTag descendant nodes of the current node. (Inherited from CompositeNode) |
| select_nodes(xpath) | Selects a list of nodes matching the XPath expression. (Inherited from CompositeNode) |
| select_single_node(xpath) | Selects the first Node that matches the XPath expression. (Inherited from CompositeNode) |
| set_border(border_type, line_style, line_width, color, is_override_cell_borders) | Sets the specified table border to the specified line style, width and color. |
| set_borders(line_style, line_width, color) | Sets all table borders to the specified line style, width and color. |
| set_shading(texture, foreground_color, background_color) | Sets shading to the specified values on whole table. |
| to_string(save_format) | Exports the content of the node into a string in the specified format. (Inherited from Node) |
| to_string(save_options) | Exports the content of the node into a string using the specified save options. (Inherited from Node) |
Examples
Shows how to build a formatted 2x2 table.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
table = builder.start_table()
builder.insert_cell()
builder.cell_format.vertical_alignment = aw.tables.CellVerticalAlignment.CENTER
builder.write("Row 1, cell 1.")
builder.insert_cell()
builder.write("Row 1, cell 2.")
builder.end_row()
# While building the table, the document builder will apply its current row_format/cell_format property values
# to the current row/cell that its cursor is in and any new rows/cells as it creates them.
self.assertEqual(aw.tables.CellVerticalAlignment.CENTER, table.rows[0].cells[0].cell_format.vertical_alignment)
self.assertEqual(aw.tables.CellVerticalAlignment.CENTER, table.rows[0].cells[1].cell_format.vertical_alignment)
builder.insert_cell()
builder.row_format.height = 100
builder.row_format.height_rule = aw.HeightRule.EXACTLY
builder.cell_format.orientation = aw.TextOrientation.UPWARD
builder.write("Row 2, cell 1.")
builder.insert_cell()
builder.cell_format.orientation = aw.TextOrientation.DOWNWARD
builder.write("Row 2, cell 2.")
builder.end_row()
builder.end_table()
# Previously added rows and cells are not retroactively affected by changes to the builder's formatting.
self.assertEqual(0, table.rows[0].row_format.height)
self.assertEqual(aw.HeightRule.AUTO, table.rows[0].row_format.height_rule)
self.assertEqual(100, table.rows[1].row_format.height)
self.assertEqual(aw.HeightRule.EXACTLY, table.rows[1].row_format.height_rule)
self.assertEqual(aw.TextOrientation.UPWARD, table.rows[1].cells[0].cell_format.orientation)
self.assertEqual(aw.TextOrientation.DOWNWARD, table.rows[1].cells[1].cell_format.orientation)
doc.save(ARTIFACTS_DIR + "DocumentBuilder.build_table.docx")
Shows how to create a table.
doc = aw.Document()
table = aw.tables.Table(doc)
doc.first_section.body.append_child(table)
# Tables contain rows, which contain cells, which may have paragraphs
# with typical elements such as runs, shapes, and even other tables.
# Calling the "ensure_minimum" method on a table will ensure that
# the table has at least one row, cell, and paragraph.
first_row = aw.tables.Row(doc)
table.append_child(first_row)
first_cell = aw.tables.Cell(doc)
first_row.append_child(first_cell)
paragraph = aw.Paragraph(doc)
first_cell.append_child(paragraph)
# Add text to the first cell in the first row of the table.
run = aw.Run(doc, "Hello world!")
paragraph.append_child(run)
doc.save(ARTIFACTS_DIR + "Table.create_table.docx")
Shows how to iterate through all tables in the document and print the contents of each cell.
doc = aw.Document(MY_DIR + "Tables.docx")
tables = doc.first_section.body.tables
self.assertEqual(2, len(tables.to_array()))
for i in range(tables.count):
print("Start of Table", i)
rows = tables[i].rows
# We can use the "to_array" method on a row collection to clone it into an array.
self.assertSequenceEqual(list(rows), rows.to_array())
#Assert.are_not_same(rows, rows.to_array())
for j in range(rows.count):
print("\tStart of Row", j)
cells = rows[j].cells
# We can use the "to_array" method on a cell collection to clone it into an array.
self.assertSequenceEqual(list(cells), cells.to_array())
#Assert.are_not_same(cells, cells.to_array())
for k in range(cells.count):
cell_text = cells[k].to_string(aw.SaveFormat.TEXT).strip()
print(f"\t\tContents of Cell:{k} = \"{cell_text}\"")
print(f"\tEnd of Row {j}")
print(f"End of Table {i}\n")
Shows how to build a nested table without using a document builder.
def test_create_nested_table(self):
doc = aw.Document()
# Create the outer table with three rows and four columns, and then add it to the document.
outer_table = ExTable.create_table(doc, 3, 4, "Outer Table")
doc.first_section.body.append_child(outer_table)
# Create another table with two rows and two columns and then insert it into the first table's first cell.
inner_table = ExTable.create_table(doc, 2, 2, "Inner Table")
outer_table.first_row.first_cell.append_child(inner_table)
doc.save(ARTIFACTS_DIR + "Table.create_nested_table.docx")
@staticmethod
def create_table(doc: aw.Document, row_count: int, cell_count: int, cell_text: str) -> aw.tables.Table:
"""Creates a new table in the document with the given dimensions and text in each cell."""
table = aw.tables.Table(doc)
for row_id in range(1, row_count + 1):
row = aw.tables.Row(doc)
table.append_child(row)
for cell_id in range(1, cell_count + 1):
cell = aw.tables.Cell(doc)
cell.append_child(aw.Paragraph(doc))
cell.first_paragraph.append_child(aw.Run(doc, cell_text))
row.append_child(cell)
# You can use the "title" and "description" properties to add a title and description respectively to your table.
# The table must have at least one row before we can use these properties.
# These properties are meaningful for ISO / IEC 29500 compliant .docx documents (see the OoxmlCompliance class).
# If we save the document to pre-ISO/IEC 29500 formats, Microsoft Word ignores these properties.
table.title = "Aspose table title"
table.description = "Aspose table description"
return table
See Also
- module aspose.words.tables
- class CompositeNode