精通 React Table (v8): 构建强大、灵活的 React 表格

在现代 Web 开发中，数据表格是展示和操作集合信息的基石。无论是简单的信息罗列，还是需要排序、筛选、分页等复杂交互的大型数据集，一个功能强大且灵活的表格组件都至关重要。React 生态系统中有许多表格库，但 React Table（现在由 TanStack 维护，称为 TanStack Table，我们通常仍称其核心为 React Table）以其独特的 “headless” 设计理念脱颖而出，提供了无与伦比的控制力和灵活性。

本文将深入探讨如何在 React 项目中使用最新版本的 React Table (v8) 来创建功能丰富、可定制的表格。我们将从基础概念入手，逐步构建一个包含排序、筛选、分页和行选择等常见功能的表格，并讨论其核心优势和最佳实践。

什么是 React Table (v8 / TanStack Table)？

React Table v8 与其前身 v7 有一个显著的区别：它是一个 Headless UI 库。这意味着 React Table 本身不提供任何 UI 组件或样式。它专注于处理表格的复杂逻辑——状态管理、数据处理（排序、过滤、分页、分组、聚合等）、API 设计——并将最终的渲染控制权完全交给开发者。

为什么选择 Headless UI？

1. 完全的渲染控制: 你可以自由选择使用标准的 HTML <table> 元素、<div> 结构、甚至是 Canvas 或 SVG 来渲染你的表格。库不限制你的标记语言。
2. 自由的样式: 因为库不输出 UI，你可以无缝集成任何你喜欢的样式方案，无论是普通的 CSS、CSS Modules、Sass、Styled Components、Tailwind CSS 还是 Material UI 等组件库。
3. 更小的包体积: 库只包含核心逻辑，不包含任何 UI 代码，使得最终打包体积更小。
4. 更高的可扩展性: Headless 设计使得添加自定义功能或与其他库集成变得更加容易。

React Table v8 的核心思想是提供一系列强大的 Hooks 和辅助函数，你可以在你的 React 组件中使用它们来管理表格状态和获取渲染所需的数据和方法。

准备工作

在开始之前，请确保你具备以下条件：

1. Node.js 和 npm/yarn: 用于管理项目依赖和运行开发服务器。
2. React 基础知识: 理解 React 组件、Hooks (特别是 useState, useEffect, useMemo) 和 JSX。
3. 一个 React 项目: 你可以使用 Create React App、Next.js、Vite 或任何其他你喜欢的 React 脚手架创建一个项目。

安装 React Table

首先，将 React Table 添加到你的项目中。打开终端，导航到你的项目目录，然后运行：

“`bash
npm install @tanstack/react-table

或者

yarn add @tanstack/react-table
“`

核心概念

理解 React Table v8 的核心概念是高效使用它的关键。

1. useReactTable Hook: 这是 React Table 的核心入口点。你将表格的配置（数据、列定义、状态管理、启用的功能等）传递给这个 Hook，它会返回一个 table 实例。
2. table 实例: 这个实例包含了渲染表格所需的一切：处理过的行数据、表头信息、以及用于交互（如排序、分页）的方法和状态。
3. ColumnDef (列定义): 这是一个定义表格列结构和行为的对象数组。每一列至少需要一个 accessorKey (或 accessorFn) 来从行数据中提取值，以及一个 header 来定义表头显示内容。你可以为列定义 cell 来自定义单元格的渲染方式。
4. 数据 (Data): 你的原始数据数组，通常是一个对象数组。
5. 状态管理 (State Management): React Table 内部管理着许多状态（如排序状态、过滤状态、分页状态等）。你可以选择让 React Table 内部管理这些状态，也可以通过 state 和 onStateChange 选项将状态提升到你自己的 React 组件中进行控制。
6. 功能 Hooks (Feature Hooks): React Table 的功能（如排序、过滤、分页）是通过不同的 “RowModel” Hooks 启用的，例如 getCoreRowModel (基础)、getSortedRowModel (排序)、getFilteredRowModel (过滤)、getPaginationRowModel (分页) 等。你需要在 useReactTable 中显式地引入这些 Hook 返回的函数来启用相应功能。

构建一个基础表格

让我们从创建一个最简单的表格开始。

1. 准备数据和列定义

假设我们有以下用户数据：

javascript
// data.js
export const defaultData = [
{ id: 1, firstName: 'Tanner', lastName: 'Linsley', age: 33, visits: 100, progress: 50, status: 'Married' },
{ id: 2, firstName: 'Kevin', lastName: 'Vandy', age: 27, visits: 200, progress: 75, status: 'Single' },
{ id: 3, firstName: 'John', lastName: 'Doe', age: 45, visits: 50, progress: 20, status: 'Complicated' },
{ id: 4, firstName: 'Jane', lastName: 'Doe', age: 42, visits: 150, progress: 90, status: 'Married' },
];

现在，定义表格的列。ColumnDef 是一个类型，你需要从 @tanstack/react-table 导入它（如果使用 TypeScript）。

“`javascript
// columns.js
import { createColumnHelper } from ‘@tanstack/react-table’;

// 假设你的数据类型是这样的
type Person = {
id: number;
firstName: string;
lastName: string;
age: number;
visits: number;
progress: number;
status: string;
};

const columnHelper = createColumnHelper(); // 使用 createColumnHelper 提供类型安全和智能提示

export const columns = [
columnHelper.accessor(‘firstName’, {
header: () => ‘First Name’, // 表头显示内容
cell: info => info.getValue(), // 单元格显示内容 (默认行为)
footer: info => info.column.id, // 可选的表尾
}),
columnHelper.accessor(row => row.lastName, { // 也可以使用 accessorFn
id: ‘lastName’, // 当使用 accessorFn 时，最好提供一个唯一的 id
header: () => Last Name, // 表头可以是 JSX
cell: info => {info.getValue()}, // 自定义单元格渲染
footer: info => info.column.id,
}),
columnHelper.accessor(‘age’, {
header: () => ‘Age’,
cell: info => info.renderValue(), // renderValue 是 getValue 的别名
footer: info => info.column.id,
}),
columnHelper.accessor(‘visits’, {
header: () => Visits,
footer: info => info.column.id,
}),
columnHelper.accessor(‘status’, {
header: ‘Status’, // header 可以是字符串
footer: info => info.column.id,
}),
columnHelper.accessor(‘progress’, {
header: ‘Profile Progress’,
footer: info => info.column.id,
}),
];
“`

注意:
* accessorKey: 直接对应数据对象中的键名。
* accessorFn: 一个函数，接收原始行数据，返回该单元格的值。当需要计算或组合字段时很有用。如果使用 accessorFn，强烈建议提供一个唯一的 id。
* header: 定义表头单元格的内容。可以是一个字符串、一个函数返回字符串/JSX。
* cell: 定义数据单元格的内容。接收一个包含 getValue()、renderValue()、row、column 等信息的对象，返回字符串/JSX。
* createColumnHelper: (可选，推荐 TypeScript 用户使用) 这是一个辅助函数，可以提供更好的类型推断和代码提示。

2. 创建表格组件

现在，在你的 React 组件中使用 useReactTable。

“`jsx
// BasicTable.jsx
import React, { useState, useMemo } from ‘react’;
import {
useReactTable,
getCoreRowModel,
flexRender, // 重要的渲染辅助函数
} from ‘@tanstack/react-table’;
import { defaultData } from ‘./data’; // 导入数据
import { columns } from ‘./columns’; // 导入列定义
import ‘./table.css’; // 稍后添加一些基础样式

function BasicTable() {
// 推荐使用 useMemo 包装数据和列定义，避免不必要的重渲染
const data = useMemo(() => defaultData, []);
const tableColumns = useMemo(() => columns, []);

// 使用 useReactTable Hook
const table = useReactTable({
data, // 数据
columns: tableColumns, // 列定义
getCoreRowModel: getCoreRowModel(), // 核心行模型，必须启用
// debugTable: true, // 可选：在控制台输出调试信息
});

// table 实例包含了渲染所需的所有内容
// console.log(table); // 可以打印出来看看里面有什么

return (

    {/* 表体 */}
    <tbody>
      {table.getRowModel().rows.map(row => (
        <tr key={row.id}>
          {row.getVisibleCells().map(cell => (
            <td key={cell.id}>
              {flexRender( // 使用 flexRender 渲染单元格内容
                cell.column.columnDef.cell,
                cell.getContext()
              )}
            </td>
          ))}
        </tr>
      ))}
    </tbody>

    {/* 表尾 (可选) */}
    {/* <tfoot>
      {table.getFooterGroups().map(footerGroup => (
        <tr key={footerGroup.id}>
          {footerGroup.headers.map(header => (
            <th key={header.id} colSpan={header.colSpan}>
              {header.isPlaceholder
                ? null
                : flexRender(
                    header.column.columnDef.footer,
                    header.getContext()
                  )}
            </th>
          ))}
        </tr>
      ))}
    </tfoot> */}
  </table>
</div>

);
}

export default EnhancedTable;
“`

添加一个简单的 CSS 类来指示可点击：

css
/* table.css (补充) */
.cursor-pointer {
cursor: pointer;
}
.select-none {
user-select: none; /* 防止点击时选中文本 */
}

现在，点击表头应该可以按升序、降序或取消排序来对表格数据进行排序了。

2. 添加全局过滤 (Global Filtering)

全局过滤允许用户输入一个关键词，在所有列中搜索匹配项。

1. 导入 getFilteredRowModel: 从 @tanstack/react-table 导入。
2. 添加到 useReactTable: 加入 getFilteredRowModel: getFilteredRowModel()。
3. 管理全局过滤状态:
   • 使用 useState 存储 globalFilter 字符串。
   • 将其传入 useReactTable 的 state 中，并提供 onGlobalFilterChange 更新函数。
4. 添加过滤输入框: 在表格外部或上方创建一个 input 元素，将其 value 绑定到 globalFilter 状态，并在 onChange 事件中调用 setGlobalFilter。

“`jsx
// EnhancedTable.jsx (继续修改)
import React, { useState, useMemo } from ‘react’;
import {
// … 其他导入
getFilteredRowModel, // 1. 导入过滤模型
} from ‘@tanstack/react-table’;
// … 其他代码

function EnhancedTable() {
// … data, tableColumns, sorting 状态

// 2. 管理全局过滤状态
const [globalFilter, setGlobalFilter] = useState(”);

const table = useReactTable({
data,
columns: tableColumns,
state: {
sorting,
globalFilter, // 3. 传入全局过滤状态
},
onSortingChange: setSorting,
onGlobalFilterChange: setGlobalFilter, // 4. 提供更新函数
getCoreRowModel: getCoreRowModel(),
getSortedRowModel: getSortedRowModel(),
getFilteredRowModel: getFilteredRowModel(), // 5. 启用过滤模型
// debugTable: true,
});

return (

  <table>
    {/* 表格渲染逻辑不变 */}
    {/* ... thead ... */}
    {/* ... tbody ... */}
  </table>
  {/* 其他功能，如分页，可以放在这里 */}
</div>

  {/* 3. 添加分页控件 */}
  <div className="pagination-controls" style={{ marginTop: '1rem', display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
    <button onClick={() => table.setPageIndex(0)} disabled={!table.getCanPreviousPage()}>
      {'<<'} First
    </button>
    <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>
      {'<'} Previous
    </button>
    <span>
      Page{' '}
      <strong>
        {currentPageIndex + 1} of {totalPages}
      </strong>{' '}
    </span>
    <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
      Next {'>'}
    </button>
    <button onClick={() => table.setPageIndex(totalPages - 1)} disabled={!table.getCanNextPage()}>
      Last {'>>'}
    </button>

    <span style={{ marginLeft: '1rem' }}>
      | Go to page:{' '}
      <input
        type="number"
        defaultValue={currentPageIndex + 1}
        onChange={e => {
          const page = e.target.value ? Number(e.target.value) - 1 : 0;
          // 确保页码在有效范围内
          const safePage = Math.max(0, Math.min(page, totalPages - 1));
          table.setPageIndex(safePage);
        }}
        style={{ width: '60px', padding: '2px 4px' }}
        min={1}
        max={totalPages}
      />
    </span>{' '}
    <select
      value={currentPageSize}
      onChange={e => {
        table.setPageSize(Number(e.target.value));
      }}
      style={{ padding: '4px 8px' }}
    >
      {[5, 10, 20, 50].map(size => (
        <option key={size} value={size}>
          Show {size}
        </option>
      ))}
    </select>
  </div>
  {/* 显示当前可见行数和总行数 (可选) */}
  {/* <div>Showing {table.getRowModel().rows.length} of {table.getPrePaginationRowModel().rows.length} total rows</div> */}
</div>

   {/* 显示选中的行数和 ID (可选) */}
  <div style={{marginTop: '1rem'}}>
    <p>{Object.keys(rowSelection).length} row(s) selected.</p>
    {/* <pre>{JSON.stringify(rowSelection, null, 2)}</pre> */}
  </div>
</div>