表格

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

安装

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

导入

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

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

用法

动态

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

为什么不使用数组 map？

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

您也可以使用 Array.map 来渲染项目，但它不会像使用 items 和 columns 属性那样高效。

示例

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

空状态

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

无标题

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

无包装器

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

自定义单元格

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

条纹行

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

单行选择

可以使表格行可选择。为此，您可以使用 selectionMode 属性。使用 defaultSelectedKeys 提供一组默认选定的行。

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

多行选择

您还可以使用 selectionMode="multiple" 属性选择多行。使用 defaultSelectedKeys 提供一组默认选定的行。

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

不允许空选择

表格还支持 disallowEmptySelection 属性，该属性强制用户始终在表格中至少选择一行。在此模式下，如果选择了单行，用户按下该行，则不会取消选择。

受控选择

要以编程方式控制行选择，请使用 selectedKeys 属性，并搭配 onSelectionChange 回调。当按下行时，选定行的 key 属性将传递到回调中，使您可以相应地更新状态。

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

禁用行

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

选择行为

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

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

行操作

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

在 replace 选择行为中，此行为略有不同，单次单击选择行，并通过双击执行操作。

行排序

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

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

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

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

加载更多数据

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

注意：我们将 isHeaderSticky 传递给 Table 组件，以使标题具有粘性。

分页表格

您可以使用 分页 组件对表格进行分页。

异步分页

也可以使用 分页 组件以异步方式对表格进行分页。为了获取数据，我们使用来自 SWR 的 useSWR 钩子。

无限分页

表格还支持无限分页。为此，您可以使用来自 @react-stately/data 的 useAsyncList 钩子和 @nextui-org/use-infinite-scroll 钩子。

用例示例

在创建表格时，您通常需要排序、分页和筛选等核心功能。在下面的示例中，我们将所有这些功能组合在一起以创建一个完整的表格。

插槽

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

自定义样式

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

数据属性

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。

辅助功能

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

API

表格属性

表格事件

表头属性

表格列属性

表格主体属性

表格主体事件

表格行属性

表格单元格属性

表格类型

排序描述符

选择

加载状态