表格

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

安装

npx nextui-cli@latest add table

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

导入

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

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

用法

动态

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

为什么不使用数组映射？

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

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

示例

import {Table, TableHeader, TableColumn, TableBody, TableRow, TableCell, getKeyValue} from "@nextui-org/react";

const rows = [...];

const columns = [...];

export default function App() {
  return (
    <Table aria-label="Example table with dynamic content">
      <TableHeader>
        {columns.map((column) =>
          <TableColumn key={column.key}>{column.label}</TableColumn>
        )}
      </TableHeader>
      <TableBody>
        {rows.map((row) =>
          <TableRow key={row.key}>
            {(columnKey) => <TableCell>{getKeyValue(row, columnKey)}</TableCell>}
          </TableRow>
        )}
      </TableBody>
    </Table>
  );
}

注意：要了解更多关于 React Aria 集合及其使用方法的信息，请查看 React Aria 集合.

空状态

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

无标题

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

无包装器

默认情况下，表格被包装在一个带有轻微阴影效果和圆角的 div 元素中。您可以使用 removeWrapper 属性来移除包装器，只渲染表格。

自定义单元格

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

条纹行

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

单行选择

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

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

多行选择

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

注意：使用多选时，表格的第一列将呈现可选择的复选框。

禁止空选择

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

受控选择

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

注意：selectedKeys 属性必须是 Set 对象。

禁用行

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

选择行为

默认情况下，Table 使用 toggle 选择行为，其行为类似于复选框组：单击、轻触或按下 空格 或 回车 键将切换所选行的选择状态。

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

行操作

Table 通过 onRowAction 回调支持行操作。在默认的 toggle 选择行为中，当没有选择任何内容时，单击或轻触该行将触发行操作。

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

排序行

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

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

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

npm install @react-stately/data

import {useAsyncList} from "@react-stately/data";

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

加载更多数据

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

注意：我们传递了 isHeaderSticky 到 Table 组件，以使标题粘住。

分页表格

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

异步分页

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

无限分页

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

用例示例

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

插槽

• base: 定义表格组件的灵活列布局和相对定位。
• wrapper: 应用于最外层的包装器，提供填充、灵活布局、相对定位、视觉样式和可滚动溢出处理。
• table: 将表格设置为具有全最小宽度和自动调整高度。
• thead: 为表格标题中的第一个子行指定圆角。
• tbody: 没有对表格主体应用任何特定样式。
• tr: 表格行的样式，包括组焦点、轮廓属性和一组未定义的 focus-visible 类。
• 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 实时区域宣布选择。
• 支持将列标记为行标题，这些标题将在使用屏幕阅读器导航行时被读取。
• 可选地支持每行中的复选框以进行选择，以及标题中的复选框以选择所有行。
• 在键盘导航期间自动滚动支持。
• 支持通过双击、Enter 键或点击进行行操作。
• 类型提前输入，允许通过键入文本来聚焦行。
• 长按在触摸时进入选择模式，前提是同时存在选择和行操作。

API

表格属性

表格事件

TableHeader Props

TableColumn Props

TableBody Props

TableBody Events

TableRow Props

表格单元格属性

表格类型

排序描述符

type SortDescriptor = {
  column: React.Key;
  direction: "ascending" | "descending";
};

选择

type Selection = "all" | Set<React.Key>;

加载状态

type LoadingState = "loading" | "sorting" | "loadingMore" | "error" | "idle" | "filtering";