Skip to main content

ProTable 进阶表格

使用场景#

ProTable 负责将数据渲染为 HTML 表格,其核心功能是将结构化的数据用表格的方式展现在页面中,并以组件 props 的形式提供了丰富的表格功能,例如排序,过滤,滚动,锁列,行多选等。

在实现层面,ProTable 是对 ali-react-table 的封装,除了保留 基础的表格特性 之外,ProTable 也默认集成了 大量表格功能拓展

注意事项#

  • 推荐为 ProTable 设置 primaryKey 作为每一行数据的唯一标识字段
  • 推荐为 ProTable 设置 defaultColumnWidth 作为每一列的默认宽度
  • columns 只支持普通的数组写法
    • 可以通过 ProTable.parseColumns 从 JSX 中解析出 columns 数组
  • 推荐使用 column.code 来代替 column.dataIndex
    • 两者作用相同
    • 本页文档示例中 code 和 dataIndex 两种用法都有出现,但在实际业务中推荐使用 code

设置行属性#

通过 getRowProps 可以设置 tr 元素的属性

<ProTable
getCellProps={(row, rowIndex) => {
return {
className: 'highlight',
style: { color: '#134589' },
onClick: (e) => {},
onDoubleClick: (e) => {},
onContextMenu: (e) => {},
};
}}
/>

表格的拓展功能#

ProTable 集成了所有 ali-react-table 默认提供的表格功能,例如行多选、树状模式、行详情等。 这些功能的相关文档很多,在本页面中就不再重复,具体请移步 ali-react-table 相关文档

在复杂场景下,例如需要对表格添加自定义的拓展,可以使用 BaseTable 组件,API 可以 在这里查看

BaseTable 引入方式为 import { BaseTable } from '@rexd/core'。 @rexd/core 导出的 BaseTable 组件用法与开源版本表格相同,但 @rexd/core 对表格的默认样式进行了定制。此外,切换到 BaseTable 时,注意 BaseTable 只支持 column.code。

虚拟滚动#

数据量较大时,ProTable 会自动开启虚拟滚动。

  • 超过 100 行自动开启纵向的虚拟滚动
  • 超过 100 列自动开启横向的虚拟滚动

如果不需要虚拟滚动,可以设置 useVirtual={false} 进行关闭。 useVirtual 用法详见 虚拟滚动说明

表格顶部工具栏#

props.toolbar 非空时,ProTable 将在表格 上方 渲染一个工具栏。 props.toolbar 将作为 Toolbar 组件的 props。例如 toolbar.leftActions 可以在顶部工具栏中添加一些按钮,toolbar.tipNode 可以添加提示文案,其他字段详见 Toolbar 的文档。

此外,ProTable 支持通过 toolbar.totalCount 快速设置 共 n 条数据 的文案。

分页#

ProTable 默认使用的是前端分页,即分页状态会影响表格展示的数据。

如果不需要前端分页,可以设置 pagination={{ keepDataSource: true }} 。该选项适用于后端分页的情况,例如每次改变页码后页面重新发起请求获取下一页的数据。

pagination 对象中的其他字段会透传至 ProTable 内部的 <Pagination /> 组件。

后端分页示例:

<ProTable
dataSource={dataSource}
columns={columns}
pagination={{
// 禁用前端分页
keepDataSource: true,
// 总数据量
total: 2000,
// 当前页码
current: 4,
onChange(nextPage) {
// 根据新的页码去请求数据
fetchData(nextPage).then(handleData);
},
}}
/>

表格页脚工具栏#

props.footer 非空时,ProTable 将在表格 下方 渲染一个工具栏。 props.footer 将作为 Toolbar 组件的 props。例如 footer.leftActions 可以添加一些按钮,footer.tipNode 可以添加提示文案。

不设置 footer.rightNode 时,表格页脚右侧会展示内置的翻页器组件(如果 pagination 非空的话)。

ProTable 兼容的 Table 用法#

  • ProTable 中的列配置兼容原有的 column.cell 用法
  • ProTable 对 column.dataIndex 进行了兼容,其作用与 column.codecolumn.dataIndex 相同
  • ProTable 对排序 sort 中的 code / dataIndex 进行了兼容
  • ProTable 兼容 footerActions,作用与 footer.leftActions 相同

用法示例#

基本表格#

通过 dataSource 设置表格的数据源,通过 columns 设置表格的列。 注意 column.dataIndex 要与 dataSource 中的数据字段相对应。

noInline

表格样式#

ProTable 提供了 compact、zebra、bordered 三种可选样式,可以通过 className 来使用这些样式

<ProTable
  dataSource={dataSource}
  columns={columns}
  className="compact" 
  hasHeader={true} 
  isLoading={false} 
/>
noInline

数据为空#

dataSource 的长度为 0 时,表格将展现空状态。

noInline

表格数据加载#

设置 isLoading=true 即可展示加载动画。

noInline

表格页脚#

设置 footerDataSource 后可以展示表格页脚, footerDataSource 中的字段一般与 dataSource 相同

noInline

表格排序#

提供排序功能,便于查看数据。

noInline

表格行单选#

noInline

表格行多选#

点击复选框时,按住 shift 键可以进行批量选择/反选。

noInline

树形表格#

让表格支持树形数据的展示,当数据中有 children 字段时会自动展示为树形表格。

noInline

树形可选择表格#

noInline

限定表格容器大小#

通过 style.width/style.maxWidth 来限定表格的宽度;通过 style.height/style.maxHeight 来限定高度。 限定宽度或高度时,要同时设置 style.overflow=auto。

noInline

行分组#

inline

表头分组与列高亮#

noInline

行详情#

noInline

表格嵌套#

600,000.00(CNY)交通银行丨浙大路支行Wesley Cruz600,000.00(CNY)招商银行丨庆春路支行Billy Horton600,000.00(CNY)招商银行丨文一路分行Paul Tran600,000.00(CNY)农业银行丨杭州分行Anna Poole
noInline

表格套娃#

在嵌套的表格内继续嵌套,可以实现套娃效果

noInline

集成表格工具栏#

toolbar 非空时,将在表格上方渲染一个工具栏。 toolbar 将作为 <Toolbar /> 组件的 props。

共 6 条数据
noInline

集成翻页器#

pagination 非空时,将在表格下方渲染一个翻页器。 表格会根据翻页器的状态对数据进行筛选,pagination 将作为 <Pagination /> 组件的 props。

noInline

拖拽调整列宽#

noInline

列的收拢展开交互#

设置 columnCollapse 后,可以开启列分组的收拢展开;

只有打上 column.features.collapsible=true 标记的分组才支持展开, 为子节点设置 columns.features.primaryColumn=true 的话,其所在分组收拢后将默认展示该子节点。

columnCollapse 支持受控用法(expandedGroups/onExpand),expandedGroups 是一个字符串数组,表示当前展开分组的 code 列表。 columnCollapse 也支持受控用法(defaultExpandedGroups),不传该属性时默认为空数组。

columnCollapse 依赖 column.code 进行工作,你需要给每一个需要展开/收拢的分组设置一个唯一 code。

noInline

自定义列#

设置 columnFilter 后,可以开启自定义显示列的功能; columnFilter 支持受控(visibleCodes/onChange) 或非受控(所有列默认均可见)用法。

columnFilter 抽屉的触发按钮在 toolbar 之内,注意设置 toolbar.rightNode 后将导致触发按钮无法展示; 故在使用 columnFilter 时,如需调整 toolbar 右侧的内容,请使用 toolbar.rightActions 进行配置。

columnFilter 支持以下功能:

columnFilter 依赖 column.code 进行工作,你需要给每一列都设置一个「唯一的 code」。 如果设置 code 影响了表格数据展示,可以通过 column.getValue 进行调整。

当一个分组下所有的叶子节点都隐藏时,该分组将自动隐藏; columnFilter.visibleCodes 只需传入「叶子节点」的 code 列表,尽量避免传入分组节点的 code.

共 5 条数据
noInline

从 JSX 中解析 columns#

ProTable.parseColumns 可用于从 JSX 中解析出 columns 数组。 该方法主要是方便从老代码迁移,一般情况下推荐你使用标准的 columns 数组写法来生成表格列。

ProTable.parseColumns 的一些规则详见下方代码示例中的注释。

inline

API#

dataSource 和 columns 是必传 props,其他 props 均可选。

表格 props#

主要字段#

字段类型
dataSourceany[]表格数据源
columnsArtColumn[]表格的列配置
isLoadingboolean表格是否在加载中
primaryKeystring
(row: any) => string
用于指定每一行的 key
传入字符串表示从数据中获取对应字段的值作为 key
传入函数时将调用该函数来生成每一行的 key
不传该 prop 时,表格将使用下标作为每一行的 key
getRowProps(record: any, rowIndex: number): React.HTMLAttributes自定义每一行的 props

其他字段#

字段类型
classNamenumber自定义类名
styleReact.CSSProperties自定义内联样式
hasHeaderboolean表格是否具有头部
isStickyHeaderboolean表格头部是否吸顶,默认为 true
stickyTopnumber表头吸顶后,距离顶部的距离,默认为 0
useOuterBorderboolean是否使用来自外层 div 的边框代替单元格的外边框,默认为 false
defaultColumnWidthnumber列的默认宽度
emptyCellHeightnumber数据为空时,单元格的高度
footerDataSourceany[]表格页脚数据源(数据中的字段一般要与 dataSource 相同)
isStickyFooterboolean表格页脚是否吸附在表格底部,默认为 true
hasStickyScrollboolean表格是否包含自定义的横向粘性滚动条是否出现,默认为 true
stickyScrollHeight'auto' / number指定自定义横向滚动条的高度,在定制滚动条样式时有用,默认为 'auto'
stickyBottomnumber表格底部距离页面下边缘的距离
useVirtual'auto'
boolean
或一个对象
是否开启虚拟滚动,详见下方「虚拟滚动」说明
estimatedRowHeightnumber虚拟滚动开启情况下,表格中每一行的预估高度
wrapperClassNamestringProTable 最外层 div 的 className
wrapperStyleReact.CSSPropertiesProTable 最外层 div 的 style
componentsobject自定义表格内部使用的子组件,详见下方

column 对象结构#

列配置注意事项:

字段类型
namestring列的名称
codestring在数据中的字段 code
dataIndexstringcode 的别名;ProTable 推荐使用 code 代替 dataIndex
getValue(record: any, rowIndex: number) => any自定义取数方法
render(value: any, record: any, rowIndex: number) => ReactNode自定义渲染方法
getCellProps(value: any, record: any, rowIndex: number) => any自定义的获取单元格 props 的方法
getSpanRect(value: any, record: any, rowIndex: number) => SpanRect在虚拟滚动的情况下设置单元格合并
titleReactNode列标题的展示名称;在页面中进行展示时,该字段将覆盖 name 字段
widthnumber列的宽度,如果该列是锁定的,则宽度为必传项
align'left' / 'center' / 'right'单元格对齐方向
lockboolean是否锁列
childrenArtColumn[]该列的子节点
headerCellPropsReact.ThHTMLAttributes表头单元格的 props
features{ [key: string]: any }功能开关标记,用于对表格功能进行拓展,注意很多拓展都需要依赖 features 中的特定标记

表格主题#

BaseTable/ProTable 中大部分样式都是通过 CSS variables 来定义的。 通过覆盖 CSS variables 的值,可以快速定制表格主题。

表格主题部分详见 开源文档.

表格功能拓展#

字段类型
sortboolean / object参数详见 排序
singleSelectboolean / object参数详见 行单选
multiSelectboolean / object参数详见 行多选
treeModeboolean / object参数详见 树状模式
treeSelectboolean / object参数详见 树形选择
rowGroupingboolean / object参数详见 行分组
columnRangeHoverboolean / object参数详见 列范围高亮
columnHoverboolean / object参数详见 列高亮
rowDetailboolean / object参数详见 行详情
tipsboolean参数详见 提示信息
columnResizeboolean / object参数详见 拖拽调整列宽
autoRowSpanboolean参数详见 自动合并多行
columnCollapseboolean / object列的收拢展开,参数见上方示例
columnFilterboolean / object自定义列,参数见上方示例

表格 UI 拓展#

字段类型
pagination透传给 <Pagination /> 组件的 props
ProTable 会根据翻页器的状态对 dataSource 进行过滤
pagination.keepDataSourceboolean禁用前端分页
toolbar透传给表格顶部 <Toolbar /> 组件的 props
toolbar.totalCountstring / number数据总数显示
footer透传给表格页脚 <Toolbar /> 组件的 props
Copyright © 2021 Alibaba Inc.
Built with ❤️ by hema-FE.