ProTable

一个页面级的表格抽象组件，内置查询、分页、行选择、列设置和操作列功能。

VEF 专属组件。 已在 v2.1.6 中从 @vef-framework-react/starter 迁移至 @vef-framework-react/components。

何时使用

• 任何需要查询 + 分页 + 行操作的数据列表页面。
• 需要列显隐控制或虚拟滚动的表格。

基础用法

import { ProTable } from '@vef-framework-react/components';
import type { TableColumn } from '@vef-framework-react/components';

interface User {
  id: number;
  name: string;
  status: string;
}

const columns: TableColumn<User>[] = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Status', dataIndex: 'status' },
];

export default function UserTable() {
  return (
    <ProTable<User, UserSearchParams>
      columns={columns}
      rowKey="id"
      queryFn={findUserPage}
      queryParams={searchParams}
      operationColumn={{
        width: 120,
        render: (row) => (
          <OperationButton requiredPermissions="user:edit" onClick={() => openEdit(row)}>
            Edit
          </OperationButton>
        )
      }}
    />
  );
}

非分页模式

<ProTable<User, UserSearchParams>
  isPaginated={false}
  columns={columns}
  rowKey="id"
  queryFn={findUserList}
/>

带行选择

<ProTable
  columns={columns}
  rowKey="id"
  queryFn={findUserPage}
  rowSelection={true}
  onSelectedRowKeysChange={(keys, rows) => setSelected(rows)}
/>

命令式 Ref

import { useRef } from 'react';
import type { ProTableRef } from '@vef-framework-react/components';

const tableRef = useRef<ProTableRef>(null);

// Manually refetch
tableRef.current?.refetch();

<ProTable ref={tableRef} ... />

API

props 类型以 ProTableProps 导出。

rowKey、showSequenceColumn 和 striped 可以通过 ConfigProvider.components.ProTable 设置应用级默认值。显式传给该表格的 prop 仍然优先。

Prop	Type	Default	说明
columns	TableColumn<TRow>[]	—	列定义
rowKey	DeepKeys<TRow> | (row) => Key	—，可由 ConfigProvider.components.ProTable 覆盖	行 key 提取器
queryFn	QueryFunction<PaginationResult<TRow>, ...>	—	数据获取函数
queryParams	TParams	—	额外的查询参数
queryEnabled	(params?) => boolean	—	是否启用查询
isPaginated	boolean	true	启用/禁用分页
showSequenceColumn	boolean	true，可由 ConfigProvider.components.ProTable 覆盖	显示行号列
virtual	boolean	false	启用虚拟滚动
striped	boolean	false，可由 ConfigProvider.components.ProTable 覆盖	渲染斑马纹行
columnSettings	ColumnSettingsProp（ColumnSettingsConfig | false）	{}	列显隐设置
operationColumn	OperationColumnConfig<TRow>	—	每行的操作列
rowSelection	RowSelectionConfig<TRow> | true	—	行选择配置
selectedRowKeys	Key[]	—	受控的已选行 key
size	'large' | 'medium' | 'small'	—	表格密度（'middle' 是 'medium' 的废弃别名）
title	ReactNode	—	表格上方的标题
header	ReactNode	—	标题上方的内容
summary	ReactNode	—	表格下方的内容
footer	ReactNode	—	页脚内容
className	string	—	表格容器的类名
style	CSSProperties	—	表格容器的内联样式
onRowClick	(row, index, event) => void	—	行点击处理函数（操作列内部会忽略该事件）
onSelectedRowKeysChange	(keys, rows) => void	—	选择变化回调函数

ColumnSettingsConfig

interface ColumnSettingsConfig {
  storageKey?: string; // persist to localStorage with this key
}

OperationColumnConfig<TRow>

字段	类型	说明
width	Length	列宽。没有内置默认值——请设置固定宽度，避免固定在末尾的操作列吸走表格的剩余空间；框架惯例是两个操作按钮用 160 px（这也是 EditableTable 的默认值）
title	ReactNode	列标题；默认为 "操作"。启用列设置时，列设置图标会渲染在标题旁
requiredPermissions	string[]	显示操作列所需的权限令牌
render	(row: TRow, index: number) => ReactNode	渲染某一行的操作单元格（必填）

requiredPermissions 会在当前用户不持有所列权限令牌中的任何一个时，隐藏整个操作列（包括表头）。操作列始终固定在表格末尾。

RowSelectionConfig<TRow>

以 rowSelection 传入（或传 true 使用全部默认值）：

字段	类型	说明
rowSelectDisabled	(model: TRow) => boolean	对函数返回 true 的行禁用选择
checkStrictly	boolean	严格勾选表格行，父子行的选择互不关联
hideSelectAll	boolean	隐藏表头中的全选复选框
preserveSelectedRowKeys	boolean	即使 key 已不存在于 dataSource 中也保留选择
defaultSelectedRowKeys	Key[]	初始选中的行 key

ProTableRef

成员	类型	说明
refetch	() => void	手动触发数据重新获取（例如外部数据变化后）
onLoading	(callback: () => void) => () => void	注册表格开始加载时调用的回调；返回取消订阅函数
onLoaded	(callback: () => void) => () => void	注册表格加载完成时调用的回调；返回取消订阅函数

ProTableSubscriber

在表格自己渲染的内容里——它的 header、title、summary、footer 或某个单元格——读取表格自身的状态：已加载的行、分页、排序、refetch。它必须渲染在表格内部，因为这些状态就存放在那里；要在表格外部跟踪加载过程，请使用上文 ref 的 onLoading / onLoaded。

import { Button, ProTable, ProTableSubscriber } from '@vef-framework-react/components';

<ProTable<User, UserSearchParams>
  columns={columns}
  rowKey="id"
  queryFn={findUserPage}
  footer={(
    <ProTableSubscriber selector={state => [state.data.length, state.refetch] as const}>
      {([count, refetch]) => <Button onClick={refetch}>{`已加载 ${count} 条，刷新`}</Button>}
    </ProTableSubscriber>
  )}
/>

Prop	类型	说明
selector	(state: ProTableState & { data: readonly TRow[] }) => TSelected	选出用于渲染的状态切片，按浅比较判断变化，因此只有这一切片变化时才会重新渲染。省略时 children 拿到完整状态
children	ReactNode | ((selected: TSelected) => ReactNode)	以选出的切片渲染

props 类型以 ProTableSubscriberProps 导出。

OperationButtonGroup

一个居中的 Group，用于操作单元格中的按钮，同样以 selector / children 的方式读取 ProTableState（props 类型为 OperationButtonGroupProps）——适用于需要表格状态的行操作，例如操作完成后刷新：

operationColumn={{
  width: 160,
  render: row => (
    <OperationButtonGroup selector={state => state.refetch}>
      {refetch => (
        <OperationButton onClick={async () => { await disableUser(row.id); refetch(); }}>
          停用
        </OperationButton>
      )}
    </OperationButtonGroup>
  )
}}

Crud 页面则使用 createCrudKit() 返回的 OperationButtonGroup，它从 CRUD store 中选取状态。

ProTableState

selector 能读取的内容：

字段	说明
paginationParams / setPaginationParams	当前分页参数及其设置函数
sort / setSort	当前的 OrderSpec[] 及其设置函数
refetch	以当前查询参数、分页与排序重新请求
columnSettings / originalColumnSettings	每列的显隐、顺序、宽度与固定方向——以及重置时恢复到的状态
setColumnVisible / setColumnFixed / setColumnWidth / reorderColumns / setColumnSettings / resetColumnSettings / initColumnSettings	列设置面板使用的各项列设置操作
eventEmitter	表格内部的事件总线

ProTableSubscriber 另外提供 data，即当前已加载的行。