表格

展示行列数据。

何时使用

• 当有大量结构化的数据需要展现时；
• 当需要对数据进行排序、搜索、分页、自定义操作等复杂行为时。

如何使用

指定表格的数据源 dataSource 为一个数组。

const dataSource = [
  {
    key: '1',
    name: '胡彦斌',
    age: 32,
    address: '西湖区湖底公园1号',
  },
  {
    key: '2',
    name: '胡彦祖',
    age: 42,
    address: '西湖区湖底公园1号',
  },
];

const columns = [
  {
    title: '姓名',
    dataIndex: 'name',
    key: 'name',
  },
  {
    title: '年龄',
    dataIndex: 'age',
    key: 'age',
  },
  {
    title: '住址',
    dataIndex: 'address',
    key: 'address',
  },
];

<Table dataSource={dataSource} columns={columns} />;

相关推荐

• Kitchen Sketch 插件 💎：设计师神器，两步自动生成 Ant Design 表格组件。
• ProTable 高级表格：在 antd Table 之上扩展了更多便捷易用的功能，内置搜索、筛选、刷新等常用表格行为，并为多种类型数据展示提供了内置格式化。
• S2 多维交叉分析表格：AntV S2 和 Antd Table 有什么区别？

代码演示

• 基本用法 · basic

• JSX 风格的 API · jsx

• 可选择 · row-selection

• 选择和操作 · row-selection-and-operation

• 自定义选择项 · row-selection-custom

• 筛选和排序 · head

• 树型筛选菜单 · filter-in-tree

• 自定义筛选的搜索 · filter-search

• 多列排序 · multiple-sorter

• 可控的筛选和排序 · reset-filter

• 自定义筛选菜单 · custom-filter-panel

• 远程加载数据 · ajax

• 紧凑型 · size

• 带边框 · bordered

• 可展开 · expand

• 特殊列排序 · order-column

• 表格行/列合并 · colspan-rowspan

• 树形数据展示 · tree-data

• 固定表头 · fixed-header

• 自动高度 · auto-height

• 固定列 · fixed-columns

• 堆叠固定列 · fixed-gapped-columns

• 固定头和列 · fixed-columns-header

• 隐藏列 · hidden-columns

• 表头分组 · grouping-columns

• 可编辑单元格 · edit-cell

• 可编辑行 · edit-row

• 嵌套子表格 · nested-table

• 拖拽排序 · drag-sorting

• 列拖拽排序 · drag-column-sorting

• 拖拽手柄列 · drag-sorting-handler

• 单元格自动省略 · ellipsis

• 统一列配置 · column-defaults

• 自定义单元格省略提示 · ellipsis-custom-tooltip

• 自定义空状态 · custom-empty

• 总结栏 · summary

• 虚拟列表 · virtual-list

• 响应式 · responsive

• 分页设置 · pagination

• 随页面滚动的固定表头和滚动条 · sticky

• 动态控制表格属性 · dynamic-settings

• 自定义语义结构的样式和类 · style-class

API

通用属性参考：通用属性

Table

Table ref

onRow 用法

适用于 onRow onHeaderRow onCell onHeaderCell。

<Table
  onRow={(record) => {
    return {
      onClick: (event) => {}, // 点击行
      onDoubleClick: (event) => {},
      onContextMenu: (event) => {},
      onMouseEnter: (event) => {}, // 鼠标移入行
      onMouseLeave: (event) => {},
    };
  }}
  onHeaderRow={(columns, index) => {
    return {
      onClick: () => {}, // 点击表头行
    };
  }}
/>

Column

列描述数据对象，是 columns 中的一项，Column 使用相同的 API。

ColumnGroup

pagination

分页的配置项。

更多配置项，请查看 Pagination。

expandable

展开功能的配置。

rowSelection

选择功能的配置。

scroll

selection

在 TypeScript 中使用

import React from 'react';
import { Table } from 'antd';
import type { TableColumnsType } from 'antd';

interface User {
  key: number;
  name: string;
}

const columns: TableColumnsType<User> = [
  {
    key: 'name',
    title: 'Name',
    dataIndex: 'name',
  },
];

const data: User[] = [
  {
    key: 0,
    name: 'Jack',
  },
];

const Demo: React.FC = () => (
  <>
    <Table<User> columns={columns} dataSource={data} />
    {/* 使用 JSX 风格的 API */}
    <Table<User> dataSource={data}>
      <Table.Column<User> key="name" title="Name" dataIndex="name" />
    </Table>
  </>
);

export default Demo;

TypeScript 里使用 Table 的 CodeSandbox 实例。

Semantic DOM

语义说明来源: vendor/components/table/demo/_semantic.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

声明来源: vendor/components/table/style/index.ts

import { unit } from '@ant-design/cssinjs';

import type { CSSObject } from '@ant-design/cssinjs';

import { FastColor } from '@ant-design/fast-color';

import { clearFix, resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import genBorderedStyle from './bordered';

import genEllipsisStyle from './ellipsis';

import genEmptyStyle from './empty';

import genExpandStyle from './expand';

import genFilterStyle from './filter';

import genFixedStyle from './fixed';

import genPaginationStyle from './pagination';

import genRadiusStyle from './radius';

import genRtlStyle from './rtl';

import genSelectionStyle from './selection';

import genSizeStyle from './size';

import genSorterStyle from './sorter';

import genStickyStyle from './sticky';

import genSummaryStyle from './summary';

import genVirtualStyle from './virtual';

export interface ComponentToken {
  /**
   * @desc 表头背景
   * @descEN Background of table header
   */
  headerBg: string;
  /**
   * @desc 表头文字颜色
   * @descEN Color of table header text
   */
  headerColor: string;
  /**
   * @desc 表头排序激活态背景色
   * @descEN Background color of table header when sorted
   */
  headerSortActiveBg: string;
  /**
   * @desc 表头排序激活态悬浮背景色
   * @descEN Background color of table header when sorted and hovered
   */
  headerSortHoverBg: string;
  /**
   * @desc 表格排序列背景色
   * @descEN Background color of table sorted column
   */
  bodySortBg: string;
  /**
   * @desc 表格行悬浮背景色
   * @descEN Background color of table hovered row
   */
  rowHoverBg: string;
  /**
   * @desc 表格行选中背景色
   * @descEN Background color of table selected row
   */
  rowSelectedBg: string;
  /**
   * @desc 表格行选中悬浮背景色
   * @descEN Background color of table selected row when hovered
   */
  rowSelectedHoverBg: string;
  /**
   * @desc 表格行展开背景色
   * @descEN Background color of table expanded row
   */
  rowExpandedBg: string;
  /**
   * @desc 单元格纵向内间距
   * @descEN Vertical padding of table cell
   */
  cellPaddingBlock: number;
  /**
   * @desc 单元格横向内间距（默认大尺寸）
   * @descEN Horizontal padding of table cell (large size by default)
   */
  cellPaddingInline: number;
  /**
   * @desc 单元格纵向内间距（中等尺寸）
   * @descEN Vertical padding of table cell (middle size)
   */
  cellPaddingBlockMD: number;
  /**
   * @desc 单元格横向内间距（中等尺寸）
   * @descEN Horizontal padding of table cell (middle size)
   */
  cellPaddingInlineMD: number;
  /**
   * @desc 单元格纵向内间距（小尺寸）
   * @descEN Vertical padding of table cell (small size)
   */
  cellPaddingBlockSM: number;
  /**
   * @desc 单元格横向内间距（小尺寸）
   * @descEN Horizontal padding of table cell (small size)
   */
  cellPaddingInlineSM: number;
  /**
   * @desc 表格边框/分割线颜色
   * @descEN Border color of table
   */
  borderColor: string;
  /**
   * @desc 表头圆角
   * @descEN Border radius of table header
   */
  headerBorderRadius: number;
  /**
   * @desc 表格底部背景色
   * @descEN Background of footer
   */
  footerBg: string;
  /**
   * @desc 表格底部文字颜色
   * @descEN Color of footer text
   */
  footerColor: string;
  /**
   * @desc 单元格文字大小（默认大尺寸）
   * @descEN Font size of table cell (large size by default)
   */
  cellFontSize: number;
  /**
   * @desc 单元格文字大小（中等尺寸）
   * @descEN Font size of table cell (middle size)
   */
  cellFontSizeMD: number;
  /**
   * @desc 单元格文字大小（小尺寸）
   * @descEN Font size of table cell (small size)
   */
  cellFontSizeSM: number;
  /**
   * @desc 表头分割线颜色
   * @descEN Split border color of table header
   */
  headerSplitColor: string;
  /**
   * @desc 固定表头排序激活态背景色
   * @descEN Background color of fixed table header when sorted
   */
  fixedHeaderSortActiveBg: string;
  /**
   * @desc 表头过滤按钮悬浮背景色
   * @descEN Background color of table header filter button when hovered
   */
  headerFilterHoverBg: string;
  /**
   * @desc 过滤下拉菜单选项背景
   * @descEN Background of filter dropdown menu item
   */
  filterDropdownMenuBg: string;
  /**
   * @desc 过滤下拉菜单颜色
   * @descEN Color of filter dropdown
   */
  filterDropdownBg: string;
  /**
   * @desc 展开按钮背景色
   * @descEN Background of expand button
   */
  expandIconBg: string;
  /**
   * @desc 选择列宽度
   * @descEN Width of selection column
   */
  selectionColumnWidth: number | string;
  /**
   * @desc Sticky 模式下滚动条背景色
   * @descEN Background of sticky scrollbar
   */
  stickyScrollBarBg: string;
  /**
   * @desc Sticky 模式下滚动条圆角
   * @descEN Border radius of sticky scrollbar
   */
  stickyScrollBarBorderRadius: number;

  /** @internal */
  expandIconMarginTop: number;
  /** @internal */
  expandIconHalfInner: number;
  /** @internal */
  expandIconSize: number;
  /** @internal */
  expandIconScale: number;
  /** @internal */
  headerIconColor: string;
  /** @internal */
  headerIconHoverColor: string;
}

export interface TableToken extends FullToken<'Table'> {
  tableFontSize: number;
  tableBg: string;
  tableRadius: number;
  tablePaddingHorizontal: number;
  tablePaddingVertical: number;
  tablePaddingHorizontalMiddle: number;
  tablePaddingVerticalMiddle: number;
  tablePaddingHorizontalSmall: number;
  tablePaddingVerticalSmall: number;
  tableBorderColor: string;
  tableHeaderTextColor: string;
  tableHeaderBg: string;
  tableFooterTextColor: string;
  tableFooterBg: string;
  tableHeaderCellSplitColor: string;
  tableHeaderSortBg: string;
  tableHeaderSortHoverBg: string;
  tableBodySortBg: string;
  tableFixedHeaderSortActiveBg: string;
  tableHeaderFilterActiveBg: string;
  tableFilterDropdownBg: string;
  tableFilterDropdownHeight: number | string;
  tableRowHoverBg: string;
  tableSelectedRowBg: string;
  tableSelectedRowHoverBg: string;

  tableFontSizeMiddle: number;
  tableFontSizeSmall: number;
  tableSelectionColumnWidth: number | string;
  tableExpandIconBg: string;
  tableExpandColumnWidth: number | string;
  tableExpandedRowBg: string;
  tableFilterDropdownWidth: number;
  tableFilterDropdownSearchWidth: number;

  // Z-Index
  zIndexTableFixed: number;

  // Virtual Scroll Bar
  tableScrollThumbSize: number;
  tableScrollThumbBg: string;
  tableScrollThumbBgHover: string;
  tableScrollBg: string;
}

注意

按照 React 的规范，所有的列表必须绑定 key。在 Table 中，dataSource 和 columns 里的数据值都需要指定 key 值。对于 dataSource 默认将每列数据的 key 属性作为唯一的标识。

如果 dataSource[i].key 没有提供，你应该使用 rowKey 来指定 dataSource 的主键，如下所示。若没有指定，控制台会出现以上的提示，表格组件也会出现各类奇怪的错误。

// 比如你的数据主键是 uid
return <Table rowKey="uid" />;
// 或
return <Table rowKey={(record) => record.uid} />;

FAQ

如何在没有数据或只有一页数据时隐藏分页栏

你可以设置 pagination 的 hideOnSinglePage 属性为 true。

表格过滤时会回到第一页？

前端过滤时通常条目总数会减少，从而导致总页数小于筛选前的当前页数，为了防止当前页面没有数据，我们默认会返回第一页。

如果你在使用远程分页，很可能需要保持当前页面，你可以参照这个 受控例子 控制当前页面不变。

表格分页为何会出现 size 切换器？

自 4.1.0 起，Pagination 在 total 大于 50 条时会默认显示 size 切换器以提升用户交互体验。如果你不需要该功能，可以通过设置 showSizeChanger 为 false 来关闭。

为什么 更新 state 会导致全表渲染？

由于 columns 支持 render 方法，因而 Table 无法知道哪些单元会受到影响。你可以通过 column.shouldCellUpdate 来控制单元格的渲染。

如何排查 Table 性能问题？

React DevTools 在分析复杂表格时可能带来额外开销，尤其是行列数量较多的场景。若你遇到明显卡顿，建议先关闭 React DevTools，或在干净的浏览器环境中重新测试。如果在正常运行环境下仍能稳定复现性能问题，欢迎提供最小复现以便我们继续排查。

固定列穿透到最上层该怎么办？

固定列通过 z-index 属性将其悬浮于非固定列之上，这使得有时候你会发现在 Table 上放置遮罩层时固定列会被透过的情况。为遮罩层设置更高的 z-index 覆盖住固定列即可。

如何自定义渲染可选列的勾选框（比如增加 Tooltip）？

自 4.1.0 起，可以通过 rowSelection 的 renderCell 属性控制，可以参考此处 Demo 实现展示 Tooltip 需求或其他自定义的需求。

为什么 components.body.wrapper 或 components.body.row 在 virtual 开启时会报错？

因为虚拟表格需要获取其 ref 做一些计算，所以你需要使用 React.forwardRef 包裹并传递 ref 到 dom。如以下代码：

const EditableRow = React.forwardRef<HTMLTableRowElement, EditableRowProps>(
  ({ index, ...props }, ref) => {
    const [form] = Form.useForm();
    return (
      <Form form={form} component={false}>
        <EditableContext.Provider value={form}>
          <tr {...props} ref={ref} />
        </EditableContext.Provider>
      </Form>
    );
  },
);

对于固定行高纵向滚动的场景，可以使用以下方法：

<Table
  //@ts-ignore // 这个属性未导出，但能透传给内部的虚拟滚动组件
  listItemHeight={36} // 帮助虚拟滚动正确计算高度，每行固定高度36px
/>

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/table/Column.ts
• vendor/components/table/ColumnGroup.ts
• vendor/components/table/ExpandIcon.tsx
• vendor/components/table/InternalTable.tsx
• vendor/components/table/hooks/useFilter/FilterDropdown.tsx
• vendor/components/table/hooks/useFilter/FilterSearch.tsx
• vendor/components/table/hooks/useFilter/FilterWrapper.tsx
• vendor/components/table/hooks/useFilter/index.tsx
• vendor/components/table/hooks/useLazyKVMap.ts
• vendor/components/table/hooks/useSelection.tsx
• vendor/components/table/hooks/useSorter.tsx
• vendor/components/table/interface.ts
• vendor/components/table/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。