Working with Tables

Working with Tables

Tables in Aspose.Words FOSS for .NET are represented by the Aspose.Words.Tables namespace: Table, Row, and Cell form a three-level composite node hierarchy that sits in the document tree alongside paragraphs. This page covers building tables with DocumentBuilder, formatting rows and cells, controlling table-wide layout, and merging cells.

The Table Object Model

A Table is a CompositeNode containing Row nodes, and each Row is a CompositeNode containing Cell nodes; a Cell in turn contains paragraphs and, potentially, nested tables. Table.Rows returns a RowCollection, Row.Cells returns a CellCollection, and a Body or other Story exposes every top-level table in it through its Tables property, a TableCollection. All three collections support Add(), Insert(), Remove(), RemoveAt(), Contains(), and IndexOf(). Table.EnsureMinimum(), Row.EnsureMinimum(), and Cell.EnsureMinimum() each fill in the smallest valid content a node of that type needs (an empty row, an empty cell, or an empty paragraph, respectively) after programmatic edits leave one without it.

Building Tables with DocumentBuilder

DocumentBuilder.StartTable() begins a new table at the cursor, InsertCell() adds a cell to the current row, EndRow() closes the current row, and EndTable() closes the table. Set DocumentBuilder.CellFormat and DocumentBuilder.RowFormat before calling InsertCell() or EndRow() to apply default formatting to cells and rows as they are created – these properties act as a template for content the builder inserts next, not a retroactive change to cells already in the document.

Cell and Row Formatting

Cell.CellFormat is a CellFormat instance (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) with ClearFormatting() to reset it and SetPaddings() to set all four cell paddings at once. Row.RowFormat is a RowFormat instance (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) with its own ClearFormatting().

Table-Wide Formatting and AutoFit

Table itself exposes layout properties – Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions), TextWrapping, and accessibility metadata via Title and Description. Table.AutoFit(AutoFitBehavior) resizes the table and its cells according to the given behavior. SetBorder() sets one border side and SetBorders() sets every border to the same line style, width, and color across the whole table; ClearBorders() and ClearShading() reset those. ConvertToHorizontallyMergedCells() converts cells that were merged by matching width into cells that are explicitly flagged with HorizontalMerge.

Preferred and Cell Widths

PreferredWidth represents a width and its unit, created with the static factory methods PreferredWidth.FromPercent() or PreferredWidth.FromPoints(); PreferredWidthType identifies which kind of value (Auto, Percent, or Points) a given PreferredWidth holds. Both Table.PreferredWidth and CellFormat.PreferredWidth accept these values.

Merged Cells

CellFormat.HorizontalMerge and CellFormat.VerticalMerge (CellMerge) mark how a cell participates in a horizontal or vertical merge with its neighbors. CellVerticalAlignment controls how content is justified within a cell vertically, independent of any merge state.

Tips and Best Practices

• Close every StartTable() with a matching EndRow() per row and a final EndTable() – an unclosed row or table leaves the builder’s internal state (and the resulting document tree) malformed.
• Set DocumentBuilder.CellFormat and DocumentBuilder.RowFormat before each InsertCell() or EndRow() call if different rows or cells in the same table need different formatting; the builder applies whatever is currently set at the moment of insertion.
• Call Table.EnsureMinimum(), Row.EnsureMinimum(), or Cell.EnsureMinimum() after removing content programmatically so the node keeps the minimum valid structure Word expects.
• Use PreferredWidth.FromPercent() for tables that should adapt to the available page width, and PreferredWidth.FromPoints() for a fixed layout width.
• AutoFitBehavior is applied when you call Table.AutoFit() – it does not continuously re-run as you add or remove content, so call it again after significant edits if you need the table re-fitted.

Common Issues

FAQ

How do I build a table from scratch with DocumentBuilder?

Call StartTable(), then InsertCell() for each cell in a row, EndRow() to close the row, repeat for additional rows, and finally EndTable() to close the table.

How do I set a percentage-based table width instead of a fixed width?

Assign Table.PreferredWidth = PreferredWidth.FromPercent(value) instead of PreferredWidth.FromPoints(value).

How do I reset all formatting on a cell or row?

Call CellFormat.ClearFormatting() on a cell’s CellFormat, or RowFormat.ClearFormatting() on a row’s RowFormat.

How do I set borders and shading for the whole table at once?

Use Table.SetBorders() for a uniform border on every side, Table.SetBorder() for one side at a time, and Table.SetShading() for uniform shading; ClearBorders() and ClearShading() reset them.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation