Working with Tables

使用表格

Aspose.Cells FOSS for Java 支持 Excel 表格（也称为 ListObjects 或结构化引用）。您可以从单元格范围创建新表格、检查现有表格、配置标题行和汇总行、应用内置表格样式、访问单个列，并将表格转换回普通范围。主要入口是 ListObjectCollection，通过 Worksheet.getListObjects() 访问。

概述

工作表上的表格通过 Worksheet.getListObjects() 返回的 ListObjectCollection 进行管理。每个 ListObject 代表一个 Excel 表格，并公开其显示名称、注释、单元格范围边界、列集合、样式设置以及标题/汇总行的可见性。

使用 ListObjectCollection.add(startRow, startColumn, endRow, endColumn, hasHeaders) 创建新表格，它返回新创建表格的零基索引。另一种重载接受单元格名称字符串：ListObjectCollection.add(startCellName, endCellName, hasHeaders)。

关键类

类	描述
`ListObject`	表示单个 Excel 表。公开 `getDisplayName()`、`getComment()`、范围坐标、列集合、样式类型以及标题/汇总行的可见性。
`ListObjectCollection`	工作表上所有表格的集合。支持 `getCount()`，以及通过 `get()`、`add()`、`remove()` 进行索引和命名查找，并提供样式类型转换助手。
`ListColumn`	表示表格中的一列。公开列 ID、名称以及汇总行计算设置。
`ListColumnCollection`	表格中列的有序集合。可迭代，支持计数和索引访问。
`TableStyleType`	枚举，用于标识内置的 Excel 表格样式（Light 1–21、Medium 1–28、Dark 1–11，或 Custom/None）。
`TotalsCalculation`	枚举，用于表格合计行的聚合函数（SUM、COUNT、AVERAGE、MAX、MIN、STD_DEV、VAR、COUNT_NUMS、CUSTOM、NONE）。

访问工作表上的表格

通过 Worksheet.getListObjects() 从任意 Worksheet 检索 ListObjectCollection。使用 ListObjectCollection.getCount() 确定存在多少表格。单个表格可通过零基索引使用 ListObjectCollection.get(index) 访问，或通过显示名称使用 ListObjectCollection.get(name) 访问。

Workbook wb = new Workbook("input.xlsx");
WorksheetCollection sheets = wb.getWorksheets();
Worksheet ws = sheets.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());
}

创建新表

使用 ListObjectCollection.add() 在单元格范围内插入表格。hasHeaders 参数指示该范围的第一行是否包含列标题。

Workbook wb = new Workbook();
WorksheetCollection sheets = wb.getWorksheets();
Worksheet ws = sheets.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");

检查表属性

一旦拥有 ListObject 引用，您可以读取：

ListObject.getDisplayName() — 表的显示名称字符串。
ListObject.getComment() — 与表关联的可选注释。
ListObject.getStartRow() / ListObject.getStartColumn() — 表范围的左上单元格。
ListObject.getEndRow() / ListObject.getEndColumn() — 表范围的右下单元格。
ListObject.isShowHeaderRow() — 表头行是否可见。
ListObject.isShowTotals() — 合计行是否可见。
ListObject.getListColumns() — 表格的ListColumnCollection。

表格样式

使用ListObject.setTableStyleType(TableStyleType)应用内置表格样式。TableStyleType枚举包括 Light (1–21)、Medium (1–28) 和 Dark (1–11) 变体，以及 NONE 和 CUSTOM。

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

额外的样式切换可控制交错行、交错列以及首列/末列强调：

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

您也可以使用ListObject.setTableStyleName(String)设置自定义样式名称。

辅助方法ListObjectCollection.parseTableStyleType(String)和ListObjectCollection.tableStyleTypeName(TableStyleType)在枚举及其字符串表示之间进行转换。

使用表格列

通过ListObject.getListColumns()访问各个列，该方法返回一个ListColumnCollection。每个ListColumn提供：

ListColumn.getId() — 基于1的 OOXML 列标识符。
ListColumn.getName() / ListColumn.setName(String) — 列标题文本。
ListColumn.getTotalsCalculation() / ListColumn.setTotalsCalculation(TotalsCalculation) — 汇总行的聚合函数。
ListColumn.getTotalsRowLabel() / ListColumn.setTotalsRowLabel(String) — 汇总行中的自定义标签。
ListColumn.getTotalsRowFormula() / ListColumn.setTotalsRowFormula(String) — 汇总行的自定义公式。

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());
}

配置汇总行

使用 ListObject.setShowTotals(true) 启用汇总行，然后使用 TotalsCalculation 枚举为各列设置聚合函数。

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");

调整大小和转换表格

使用 ListObject.resize(startRow, startColumn, endRow, endColumn, hasHeaders) 将表格调整为覆盖不同的单元格范围。

使用 ListObject.convertToRange() 将表格转换回普通单元格范围。这会移除表格结构，同时保留单元格数据和格式。

使用 ListObjectCollection.removeAt(index) 完全从集合中删除表。

AutoFilter 在表上

显示或移除表中列下拉自动筛选箭头：

ListObject.showAutoFilter() — 在标题行显示筛选箭头。
ListObject.removeAutoFilter() — 隐藏筛选箭头。

API Reference 摘要

ListObject

方法	返回类型	描述
`getDisplayName()`	`String`	表格的显示名称。
`setDisplayName(name)`	`void`	设置显示名称。
`getComment()`	`String`	表格的可选注释。
`setComment(comment)`	`void`	设置表注释。
`getStartRow()`	`int`	表格范围的起始行索引。
`getStartColumn()`	`int`	表格范围的起始列索引。
`getEndRow()`	`int`	表格范围的结束行索引。
`getEndColumn()`	`int`	表格范围的结束列索引。
`isShowHeaderRow()`	`boolean`	标题行是否可见。
`setShowHeaderRow(show)`	`void`	显示或隐藏标题行。
`isShowTotals()`	`boolean`	是否显示总计行。
`setShowTotals(show)`	`void`	显示或隐藏总计行。
`getTableStyleType()`	`TableStyleType`	内置表格样式。
`setTableStyleType(type)`	`void`	应用内置表格样式。
`getTableStyleName()`	`String`	自定义表格样式名称。
`setTableStyleName(name)`	`void`	设置自定义表格样式名称。
`getListColumns()`	`ListColumnCollection`	表格的列集合。
`resize(...)`	`void`	将表格调整为新范围。
`convertToRange()`	`void`	将表格转换为普通范围。
`showAutoFilter()`	`void`	显示自动筛选箭头。
`removeAutoFilter()`	`void`	隐藏自动筛选箭头。

ListObjectCollection

方法	返回类型	描述
`getCount()`	`int`	工作表上的表格数量。
`get(index)`	`ListObject`	返回给定零基索引处的表格。
`get(name)`	`ListObject`	返回具有给定显示名称的表格。
`add(startRow, startColumn, endRow, endColumn, hasHeaders)`	`int`	创建一个新表；返回其索引。
`add(startCellName, endCellName, hasHeaders)`	`int`	根据单元格名称创建一个新表；返回其索引。
`removeAt(index)`	`void`	删除给定索引处的表。
`parseTableStyleType(name)`	`TableStyleType`	将字符串转换为 `TableStyleType` 枚举值。
`tableStyleTypeName(type)`	`String`	将 `TableStyleType` 枚举转换为其字符串名称。

ListColumn

方法	返回类型	描述
`getId()`	`int`	以 1 为基准的 OOXML 列标识符。
`getName()`	`String`	列标题文本。
`setName(name)`	`void`	设置列标题文本。
`getTotalsCalculation()`	`TotalsCalculation`	合计行聚合函数。
`setTotalsCalculation(calc)`	`void`	设置总计行的聚合。
`getTotalsRowLabel()`	`String`	总计行中的自定义标签。
`setTotalsRowLabel(label)`	`void`	设置总计行标签。
`getTotalsRowFormula()`	`String`	用于合计行的自定义公式。
`setTotalsRowFormula(formula)`	`void`	设置汇总行公式。

限制

表数据绑定不可单独修改；表格覆盖创建时指定的范围。使用 resize() 来调整覆盖的范围。
自定义表格样式必须先在工作簿中定义，然后才能通过 setTableStyleName() 按名称引用它们。

另请参阅

Aspose.Cells for Java — Enterprise Documentation