表格

表格用于使用行和列显示表格数据。它们允许用户快速扫描、排序、比较和对大量数据执行操作。

安装

上述命令仅用于单独安装。如果 @heroui/react 已全局安装，则可以跳过此步骤。

导入

HeroUI 导出 6 个与表格相关的组件

• Table: 用于显示表格的主要组件。
• TableHeader: 表格的表头。
• TableBody: 表格的主体。
• TableColumn: 表格的列。
• TableRow: 表格的行。
• TableCell: 表格的单元格。

用法

动态

要动态渲染表格，您可以使用 columns 属性传递列，并使用 items 属性传递数据。

为什么不使用数组 map？

使用 items 属性并提供渲染函数，可以让 react-aria 自动缓存每个项目的渲染结果，并避免在集合中只有一个项目更改时重新渲染所有项目。这对于大型集合具有很大的性能优势。

您也可以使用 Array.map 来渲染项目，但其性能不如使用 items 和 columns 属性。

示例

注意：要了解更多关于 React Aria 集合以及如何使用它们的信息，请查看 React Aria Collections。

空状态

您可以使用 emptyContent 属性在表格为空时渲染自定义组件。

无表头

如果您不想渲染表头，可以使用 hideHeader 属性。

无外层容器

默认情况下，表格包裹在一个带有小阴影效果和边框半径的 div 元素中。您可以使用 removeWrapper 属性移除外层容器，仅渲染表格。

自定义单元格

您可以在表格单元格内渲染任何组件。在下面的示例中，我们根据列的 key 渲染不同的组件。

条纹行

您可以使用 isStriped 属性渲染条纹行。

单行选择

表格行是可以被选择的。要实现这一点，你可以使用 selectionMode 属性。使用 defaultSelectedKeys 来提供默认选定的行集合。

注意: 选定键的值必须与行的 key 属性匹配。

多行选择

你也可以通过使用 selectionMode="multiple" 属性来选择多行。使用 defaultSelectedKeys 来提供默认选定的行集合。

注意: 当使用多选时，可选择的复选框将会在表格的第一列渲染。

禁止空选择

表格也支持 disallowEmptySelection 属性，该属性强制用户始终在表格中至少选择一行。在这种模式下，如果单行被选中，并且用户再次点击它，则不会取消选择。

受控选择

要以编程方式控制行选择，请使用 selectedKeys 属性与 onSelectionChange 回调函数配对使用。当行被点击时，选定行的 key 属性将被传递到回调函数中，允许你相应地更新状态。

注意: selectedKeys 属性必须是一个 Set 对象。

禁用行

你可以使用 disabledKeys 属性来禁用行。这将阻止行被选中，如下例所示。

选择行为

默认情况下，表格使用 toggle 选择行为，其行为类似于复选框组：单击、轻触或按下 Space 或 Enter 键会切换焦点行的选择状态。

当 selectionBehavior 属性设置为 replace 时，鼠标单击某行会将选择替换为仅该行。使用箭头键会移动焦点和选择。要选择多行，可以使用修饰键，例如 Ctrl、Cmd 和 Shift。

行操作

表格通过 onRowAction 回调函数支持行操作。在默认的 toggle 选择行为中，当没有任何行被选中时，单击或轻触行会触发行操作。

这种行为在 replace 选择行为中略有不同，其中单击选择行，而双击执行操作。

行排序

当列标题被按下时，表格支持对其数据进行排序。要指定 Column 应支持排序，请为其提供 allowsSorting 属性。

表格接受 sortDescriptor 属性，该属性定义了当前要排序的列键和排序方向（升序/降序）。当用户按下可排序的列标题时，该列的键和排序方向将传递到 onSortChange 回调函数中，允许你适当地更新 sortDescriptor。

我们建议使用来自 @react-stately/data 的 useAsyncList Hook 来管理数据排序。因此，请确保在使用排序功能之前安装它。

请注意，我们将 isLoading 和 loadingContent 属性传递给 TableBody，以便在数据正在获取时渲染加载状态。

加载更多数据

表格允许你在表格末尾添加自定义组件，在下面的示例中，我们使用了一个按钮来加载更多数据。

注意: 我们将 isHeaderSticky 传递给 Table 组件，以使表头保持粘性。

分页表格

你可以使用 Pagination 组件来对表格进行分页。

异步分页

也可以使用 Pagination 组件来异步分页表格。为了获取数据，我们使用了来自 SWR 的 useSWR Hook。

无限分页

表格也支持无限分页。为此，你可以使用来自 @react-stately/data 的 useAsyncList Hook 和 @heroui/use-infinite-scroll Hook。

用例示例

在创建表格时，你通常需要诸如排序、分页和筛选等核心功能。在下面的示例中，我们结合了所有这些功能来创建一个完整的表格。

插槽 (Slots)

• base: 为表格组件定义灵活的列布局和相对定位。
• wrapper: 应用于最外层包装器，提供内边距、灵活布局、相对定位、视觉样式和可滚动溢出处理。
• table: 设置表格具有完整的最小宽度和自动调整的高度。
• thead: 为表头中第一个子行指定圆角。
• tbody: 没有特定的样式应用于表格的主体。
• tr: 表格行的样式，包括组焦点、轮廓属性和一组未定义的 focus-visible 类。
• th: 表头单元格的样式，包括内边距、文本对齐方式、字体属性以及可排序列的特殊样式。
• td: 应用于表格单元格，具有内边距、对齐方式和相对定位的属性，以及第一个子元素、选择指示和禁用单元格的特殊样式。
• tfoot: 没有特定的样式应用于表格的页脚。
• sortIcon: 排序图标的样式，具有基于排序方向和悬停状态的边距、不透明度和过渡效果属性。
• emptyWrapper: 定义空表格的样式，具有文本对齐方式、颜色和指定的高度。
• loadingWrapper: 当表格正在加载时应用的样式，将其定位在其容器的中心。

自定义样式

你可以通过将自定义 Tailwind CSS 类传递给组件插槽来自定义 Table 组件。

数据属性 (Data Attributes)

TableBody 具有以下属性

• data-empty: 当表格为空时。
• data-loading: 当表格数据正在加载时。基于 TableBody 的 isLoading 和 loadingContent 属性。

TableRow 具有以下属性

• data-selected: 当行被选中时。基于 Table 的 selectedKeys 属性。
• data-disabled: 当行被禁用时。基于 Table 的 disabledKeys 属性。
• data-hover: 当行被悬停时。基于 useHover
• data-focus-visible: 当行通过键盘获得焦点时。基于 useFocusRing。
• data-first: 当行是第一行时。
• data-middle: 当行在中间时。
• data-odd: 当行是奇数行时。
• data-last: 当行是最后一行时。

TableCell 具有以下属性

• data-selected: 当单元格所在的行被选中时。基于 Table 的 selectedKeys 属性。
• data-focus-visible: 当单元格通过键盘获得焦点时。基于 useFocusRing。

无障碍访问 (Accessibility)

• 通过 ARIA 作为网格暴露给辅助技术。
• 通过箭头键在列、行、单元格和单元格内可聚焦元素之间进行键盘导航。
• 通过鼠标、触摸或键盘交互进行单行、多行或无行选择。
• 支持禁用行，禁用行无法被选择。
• 列排序支持。
• 异步加载、无限滚动、筛选和排序支持。
• 支持切换和替换选择行为。
• 标签支持以实现无障碍访问。
• 确保使用 ARIA live region 宣布选择。
• 支持将列标记为行标题，这将在使用屏幕阅读器导航行时被读取。
• 可选支持在每行中使用复选框进行选择，以及在表头中使用复选框来选择所有行。
• 键盘导航期间的自动滚动支持。
• 通过双击、Enter 键或轻触支持行操作。
• Typeahead 允许通过键入文本来聚焦行。
• 当同时存在选择和行操作时，长按进入触摸选择模式。

API

Table Props (表格属性)

Table Events (表格事件)

TableHeader Props (表格头部属性)

TableColumn Props (表格列属性)

TableBody Props (表格主体属性)

TableBody Events (表格主体事件)

TableRow Props (表格行属性)

TableCell 属性

表格类型

排序描述符

选择

加载状态