Skip to content

Latest commit

 

History

History
307 lines (246 loc) · 15.2 KB

index.zh-CN.md

File metadata and controls

307 lines (246 loc) · 15.2 KB
Raw
category cols type title subtitle cover
Components
1
数据展示
Table
表格

展示行列数据。

设计师专属

安装 Kitchen Sketch 插件 💎，两步就可以自动生成 Ant Design 表格组件。

何时使用

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

如何使用

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

API

另外我们封装了 ProTable，在 antd Table 之上扩展了更多便捷易用的功能，内置搜索、筛选、刷新等常用表格行为，并为多种类型数据展示提供了内置格式化，欢迎尝试使用。

Table

参数 说明 类型 默认值 版本
bordered 是否展示外边框和列边框 boolean false
columns 表格列的配置描述，具体项见下表 ColumnsType[] -
components 覆盖默认的 table 元素 TableComponents -
dataSource 数据数组 object[] -
expandable 配置展开属性 expandable -
footer 表格尾部 function(currentPageData) -
getPopupContainer 设置表格内各类浮层的渲染节点，如筛选菜单 (triggerNode) => HTMLElement () => TableHtmlElement
loading 页面是否加载中 boolean | object (更多) false
locale 默认文案设置，目前包括排序、过滤、空数据文案 object filterConfirm: 确定
filterReset: 重置
emptyText: 暂无数据
默认值
pagination 分页器，参考配置项或 pagination 文档，设为 false 时不展示和进行分页 object -
rowClassName 表格行的类名 function(record, index): string -
rowKey 表格行 key 的取值，可以是字符串或一个函数 string | function(record): string key
rowSelection 表格行是否可选择，配置项 object -
scroll 表格是否可滚动，也可以指定滚动区域的宽、高，配置项 object -
showHeader 是否显示表头 boolean true
showSorterTooltip 表头是否显示下一次排序的 tooltip 提示 boolean true
size 表格大小 default | middle | small default
sortDirections 支持的排序方式，取值为 ascend descend Array [ascend, descend]
sticky 设置粘性头部和滚动条 boolean | {offsetHeader?: number, offsetScroll?: number, getContainer?: () => HTMLElement} - 4.6.0 (getContainer: 4.7.0)
summary 总结栏 (currentData) => ReactNode -
tableLayout 表格元素的 table-layout 属性，设为 fixed 表示内容不会影响列的布局 - | auto | fixed 无
固定表头/列或使用了 column.ellipsis 时，默认值为 fixed
title 表格标题 function(currentPageData) -
onChange 分页、排序、筛选变化时触发 function(pagination, filters, sorter, extra: { currentDataSource: [], action: paginate | sort | filter }) -
onHeaderRow 设置头部行属性 function(column, index) -
onRow 设置行属性 function(record, index) -

onRow 用法

适用于 onRow onHeaderRow onCell onHeaderCell。

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

Column

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

参数 说明 类型 默认值 版本
align 设置列的对齐方式 left | right | center left
className 列样式类名 string -
colSpan 表头列合并,设置为 0 时，不渲染 number -
dataIndex 列数据在数据项中对应的路径，支持通过数组查询嵌套路径 string | string[] -
defaultFilteredValue 默认筛选值 string[] -
defaultSortOrder 默认排序顺序 ascend | descend -
ellipsis 超过宽度将自动省略，暂不支持和排序筛选一起使用。
设置为 true 或 { showTitle?: boolean } 时，表格布局将变成 tableLayout="fixed"。		 boolean | { showTitle?: boolean } false showTitle: 4.3.0
filterDropdown 可以自定义筛选菜单，此函数只负责渲染图层，需要自行编写各种交互 ReactNode | (props: FilterDropdownProps) => ReactNode -
filterDropdownVisible 用于控制自定义筛选菜单是否可见 boolean -
filtered 标识数据是否经过过滤，筛选图标会高亮 boolean false
filteredValue 筛选的受控属性，外界可用此控制列的筛选状态，值为已筛选的 value 数组 string[] -
filterIcon 自定义 filter 图标。 ReactNode | (filtered: boolean) => ReactNode false
filterMultiple 是否多选 boolean true
filters 表头的筛选菜单项 object[] -
fixed （IE 下无效）列是否固定，可选 true (等效于 left) left right boolean | string false
key React 需要的 key，如果已经设置了唯一的 dataIndex，可以忽略这个属性 string -
render 生成复杂数据的渲染函数，参数分别为当前行的值，当前行数据，行索引，@return 里面可以设置表格行/列合并 function(text, record, index) {} -
responsive 响应式 breakpoint 配置列表。未设置则始终可见。 Breakpoint[] - 4.2.0
shouldCellUpdate 自定义单元格渲染时机 (record, prevRecord) => boolean - 4.3.0
showSorterTooltip 表头显示下一次排序的 tooltip 提示, 覆盖 table 中showSorterTooltip boolean true
sortDirections 支持的排序方式，覆盖Table中sortDirections， 取值为 ascend descend Array [ascend, descend]
sorter 排序函数，本地排序使用一个函数(参考 Array.sort 的 compareFunction)，需要服务端排序可设为 true function | boolean -
sortOrder 排序的受控属性，外界可用此控制列的排序，可设置为 ascend descend false boolean | string -
title 列头显示文字（函数用法 3.10.0 后支持） ReactNode | ({ sortOrder, sortColumn, filters }) => ReactNode -
width 列宽度（指定了也不生效？） string | number -
onCell 设置单元格属性 function(record, rowIndex) -
onFilter 本地模式下，确定筛选的运行函数 function -
onFilterDropdownVisibleChange 自定义筛选菜单可见变化时调用 function(visible) {} -
onHeaderCell 设置头部单元格属性 function(column) -

ColumnGroup

参数 说明 类型 默认值
title 列头显示文字 ReactNode -

pagination

分页的配置项。

参数 说明 类型 默认值
position 指定分页显示的位置， 取值为topLeft | topCenter | topRight |bottomLeft | bottomCenter | bottomRight Array [bottomRight]

更多配置项，请查看 Pagination。

expandable

展开功能的配置。

参数 说明 类型 默认值
childrenColumnName 指定树形结构的列名 string children
defaultExpandAllRows 初始时，是否展开所有行 boolean false
defaultExpandedRowKeys 默认展开的行 string[] -
expandedRowClassName 展开行的 className function(record, index, indent): string -
expandedRowKeys 展开的行，控制属性 string[] -
expandedRowRender 额外的展开行 function(record, index, indent, expanded): ReactNode -
expandIcon 自定义展开图标，参考示例 function(props): ReactNode -
expandIconColumnIndex 自定义展开按钮的列顺序，-1 时不展示 number -
expandRowByClick 通过点击行来展开子行 boolean false
indentSize 展示树形数据时，每层缩进的宽度，以 px 为单位 number 15
rowExpandable 设置是否允许行展开 (record) => boolean -
onExpand 点击展开图标时触发 function(expanded, record) -
onExpandedRowsChange 展开的行变化时触发 function(expandedRows) -

rowSelection

选择功能的配置。

参数 说明 类型 默认值 版本
checkStrictly checkable 状态下节点选择完全受控（父子数据选中状态不再关联） boolean true 4.4.0
columnTitle 自定义列表选择框标题 ReactNode -
columnWidth 自定义列表选择框宽度 string | number 60px
fixed 把选择框列固定在左边 boolean -
getCheckboxProps 选择框的默认属性配置 function(record) -
hideSelectAll 隐藏全选勾选框与自定义选择项 boolean false 4.3.0
preserveSelectedRowKeys 当数据被删除时仍然保留选项的 key boolean - 4.4.0
renderCell 渲染勾选框，用法与 Column 的 render 相同 function(checked, record, index, originNode) {} - 4.1.0
selectedRowKeys 指定选中项的 key 数组，需要和 onChange 进行配合 string[] | number[] []
selections 自定义选择项 配置项, 设为 true 时使用默认选择项 object[] | boolean true
type 多选/单选，checkbox or radio string checkbox
onChange 选中项发生变化时的回调 function(selectedRowKeys, selectedRows) -
onSelect 用户手动选择/取消选择某行的回调 function(record, selected, selectedRows, nativeEvent) -
onSelectAll 用户手动选择/取消选择所有行的回调 function(selected, selectedRows, changeRows) -
onSelectInvert 用户手动选择反选的回调 function(selectedRowKeys) -

scroll

参数 说明 类型 默认值
scrollToFirstRowOnChange 当分页、排序、筛选变化后是否滚动到表格顶部 boolean -
x 设置横向滚动，也可用于指定滚动区域的宽，可以设置为像素值，百分比，true 和 'max-content' number | true -
y 设置纵向滚动，也可用于指定滚动区域的高，可以设置为像素值 number -

selection

参数 说明 类型 默认值
key React 需要的 key，建议设置 string -
text 选择项显示的文字 ReactNode -
onSelect 选择项点击回调 function(changeableRowKeys) -

在 TypeScript 中使用

import { Table } from 'antd';
import { ColumnsType } from 'antd/es/table';

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

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

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

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

TypeScript 里使用 Table 的 CodeSandbox 实例。

注意

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

控制台警告

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

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

从 v3 升级到 v4

Table 移除了在 v3 中废弃的 onRowClick、onRowDoubleClick、onRowMouseEnter、onRowMouseLeave 等方法。如果你使用的 api 为文档中列举的 api，那你不用担心会丢失功能。

此外，比较重大的改动为 dataIndex 从支持路径嵌套如 user.age 改成了数组路径如 ['user', 'age']。以解决过去属性名带 . 需要额外的数据转化问题。

FAQ

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

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

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

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

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

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

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

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

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