Working with Tables

Aspose.Cells FOSS for Java supports Excel tables (also known as ListObjects or structured references). You can create new tables from cell ranges, inspect existing tables, configure header and totals rows, apply built-in table styles, access individual columns, and convert tables back to normal ranges. The primary entry point is ListObjectCollection, accessed via Worksheet.getListObjects().

Overview

Tables on a worksheet are managed through the ListObjectCollection returned by Worksheet.getListObjects(). Each ListObject represents one Excel table and exposes its display name, comment, cell range bounds, column collection, style settings, and header/totals row visibility.

A new table is created with ListObjectCollection.add(startRow, startColumn, endRow, endColumn, hasHeaders), which returns the zero-based index of the newly created table. An alternative overload accepts cell-name strings: ListObjectCollection.add(startCellName, endCellName, hasHeaders).

Key Classes

Class	Description
`ListObject`	Represents a single Excel table. Provides access to name, comment, range, columns, style, and header/totals visibility.
`ListObjectCollection`	Collection of all tables on a worksheet. Supports count, index/name access, add, remove, and style-type conversion helpers.
`ListColumn`	Represents one column within a table. Exposes column ID, name, and totals-row calculation settings.
`ListColumnCollection`	Ordered collection of columns in a table. Iterable with count and index access.
`TableStyleType`	Enum identifying a built-in Excel table style (Light 1–21, Medium 1–28, Dark 1–11, or Custom/None).
`TotalsCalculation`	Enum for the aggregation function on a table’s totals row (SUM, COUNT, AVERAGE, MAX, MIN, STD_DEV, VAR, COUNT_NUMS, CUSTOM, NONE).

Accessing Tables on a Worksheet

Retrieve the ListObjectCollection from any Worksheet via Worksheet.getListObjects(). Use ListObjectCollection.getCount() to determine how many tables exist. Individual tables are accessed by zero-based index through ListObjectCollection.get(index) or by display name through ListObjectCollection.get(name).

Workbook wb = new Workbook("input.xlsx");
Worksheet ws = wb.getWorksheets().get(0);
ListObjectCollection tables = ws.getListObjects();

for (int i = 0; i < tables.getCount(); i++) {
    ListObject table = tables.get(i);
    System.out.println("Table: " + table.getDisplayName()
        + " rows: " + table.getStartRow() + "-" + table.getEndRow());
}

Creating a New Table

Use ListObjectCollection.add() to insert a table over a cell range. The hasHeaders parameter indicates whether the first row of the range contains column headers.

Workbook wb = new Workbook();
Worksheet ws = wb.getWorksheets().get(0);

// Populate data
ws.getCells().get("A1").putValue("Product");
ws.getCells().get("B1").putValue("Quantity");
ws.getCells().get("A2").putValue("Widget");
ws.getCells().get("B2").putValue(100);

// Create table over A1:B2 with headers in row 0
int tableIndex = ws.getListObjects().add(0, 0, 1, 1, true);
ListObject table = ws.getListObjects().get(tableIndex);
table.setDisplayName("SalesTable");

Inspecting Table Properties

Once you hold a ListObject reference you can read:

ListObject.getDisplayName() — the table’s display name string.
ListObject.getComment() — an optional comment associated with the table.
ListObject.getStartRow() / ListObject.getStartColumn() — top-left cell of the table range.
ListObject.getEndRow() / ListObject.getEndColumn() — bottom-right cell of the table range.
ListObject.isShowHeaderRow() — whether the header row is visible.
ListObject.isShowTotals() — whether the totals row is visible.
ListObject.getListColumns() — the ListColumnCollection for the table.

Styling Tables

Apply a built-in table style using ListObject.setTableStyleType(TableStyleType). The TableStyleType enum includes Light (1–21), Medium (1–28), and Dark (1–11) variants plus NONE and CUSTOM.

ListObject table = ws.getListObjects().get(0);
table.setTableStyleType(TableStyleType.TABLE_STYLE_MEDIUM_2);

Additional style toggles control banded rows, banded columns, and first/last column emphasis:

ListObject.setShowTableStyleRowStripes(boolean)
ListObject.setShowTableStyleColumnStripes(boolean)
ListObject.setShowTableStyleFirstColumn(boolean)
ListObject.setShowTableStyleLastColumn(boolean)

You can also set a custom style name with ListObject.setTableStyleName(String).

Helper methods ListObjectCollection.parseTableStyleType(String) and ListObjectCollection.tableStyleTypeName(TableStyleType) convert between the enum and its string representation.

Working with Table Columns

Access individual columns through ListObject.getListColumns(), which returns a ListColumnCollection. Each ListColumn exposes:

ListColumn.getId() — the one-based OOXML column identifier.
ListColumn.getName() / ListColumn.setName(String) — the column header text.
ListColumn.getTotalsCalculation() / ListColumn.setTotalsCalculation(TotalsCalculation) — the aggregation function for the totals row.
ListColumn.getTotalsRowLabel() / ListColumn.setTotalsRowLabel(String) — a custom label in the totals row.
ListColumn.getTotalsRowFormula() / ListColumn.setTotalsRowFormula(String) — a custom formula for the totals row.

ListObject table = ws.getListObjects().get(0);
ListColumnCollection columns = table.getListColumns();
for (int i = 0; i < columns.getCount(); i++) {
    ListColumn col = columns.get(i);
    System.out.println("Column " + col.getId() + ": " + col.getName());
}

Configuring the Totals Row

Enable the totals row with ListObject.setShowTotals(true), then set per-column aggregation functions using the TotalsCalculation enum.

ListObject table = ws.getListObjects().get(0);
table.setShowTotals(true);

ListColumn qtyColumn = table.getListColumns().get(1);
qtyColumn.setTotalsCalculation(TotalsCalculation.SUM);

ListColumn labelColumn = table.getListColumns().get(0);
labelColumn.setTotalsRowLabel("Total");

Resizing and Converting Tables

Resize a table to cover a different cell range using ListObject.resize(startRow, startColumn, endRow, endColumn, hasHeaders).

Convert a table back to a normal cell range with ListObject.convertToRange(). This removes the table structure while preserving the cell data and formatting.

Remove a table entirely from the collection with ListObjectCollection.removeAt(index).

AutoFilter on Tables

Show or remove the column drop-down auto-filter arrows on a table:

ListObject.showAutoFilter() — display filter arrows on the header row.
ListObject.removeAutoFilter() — hide the filter arrows.

API Reference Summary

ListObject

Method	Return type	Description
`getDisplayName()`	`String`	Display name of the table.
`setDisplayName(name)`	`void`	Sets the display name.
`getComment()`	`String`	Optional comment for the table.
`setComment(comment)`	`void`	Sets the table comment.
`getStartRow()`	`int`	Start row index of the table range.
`getStartColumn()`	`int`	Start column index of the table range.
`getEndRow()`	`int`	End row index of the table range.
`getEndColumn()`	`int`	End column index of the table range.
`isShowHeaderRow()`	`boolean`	Whether the header row is visible.
`setShowHeaderRow(show)`	`void`	Shows or hides the header row.
`isShowTotals()`	`boolean`	Whether the totals row is visible.
`setShowTotals(show)`	`void`	Shows or hides the totals row.
`getTableStyleType()`	`TableStyleType`	The built-in table style.
`setTableStyleType(type)`	`void`	Applies a built-in table style.
`getTableStyleName()`	`String`	Custom table style name.
`setTableStyleName(name)`	`void`	Sets a custom table style name.
`getListColumns()`	`ListColumnCollection`	The table’s column collection.
`resize(...)`	`void`	Resizes the table to a new range.
`convertToRange()`	`void`	Converts the table to a normal range.
`showAutoFilter()`	`void`	Displays auto-filter arrows.
`removeAutoFilter()`	`void`	Hides auto-filter arrows.

ListObjectCollection

Method	Return type	Description
`getCount()`	`int`	Number of tables on the worksheet.
`get(index)`	`ListObject`	Returns the table at the given zero-based index.
`get(name)`	`ListObject`	Returns the table with the given display name.
`add(startRow, startColumn, endRow, endColumn, hasHeaders)`	`int`	Creates a new table; returns its index.
`add(startCellName, endCellName, hasHeaders)`	`int`	Creates a new table from cell names; returns its index.
`removeAt(index)`	`void`	Removes the table at the given index.
`parseTableStyleType(name)`	`TableStyleType`	Converts a string to a `TableStyleType` enum value.
`tableStyleTypeName(type)`	`String`	Converts a `TableStyleType` enum to its string name.

ListColumn

Method	Return type	Description
`getId()`	`int`	One-based OOXML column identifier.
`getName()`	`String`	Column header text.
`setName(name)`	`void`	Sets the column header text.
`getTotalsCalculation()`	`TotalsCalculation`	Totals row aggregation function.
`setTotalsCalculation(calc)`	`void`	Sets the totals row aggregation.
`getTotalsRowLabel()`	`String`	Custom label in the totals row.
`setTotalsRowLabel(label)`	`void`	Sets the totals row label.
`getTotalsRowFormula()`	`String`	Custom formula for the totals row.
`setTotalsRowFormula(formula)`	`void`	Sets the totals row formula.

Limitations

Table data bindings are not separately modifiable; the table covers the range specified at creation time. Use resize() to adjust the covered range.
Custom table styles must be defined in the workbook before referencing them by name via setTableStyleName().

Working with Tables