Table

Table 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Table 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Table 对每个部分使用独立的命名导入：

1import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@lenso/ui";2
3export default function App() {4  return (5    <Table aria-label="Example table">6      <TableHeader>7        <TableColumn>Name</TableColumn>8        <TableColumn>Role</TableColumn>9      </TableHeader>10      <TableBody>11        <TableRow key="1">12          <TableCell>Kate Moore</TableCell>13          <TableCell>CEO</TableCell>14        </TableRow>15      </TableBody>16    </Table>17  );18}

在 v3 中，Table 使用点语法的复合组件，并新增 Table.ScrollContainer 与 Table.Content：

1import { Table } from "@lenso/ui";2
3export default function App() {4  return (5    <Table>6      <Table.ScrollContainer>7        <Table.Content aria-label="Example table">8          <Table.Header>9            <Table.Column>Name</Table.Column>10            <Table.Column>Role</Table.Column>11          </Table.Header>12          <Table.Body>13            <Table.Row>14              <Table.Cell>Kate Moore</Table.Cell>15              <Table.Cell>CEO</Table.Cell>16            </Table.Row>17          </Table.Body>18        </Table.Content>19      </Table.ScrollContainer>20    </Table>21  );22}

主要变化

1. 组件结构

v2： 独立的命名导入（Table、TableHeader、TableColumn、TableBody、TableRow、TableCell）
v3： 单一 Table 导入配合点语法：Table、Table.ScrollContainer、Table.Content、Table.Header、Table.Column、Table.Body、Table.Row、Table.Cell、Table.Footer

2. 新增包裹层

Table：根容器（样式外层）
Table.ScrollContainer：横向滚动与自定义滚动条
Table.Content：实际的 <table> 元素（aria-label、selectionMode、sortDescriptor 等放在这里）
Table.Footer：替代 bottomContent，用于分页等底部内容

3. Prop 变更

v2 prop	v3 对应位置	说明
`aria-label`	`Table.Content` 的 `aria-label`	移到 `Table.Content`
`selectionMode`	`Table.Content`	移到 `Table.Content`
`selectedKeys`	`Table.Content`	移到 `Table.Content`
`defaultSelectedKeys`	`Table.Content`	移到 `Table.Content`
`onSelectionChange`	`Table.Content`	移到 `Table.Content`
`sortDescriptor`	`Table.Content`	移到 `Table.Content`
`onSortChange`	`Table.Content`	移到 `Table.Content`
`disabledKeys`	`Table.Content`	移到 `Table.Content`
`disallowEmptySelection`	`Table.Content`	移到 `Table.Content`
`selectionBehavior`	`Table.Content`	移到 `Table.Content`
`disabledBehavior`	`Table.Content`	移到 `Table.Content`
`onRowAction`	`Table.Content`	移到 `Table.Content`
`onCellAction`	`Table.Content`	移到 `Table.Content`
`topContent`	—	放在 `Table` 内、`Table.ScrollContainer` 之前
`bottomContent`	—	使用 `Table.Footer`
`topContentPlacement`	—	已移除（直接组合布局）
`bottomContentPlacement`	—	已移除（直接组合布局）
`color`	—	已移除（请用 Tailwind CSS）
`variant`	`Table` 的 `variant`	变为 `"primary"`（卡片式，默认）或 `"secondary"`（扁平）
`layout`	—	已移除
`radius`	—	已移除（请用 Tailwind CSS）
`shadow`	—	已移除（请用 Tailwind CSS）
`isStriped`	—	已移除（请用 Tailwind CSS）
`isCompact`	—	已移除（请用 Tailwind CSS）
`isHeaderSticky`	—	已移除（请用 Tailwind CSS，例如 `sticky top-0`）
`fullWidth`	—	已移除（默认全宽）
`removeWrapper`	—	已移除（直接组合布局）
`hideHeader`	—	已移除（省略 `Table.Header` 或用 CSS）
`isVirtualized`	—	使用 React Aria 的 `Virtualizer` 包裹
`maxTableHeight`	—	使用 CSS 或 Virtualizer
`rowHeight`	—	与 Virtualizer 一起使用 `TableLayout`
`isKeyboardNavigationDisabled`	—	已移除
`disableAnimation`	—	已移除
`classNames`	—	在各复合子组件上使用 `className`

4. 使用 Checkbox 的选择

v2： 设置 selectionMode 后由表格自动渲染 Checkbox。
v3： 在列与行中显式使用带 slot="selection" 的 Checkbox。

5. 加载与空状态

v2： TableBody 上的 loadingState、loadingContent、emptyContent。
v3： Table.Body 上的 renderEmptyState；无限滚动加载用 Table.LoadMore。

6. 分页

v2： Table 上的 bottomContent。
v3： Table.Footer 复合组件。

7. 列宽调整

v2： 非内置能力。
v3： Table.ResizableContainer + Table.ColumnResizer 复合组件。

迁移示例

基础表格

1import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from "@lenso/ui";2
3<Table aria-label="Users">4  <TableHeader>5    <TableColumn>Name</TableColumn>6    <TableColumn>Role</TableColumn>7    <TableColumn>Status</TableColumn>8  </TableHeader>9  <TableBody>10    <TableRow key="1">11      <TableCell>Kate Moore</TableCell>12      <TableCell>CEO</TableCell>13      <TableCell>Active</TableCell>14    </TableRow>15    <TableRow key="2">16      <TableCell>John Doe</TableCell>17      <TableCell>Developer</TableCell>18      <TableCell>Active</TableCell>19    </TableRow>20  </TableBody>21</Table>

动态行

1const columns = [2  { key: "name", label: "Name" },3  { key: "role", label: "Role" },4];5const rows = [6  { key: "1", name: "Kate", role: "CEO" },7  { key: "2", name: "John", role: "Developer" },8];9
10<Table aria-label="Users">11  <TableHeader columns={columns}>12    {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}13  </TableHeader>14  <TableBody items={rows}>15    {(item) => (16      <TableRow key={item.key}>17        {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}18      </TableRow>19    )}20  </TableBody>21</Table>

选择

1const [selectedKeys, setSelectedKeys] = useState(new Set(["1"]));2
3<Table4  aria-label="Users"5  selectionMode="multiple"6  selectedKeys={selectedKeys}7  onSelectionChange={setSelectedKeys}8>9  <TableHeader>10    <TableColumn>Name</TableColumn>11    <TableColumn>Role</TableColumn>12  </TableHeader>13  <TableBody>14    <TableRow key="1">15      <TableCell>Kate</TableCell>16      <TableCell>CEO</TableCell>17    </TableRow>18    <TableRow key="2">19      <TableCell>John</TableCell>20      <TableCell>Developer</TableCell>21    </TableRow>22  </TableBody>23</Table>

排序

1const [sortDescriptor, setSortDescriptor] = useState({2  column: "name",3  direction: "ascending",4});5
6<Table7  aria-label="Users"8  sortDescriptor={sortDescriptor}9  onSortChange={setSortDescriptor}10>11  <TableHeader>12    <TableColumn key="name" allowsSorting>Name</TableColumn>13    <TableColumn key="role" allowsSorting>Role</TableColumn>14  </TableHeader>15  <TableBody items={sortedItems}>16    {(item) => (17      <TableRow key={item.key}>18        {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}19      </TableRow>20    )}21  </TableBody>22</Table>

分页（底部内容）

1<Table2  aria-label="Users"3  bottomContent={4    <Pagination total={10} page={page} onChange={setPage} />5  }6  bottomContentPlacement="outside"7>8  {/* ... */}9</Table>

空状态

1<TableBody emptyContent="No rows to display.">2  {[]}3</TableBody>

样式相关变化

v2：`classNames` prop

1<Table2  classNames={{3    base: "custom-base",4    wrapper: "custom-wrapper",5    table: "custom-table",6    thead: "custom-header",7    tbody: "custom-body",8    tr: "custom-row",9    th: "custom-column",10    td: "custom-cell",11  }}12/>

v3：直接使用 `className`

1<Table className="custom-base">2  <Table.ScrollContainer className="custom-wrapper">3    <Table.Content aria-label="Table" className="custom-table">4      <Table.Header className="custom-header">5        <Table.Column className="custom-column">Name</Table.Column>6      </Table.Header>7      <Table.Body className="custom-body">8        <Table.Row className="custom-row">9          <Table.Cell className="custom-cell">Value</Table.Cell>10        </Table.Row>11      </Table.Body>12    </Table.Content>13  </Table.ScrollContainer>14</Table>

组件结构（Anatomy）

v3 的 Table 结构如下：

1Table (Root container)2  ├── Table.ScrollContainer (horizontal scroll)3  │   └── Table.Content (<table> element, aria-label, selectionMode, etc.)4  │       ├── Table.Header (<thead>)5  │       │   └── Table.Column (<th>, allowsSorting, etc.)6  │       │       └── Table.ColumnResizer (optional)7  │       └── Table.Body (<tbody>, items, renderEmptyState)8  │           ├── Table.Row (<tr>)9  │           │   └── Table.Cell (<td>)10  │           └── Table.LoadMore (optional, infinite scroll)11  │               └── Table.LoadMoreContent12  └── Table.Footer (optional, pagination, etc.)

数据项标识

v2： React 的 key 同时用于列表调和与选择状态。
v3： 在 Table.Row 与 Table.Column 上使用 id 承载选择/排序状态；列表渲染仍保留 React 的 key。

总结

导入方式：由多个命名导入 → 单一 Table 导入配合点语法。
新增包裹层：Table.ScrollContainer 与 Table.Content 包裹表格结构。
prop 迁移：aria-label、selectionMode、sortDescriptor 等从 Table 移到 Table.Content。
底部区域：bottomContent → Table.Footer。
顶部区域：topContent → 放在 Table 内、Table.ScrollContainer 之前。
选择用 Checkbox：由自动渲染 → 显式使用 slot="selection" 的 Checkbox。
空状态：emptyContent → Table.Body 的 renderEmptyState。
加载：loadingState / loadingContent → 无限滚动场景用 Table.LoadMore。
列宽调整：新增 Table.ResizableContainer 与 Table.ColumnResizer。
标识字段：行/列由 key 表达业务标识 → 使用 id。
样式类 prop 移除：color、radius、shadow、isStriped、isCompact 等 → 请用 Tailwind CSS。
classNames 移除：在各复合子组件上使用 className。