跳到主要内容

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​

PropTypeDefault说明
columnsTableColumn<TRow>[]—列定义
rowKeyDeepKeys<TRow> | (row) => Key—行 key 提取器
queryFnQueryFunction<PaginationResult<TRow>, ...>—数据获取函数
queryParamsTParams—额外的查询参数
queryEnabled(params?) => boolean—是否启用查询
isPaginatedbooleantrue启用/禁用分页
showSequenceColumnbooleantrue显示行号列
virtualbooleanfalse启用虚拟滚动
stripedbooleanfalse渲染斑马纹行
columnSettingsColumnSettingsConfig | false{}列显隐设置
operationColumnOperationColumnConfig<TRow>—每行的操作列
rowSelectionRowSelectionConfig<TRow> | true—行选择配置
selectedRowKeysKey[]—受控的已选行 key
size'large' | 'medium' | 'small'—表格密度（'middle' 是 'medium' 的废弃别名）
titleReactNode—表格上方的标题
headerReactNode—标题上方的内容
summaryReactNode—表格下方的内容
footerReactNode—页脚内容
classNamestring—表格容器的类名
styleCSSProperties—表格容器的内联样式
onRowClick(row, index, event) => void—行点击处理函数（操作列内部会忽略该事件）
onSelectedRowKeysChange(keys, rows) => void—选择变化回调函数

ColumnSettingsConfig​

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

OperationColumnConfig<TRow>​

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

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

RowSelectionConfig<TRow>​

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

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

ProTableRef​

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

ProTableSubscriber​

从组件外部订阅表格的加载事件：

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

<ProTableSubscriber
  tableRef={tableRef}
  onLoading={() => setLoading(true)}
  onLoaded={() => setLoading(false)}
/>