Table 表格更新

引入

import { Table } from '@heroui/react';

用法

import {Table} from "@heroui/react";

export function Basic() {
  return (
    <Table>

组件结构

引入 Table 组件，并通过点语法访问各部分。

import { Table } from '@heroui/react';

export default () => (
  <Table>
    <Table.ScrollContainer>
      <Table.Content aria-label="Example table">
        <Table.Header>
          <Table.Column>Name</Table.Column>
          <Table.Column>Role</Table.Column>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Kate Moore</Table.Cell>
            <Table.Cell>CEO</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Content>
    </Table.ScrollContainer>
    <Table.Footer>{/* Optional footer content */}</Table.Footer>
  </Table>
);

次要变体

import {Table} from "@heroui/react";

export function SecondaryVariant() {
  return (
    <Table variant="secondary">

排序

在 Table.Column 上设置 allowsSorting 可将列设为可排序。在 Table.Content 上使用 sortDescriptor 与 onSortChange 管理排序状态。

"use client";

import type {SortDescriptor} from "@heroui/react";

import {Table, cn} from "@heroui/react";

选择

在 Table.Content 上设置 selectionMode 以启用行选择。全选与每行复选框可使用带 slot="selection" 的 Checkbox。

"use client";

import type {Selection} from "@heroui/react";

import {Checkbox, Table} from "@heroui/react";

自定义单元格

"use client";

import type {Selection, SortDescriptor} from "@heroui/react";

import {Avatar, Button, Checkbox, Chip, Table, cn} from "@heroui/react";

可展开行

行可以嵌套以展示层级数据。使用 treeColumn 指定列，并在该列单元格内渲染带 slot="chevron" 的 Button，以便用户展开/收起行。使用 expandedKeys 控制哪些行处于展开状态。

"use client";

import type {Selection} from "@heroui/react";

import {Button, Table, cn} from "@heroui/react";

分页

使用 Table.Footer 在表格下方添加分页组件。

"use client";

import {Pagination, Table} from "@heroui/react";
import {useMemo, useState} from "react";

列宽调整

使用 Table.ResizableContainer 包裹表格，并在每个可调整宽度的列中加入 Table.ColumnResizer。

import {Chip, Table} from "@heroui/react";

export function ColumnResizing() {
  return (
    <Table>

空状态

在 Table.Body 上使用 renderEmptyState，在表格无数据时展示自定义内容。

"use client";

import {EmptyState, Table} from "@heroui/react";
import {Icon} from "@iconify/react";

异步加载

使用 Table.LoadMore 实现无限滚动：会渲染一行哨兵节点，在进入视口时触发 onLoadMore。

"use client";

import {Chip, Spinner, Table} from "@heroui/react";
import {useCallback, useRef, useState} from "react";

虚拟化

Table 通过 Virtualizer 支持虚拟化，仅渲染视口内可见行，从而高效处理大数据集。

"use client";

import {Table, TableLayout, Virtualizer} from "@heroui/react";

interface User {

TanStack Table

HeroUI 的 Table 可作为无头表格库之上的渲染层。 本示例使用 TanStack Table 处理列定义、排序与分页，而样式与无障碍由 HeroUI 负责。

"use client";

import type {SortDescriptor} from "@heroui/react";
import type {SortingState} from "@tanstack/react-table";

样式

传入 Tailwind CSS 类

你可以为 Table 的各个部分分别传入类名：

import { Table } from '@heroui/react';

function CustomTable() {
  return (
    <Table className="border border-purple-200">
      <Table.ScrollContainer>
        <Table.Content aria-label="Custom styled table">
          <Table.Header className="bg-purple-50">
            <Table.Column>Name</Table.Column>
          </Table.Header>
          <Table.Body>
            <Table.Row className="hover:bg-purple-50">
              <Table.Cell>Kate Moore</Table.Cell>
            </Table.Row>
          </Table.Body>
        </Table.Content>
      </Table.ScrollContainer>
    </Table>
  );
}

自定义组件类

若要自定义 Table 组件类，可以使用 @layer components 指令。
了解更多。

@layer components {
  .table-root {
    @apply relative grid w-full overflow-clip;
  }

  .table__header {
    @apply bg-gray-100;
  }

  .table__column {
    @apply px-4 py-2.5 text-left text-xs font-medium text-gray-600;
  }

  .table__row {
    @apply bg-white border-b border-gray-200;
  }

  .table__cell {
    @apply px-4 py-3 text-sm;
  }

  .table__footer {
    @apply flex items-center px-4 py-2.5;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Table 组件使用以下 CSS 类（查看源码样式）：

基础类

• .table-root - 根容器（命名为 table-root 而非 table，因为 table 是 Tailwind CSS 内置的 display: table 工具类）
• .table__scroll-container - 横向滚动包裹层与自定义滚动条
• .table__content - <table> 元素
• .table__header - 表头行（<thead>）
• .table__column - 列表头单元格（<th>）
• .table__body - 表体（<tbody>）
• .table__row - 行（<tr>）
• .table__cell - 数据单元格（<td>）
• .table__footer - 表底容器（位于 table 外部）

进阶类

• .table__column-resizer - 列宽拖拽手柄
• .table__resizable-container - 启用列宽调整的包裹层
• .table__load-more - 无限滚动的哨兵行
• .table__load-more-content - 加载指示器的样式容器

变体类

• .table-root--primary - 灰色背景容器与卡片式表体（默认）
• .table-root--secondary - 无背景，独立圆角表头

交互状态

Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：

• 悬停：:hover 或 [data-hovered="true"]（行背景变化）
• 已选中：[data-selected="true"]（行高亮）
• 聚焦：:focus-visible 或 [data-focus-visible="true"]（行、列与单元格的内嵌焦点环）
• 禁用：:disabled 或 [aria-disabled="true"]（降低透明度）
• 可排序：[data-allows-sorting="true"]（列上的交互指针样式）
• 拖动中：[data-dragging="true"]（降低透明度）
• 放置目标：[data-drop-target="true"]（强调色背景）

API 参考

Table Props

Table.ScrollContainer Props

Table.Content Props

继承自 React Aria Table。

Table.Header Props

继承自 React Aria TableHeader。

Table.Column Props

继承自 React Aria Column。

Table.Body Props

继承自 React Aria TableBody。

Table.Row Props

继承自 React Aria Row。

Table.Cell Props

继承自 React Aria Cell。

Table.Footer Props

Table.ColumnResizer Props

继承自 React Aria ColumnResizer。

Table.ResizableContainer Props

继承自 React Aria ResizableTableContainer。

Table.LoadMore Props

继承自 React Aria TableLoadMoreItem。

Table.LoadMoreContent Props

Table.Collection Props

由 React Aria Collection 重新导出。用于在行内与静态单元格并存时渲染动态单元格（例如复选框）。

TableLayout