ant-design/components/table/index.en-US.md
二货爱吃白萝卜 20561d6f9d
docs: Fix component doc alignment & support import usage (#48004)
* docs: init ref

* docs all support

* docs: fix link show
2024-03-22 14:22:42 +08:00

21 KiB
Raw Blame History

category group title description cover coverDark
Components Data Display Table A table displays rows of data. https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*3yz3QqMlShYAAAAAAAAAAAAADrJ8AQ/original https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*Sv8XQ50NB40AAAAAAAAAAAAADrJ8AQ/original

When To Use

  • To display a collection of structured data.
  • To sort, search, paginate, filter data.

How To Use

Specify dataSource of Table as an array of data.

const dataSource = [
  {
    key: '1',
    name: 'Mike',
    age: 32,
    address: '10 Downing Street',
  },
  {
    key: '2',
    name: 'John',
    age: 42,
    address: '10 Downing Street',
  },
];

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    key: 'name',
  },
  {
    title: 'Age',
    dataIndex: 'age',
    key: 'age',
  },
  {
    title: 'Address',
    dataIndex: 'address',
    key: 'address',
  },
];

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

Promotion

Examples

Basic Usage JSX style API selection Selection and operation Custom selection Selection Perf Filter and sorter Filter in Tree Filter search Multiple sorter Reset filters and sorters Customized filter panel Ajax size size border, title and footer Expandable Row Order Specific Column colSpan and rowSpan Tree data Tree data ellipsis debug demo Fixed Header Fixed Columns Stack Fixed Columns Fixed Columns and Header Hidden Columns Grouping table head Editable Cells Editable Rows Nested tables Drag sorting Drag sorting with handler Resizable column ellipsis column ellipsis column custom tooltip Summary Virtual list Responsive Nested Bordered Table Debug Pagination Settings Custom selection group Fixed header and scroll bar with the page Dynamic Settings selections with icon Component Token

API

Common props refCommon props

Table

Property Description Type Default Version
bordered Whether to show all table borders boolean false
columns Columns of table ColumnsType[] -
components Override default table elements TableComponents -
dataSource Data record array to be displayed object[] -
expandable Config expandable content expandable -
footer Table footer renderer function(currentPageData) -
getPopupContainer The render container of dropdowns in table (triggerNode) => HTMLElement () => TableHtmlElement
loading Loading status of table boolean | Spin Props false
locale The i18n text including filter, sort, empty text, etc object Default Value
pagination Config of pagination. You can ref table pagination config or full pagination document, hide it by setting it to false object | false -
rowClassName Row's className function(record, index): string -
rowKey Row's unique key, could be a string or function that returns a string string | function(record): string key
rowSelection Row selection config object -
scroll Whether the table can be scrollable, config object -
showHeader Whether to show table header boolean true
showSorterTooltip The header show next sorter direction tooltip. It will be set as the property of Tooltip if its type is object boolean | Tooltip props true
size Size of table large | middle | small large
sortDirections Supported sort way, could be ascend, descend Array [ascend, descend]
sticky Set sticky header and scroll bar boolean | {offsetHeader?: number, offsetScroll?: number, getContainer?: () => HTMLElement} - 4.6.0 (getContainer: 4.7.0)
summary Summary content (currentData) => ReactNode -
tableLayout The table-layout attribute of table element - | auto | fixed -
fixed when header/columns are fixed, or using column.ellipsis
title Table title renderer function(currentPageData) -
onChange Callback executed when pagination, filters or sorter is changed function(pagination, filters, sorter, extra: { currentDataSource: [], action: paginate | sort | filter }) -
onHeaderRow Set props on per header row function(columns, index) -
onRow Set props on per row function(record, index) -
virtual Support virtual list boolean - 5.9.0

Table ref

Property Description Type Version
nativeElement The wrap element HTMLDivElement 5.11.0
scrollTo Trigger to scroll to target position. key match with record rowKey (config: { index?: number, key?: React.Key, top?: number }) => void 5.11.0

onRow usage

Same as onRow onHeaderRow onCell onHeaderCell

<Table
  onRow={(record, rowIndex) => {
    return {
      onClick: (event) => {}, // click row
      onDoubleClick: (event) => {}, // double click row
      onContextMenu: (event) => {}, // right button click row
      onMouseEnter: (event) => {}, // mouse enter row
      onMouseLeave: (event) => {}, // mouse leave row
    };
  }}
  onHeaderRow={(columns, index) => {
    return {
      onClick: () => {}, // click header row
    };
  }}
/>

Column

One of the Table columns prop for describing the table's columns, Column has the same API.

Property Description Type Default Version
align The specify which way that column is aligned left | right | center left
className The className of this column string -
colSpan Span of this column's title number -
dataIndex Display field of the data record, support nest path by string array string | string[] -
defaultFilteredValue Default filtered values string[] -
filterResetToDefaultFilteredValue click the reset button, whether to restore the default filter boolean false
defaultSortOrder Default order of sorted values ascend | descend -
ellipsis The ellipsis cell content, not working with sorter and filters for now.
tableLayout would be fixed when ellipsis is true or { showTitle?: boolean }
boolean | {showTitle?: boolean } false showTitle: 4.3.0
filterDropdown Customized filter overlay ReactNode | (props: FilterDropdownProps) => ReactNode -
filterDropdownOpen Whether filterDropdown is visible boolean -
filtered Whether the dataSource is filtered boolean false
filteredValue Controlled filtered value, filter icon will highlight string[] -
filterIcon Customized filter icon ReactNode | (filtered: boolean) => ReactNode -
filterOnClose Whether to trigger filter when the filter menu closes boolean true 5.15.0
filterMultiple Whether multiple filters can be selected boolean true
filterMode To specify the filter interface 'menu' | 'tree' 'menu' 4.17.0
filterSearch Whether to be searchable for filter menu boolean | function(input, record):boolean false boolean:4.17.0 function:4.19.0
filters Filter menu config object[] -
fixed (IE not support) Set column to be fixed: true(same as left) 'left' 'right' boolean | string false
key Unique key of this column, you can ignore this prop if you've set a unique dataIndex string -
render Renderer of the table cell. The return value should be a ReactNode function(text, record, index) {} -
responsive The list of breakpoints at which to display this column. Always visible if not set Breakpoint[] - 4.2.0
rowScope Set scope attribute for all cells in this column row | rowgroup - 5.1.0
shouldCellUpdate Control cell render logic (record, prevRecord) => boolean - 4.3.0
showSorterTooltip If header show next sorter direction tooltip, override showSorterTooltip in table boolean | Tooltip props true
sortDirections Supported sort way, override sortDirections in Table, could be ascend, descend Array [ascend, descend]
sorter Sort function for local sort, see Array.sort's compareFunction. If it is server-side sorting, set to true, but if you want to support multi-column sorting, you can set it to { multiple: number } function | boolean | { compare: function, multiple: number } -
sortOrder Order of sorted values: ascend descend null ascend | descend | null -
sortIcon Customized sort icon (props: { sortOrder }) => ReactNode - 5.6.0
title Title of this column ReactNode | ({ sortOrder, sortColumn, filters }) => ReactNode -
width Width of this column (width not working?) string | number -
hidden Hidden this column boolean false 5.13.0
onCell Set props on per cell function(record, rowIndex) -
onFilter Function that determines if the row is displayed when filtered function(value, record) => boolean -
onFilterDropdownOpenChange Callback executed when filterDropdownOpen is changed function(visible) {} -
onHeaderCell Set props on per header cell function(column) -

ColumnGroup

Property Description Type Default
title Title of the column group ReactNode -

pagination

Properties for pagination.

Property Description Type Default
position Specify the position of Pagination, could betopLeft | topCenter | topRight |bottomLeft | bottomCenter | bottomRight Array [bottomRight]

More about pagination, please check Pagination.

expandable

Properties for expandable.

Property Description Type Default Version
childrenColumnName The column contains children to display string children
columnTitle Set the title of the expand column ReactNode - 4.23.0
columnWidth Set the width of the expand column string | number -
defaultExpandAllRows Expand all rows initially boolean false
defaultExpandedRowKeys Initial expanded row keys string[] -
expandedRowClassName Expanded row's className function(record, index, indent): string -
expandedRowKeys Current expanded row keys string[] -
expandedRowRender Expanded container render for each row function(record, index, indent, expanded): ReactNode -
expandIcon Customize row expand Icon. Ref example function(props): ReactNode -
expandRowByClick Whether to expand row by clicking anywhere in the whole row boolean false
fixed Whether the expansion icon is fixed. Optional true left right boolean | string false 4.16.0
indentSize Indent size in pixels of tree data number 15
rowExpandable Enable row can be expandable (record) => boolean -
showExpandColumn Show expand column boolean true 4.18.0
onExpand Callback executed when the row expand icon is clicked function(record, event) -
onExpandedRowsChange Callback executed when the expanded rows change function(expandedRows) -

rowSelection

Properties for row selection.

Property Description Type Default Version
checkStrictly Check table row precisely; parent row and children rows are not associated boolean true 4.4.0
columnTitle Set the title of the selection column ReactNode | (originalNode: ReactNode) => ReactNode -
columnWidth Set the width of the selection column string | number 32px
fixed Fixed selection column on the left boolean -
getCheckboxProps Get Checkbox or Radio props function(record) -
hideSelectAll Hide the selectAll checkbox and custom selection boolean false 4.3.0
preserveSelectedRowKeys Keep selection key even when it removed from dataSource boolean - 4.4.0
renderCell Renderer of the table cell. Same as render in column function(checked, record, index, originNode) {} - 4.1.0
selectedRowKeys Controlled selected row keys string[] | number[] []
selections Custom selection config, only displays default selections when set to true object[] | boolean -
type checkbox or radio checkbox | radio checkbox
onCell Set props on per cell. Same as onCell in column function(record, rowIndex) - 5.5.0
onChange Callback executed when selected rows change function(selectedRowKeys, selectedRows, info: { type }) - info.type: 4.21.0
onSelect Callback executed when select/deselect one row function(record, selected, selectedRows, nativeEvent) -
onSelectAll Callback executed when select/deselect all rows function(selected, selectedRows, changeRows) -
onSelectInvert Callback executed when row selection is inverted function(selectedRowKeys) -
onSelectNone Callback executed when row selection is cleared function() -
onSelectMultiple Callback executed when row selection is changed by pressing shift function(selected, selectedRows, changeRows) -

scroll

Property Description Type Default
scrollToFirstRowOnChange Whether to scroll to the top of the table when paging, sorting, filtering changes boolean -
x Set horizontal scrolling, can also be used to specify the width of the scroll area, could be number, percent value, true and 'max-content' string | number | true -
y Set vertical scrolling, can also be used to specify the height of the scroll area, could be string or number string | number -

selection

Property Description Type Default
key Unique key of this selection string -
text Display text of this selection ReactNode -
onSelect Callback executed when this selection is clicked function(changeableRowKeys) -

Using in TypeScript

import React from 'react';
import { Table } from 'antd';
import type { 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',
  },
];

const Demo: React.FC = () => (
  <>
    <Table<User> columns={columns} dataSource={data} />
    {/* JSX style usage */}
    <Table<User> dataSource={data}>
      <Table.Column<User> key="name" title="Name" dataIndex="name" />
    </Table>
  </>
);

export default Demo;

Here is the CodeSandbox for TypeScript.

Design Token

Note

According to the React documentation, every child in an array should be assigned a unique key. The values inside the Table's dataSource and columns should follow this rule. By default, dataSource[i].key will be treated as the key value for dataSource.

console warning

If dataSource[i].key is not provided, then you should specify the primary key of dataSource value via rowKey, as shown below. If not, warnings like the one above will show in browser console.

// primary key is uid
return <Table rowKey="uid" />;
// or
return <Table rowKey={(record) => record.uid} />;

FAQ

How to hide pagination when single page or no data?

You can set hideOnSinglePage with pagination prop.

Table will return to first page when filter data.

Table total page count usually reduce after filter data, we by default return to first page in case of current page is out of filtered results.

You may need to keep current page after filtering when fetch data from remote service, please check this demo as workaround.

Also you can use the action from extra param to determine when return to first page.

Why Table pagination show size changer?

In order to improve user experience, Pagination show size changer by default when total > 50 since 4.1.0. You can set showSizeChanger=false to disable this feature.

Why Table fully render when state change?

Table can not tell what state used in columns.render, so it always need fully render to avoid sync issue. You can use column.shouldCellUpdate to control render.

How to handle fixed column display over the mask layout?

Fixed column use z-index to make it over other columns. You will find sometime fixed columns also over your mask layout. You can set z-index on your mask layout to resolve.

How to custom render Table CheckboxFor example, adding Tooltip?

Since 4.1.0, You can use rowSelection.renderCell to custom render Table Checkbox. If you want to add Tooltip, please refer to this demo.

Why does components.body.wrapper report an error when virtual is enabled?

Because virtual table needs to get its ref to do some calculations, so you need to use React.forwardRef wrapper and pass the ref to the dom