Table

何时使用 {#when-to-use}

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

如何使用 {#how-to-use}

指定表格的数据源 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} />;

相关推荐 {#promotion}

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

代码演示 {#examples}

<code src="./demo/basic.tsx">基本用法</code> <code src="./demo/jsx.tsx">JSX 风格的 API</code> <code src="./demo/row-selection.tsx">可选择</code> <code src="./demo/row-selection-and-operation.tsx">选择和操作</code> <code src="./demo/row-selection-custom.tsx">自定义选择项</code> <code src="./demo/row-selection-debug.tsx" debug>选择性能</code> <code src="./demo/head.tsx">筛选和排序</code> <code src="./demo/filter-in-tree.tsx">树型筛选菜单</code> <code src="./demo/filter-search.tsx">自定义筛选的搜索</code> <code src="./demo/multiple-sorter.tsx">多列排序</code> <code src="./demo/reset-filter.tsx">可控的筛选和排序</code> <code src="./demo/custom-filter-panel.tsx">自定义筛选菜单</code> <code src="./demo/ajax.tsx">远程加载数据</code> <code src="./demo/size.tsx">紧凑型</code> <code src="./demo/narrow.tsx" debug>紧凑型</code> <code src="./demo/bordered.tsx">带边框</code> <code src="./demo/expand.tsx">可展开</code> <code src="./demo/expand-sticky.tsx" debug>可自定义展开位置</code> <code src="./demo/order-column.tsx">特殊列排序</code> <code src="./demo/colspan-rowspan.tsx">表格行/列合并</code> <code src="./demo/tree-data.tsx">树形数据展示</code> <code src="./demo/tree-table-ellipsis.tsx" debug>树形数据省略情况测试</code> <code src="./demo/tree-table-preserveSelectedRowKeys.tsx" debug>树形数据保留key测试</code> <code src="./demo/fixed-header.tsx">固定表头</code> <code src="./demo/fixed-columns.tsx">固定列</code> <code src="./demo/fixed-gapped-columns.tsx" version="5.14.0">堆叠固定列</code> <code src="./demo/fixed-columns-header.tsx">固定头和列</code> <code src="./demo/hidden-columns.tsx" version="5.13.0">隐藏列</code> <code src="./demo/grouping-columns.tsx">表头分组</code> <code src="./demo/edit-cell.tsx">可编辑单元格</code> <code src="./demo/edit-row.tsx">可编辑行</code> <code src="./demo/nested-table.tsx">嵌套子表格</code> <code src="./demo/drag-sorting.tsx">拖拽排序</code> <code src="./demo/drag-column-sorting.tsx">列拖拽排序</code> <code src="./demo/drag-sorting-handler.tsx">拖拽手柄列</code> <code src="./demo/ellipsis.tsx">单元格自动省略</code> <code src="./demo/ellipsis-custom-tooltip.tsx">自定义单元格省略提示</code> <code src="./demo/custom-empty.tsx">自定义空状态</code> <code src="./demo/summary.tsx">总结栏</code> <code src="./demo/virtual-list.tsx" version="5.9.0">虚拟列表</code> <code src="./demo/responsive.tsx">响应式</code> <code src="./demo/nest-table-border-debug.tsx" debug>嵌套带边框的表格 Debug</code> <code src="./demo/pagination.tsx">分页设置</code> <code src="./demo/row-selection-custom-debug.tsx" debug>自定义选择项组</code> <code src="./demo/sticky.tsx">随页面滚动的固定表头和滚动条</code> <code src="./demo/dynamic-settings.tsx">动态控制表格属性</code> <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code> <code src="./demo/selections-debug.tsx" debug>带下拉箭头的表头</code> <code src="./demo/component-token.tsx" debug>组件 Token</code> <code src="./demo/measure-row-render.tsx" debug>measureRowRender</code>

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 中使用 {#using-in-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} />
    <Table<User> dataSource={data}>
      <Table.Column<User> key="name" title="Name" dataIndex="name" />
    </Table>
  </>
);

export default Demo;

TypeScript 里使用 Table 的 CodeSandbox 实例。

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

主题变量（Design Token）{#design-token}

<ComponentTokenTable component="Table"></ComponentTokenTable>

注意 {#note}

按照 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

如何在没有数据或只有一页数据时隐藏分页栏 {#faq-hide-pagination}

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

表格过滤时会回到第一页？ {#faq-filter-to-first-page}

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

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

表格分页为何会出现 size 切换器？ {#faq-size-changer}

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

为什么 更新 state 会导致全表渲染？ {#faq-state-update-rerender}

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

固定列穿透到最上层该怎么办？ {#faq-fixed-column-zindex}

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

如何自定义渲染可选列的勾选框（比如增加 Tooltip）？ {#faq-custom-checkbox-render}

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

为什么 components.body.wrapper 或 components.body.row 在 virtual 开启时会报错？ {#faq-virtual-wrapper-ref}

因为虚拟表格需要获取其 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
/>