FCrudTable CRUD 表格

集 搜索栏 + 高效表格 + 分页 + 灵活列控制 + 自动 CRUD 模态框 于一体的通用数据表格组件。

组件与命名规范：组件名主推 FCrudTable，简写别名 FTable，兼容别名导出 FinCrudTable。

快速上手与演示

基础用法

不配置查询字段时，仅展示数据表格和分页。

格式化展示 (Formatter)

支持内置场景化格式化器（如金额、日期、百分比、状态标签等）。

带搜索区的 CRUD 表格

通过 searchPanelConfig.formConfig 配置顶部查询表单；整体面板折叠与条件按行收起均为可选能力。未启用整体折叠时不渲染标题栏，只展示查询表单。

查询区支持两级独立折叠：

// 不折叠：没有标题栏占位，仅展示查询表单
searchPanelConfig: {
  formConfig: { colProps: { span: 6 } },
}

// 仅整体面板折叠
searchPanelConfig: {
  collapsible: true,
  defaultCollapsed: false,
  formConfig: { colProps: { span: 6 } },
}

// 仅查询条件按行收起
searchPanelConfig: {
  formConfig: {
    collapsedRows: 1,
    defaultCollapsed: true,
  },
}

// 两级折叠同时启用
searchPanelConfig: {
  title: '筛选条件',
  collapsible: true,
  defaultCollapsed: false,
  formConfig: {
    collapsedRows: 1,
    defaultCollapsed: true,
  },
}

collapsedRows 未配置或小于等于 0 时不启用条件折叠；字段和查询按钮在指定行数内可完整展示时，也不会出现“展开/收起”。

完整 CRUD 模态框交互

配置 tableConfig.crudConfig 结合 createApi / updateApi / deleteApi 一键开启完整的弹窗增删改查全流程。

单选模式 (Radio)

通过设置 radio: true 启用单选模式，每次只能选择一行数据。单选与多选互斥。

栅格排版 (Span) 全局默认 vs 字段级特例覆盖法则

在 CrudTable 中，排版设计采用了 “全局容器默认 + 单字段特例覆盖” 的优雅层级：

全局容器控制 (tableConfig.searchPanelConfig.formConfig)：通过 formConfig.colProps.span 可以统一设置顶部搜索栏所有字段的默认所占宽度。例如设置 { colProps: { span: 6 } }，即表示顶部搜索栏所有查询框默认均分为 4 列。无需在每个 formItem 中重复书写 span。
单字段特例覆盖 (columns[i].formItem)：当某个特定字段内容较长（如日期范围选择框）需要跨多列时，才需在 formItem 里指定 querySpan 或 queryColProps 进行单独特例覆盖。

栅格列宽 (Span) 的全量 4 级智能解算链条

$$\text{1. queryColProps / querySpan} ;; > ;; \text{2. 通用 formItem.colProps / span} ;; > ;; \text{3. searchPanelConfig.formConfig.colProps.span} ;; > ;; \text{4. 默认 span: 6}$$

2. 弹窗模态框场景 (Dialog Form)

$$\text{1. 通用 formItem.colProps / span} ;; > ;; \text{2. dialogConfig.formProps.colProps / span} ;; > ;; \text{3. 默认 span: 24}$$

💡 智能降级共享法则：
若容器全局均未配置 colProps，且开发者仅配置了通用的 formItem: { span: 12 }（未指定 querySpan），该 span: 12 会同时自动回退作用于搜索栏与弹窗；
一旦指定了搜索专用的 querySpan: 8 或在 searchPanelConfig.formConfig 中指定了全局排版，则按上述层级精准覆盖。

全量 API 参数指南

1. TableConfig (表格核心配置)

继承 Element Plus 官方 TableProps<any>（可直接书写 border, stripe, height, fit, showSummary 等原生属性），并扩展以下 FinUI 顶级配置项：

属性名	类型	默认值	说明
`columns`	`TableColumnConfig[]`	必填	业务列表数据列配置数组
`title`	`string`	-	表格顶部显示标题
`selection`	`boolean`	`false`	是否显示复选框多选列
`radio`	`boolean`	`false`	是否显示单选列（与 selection 互斥）
`index`	`boolean`	`false`	是否显示序号列
`expand`	`boolean`	`false`	是否开启行展开功能（配合 `#expand` 插槽）
`rowKey`	`string \| ((row: any) => string)`	`'id'`	行数据的唯一 key 标识
`virtual`	`boolean`	`false`	是否开启虚拟滚动模式（推荐数据量 > 500 时开启）
`virtualItemSize`	`number`	`48`	虚拟滚动下的每行固定高度（px）
`toolbarConfig`	`ToolbarConfig`	-	顶部工具栏整体配置对象
`rowActionConfig`	`RowActionConfig`	-	行操作列整体配置对象
`searchPanelConfig`	`SearchPanelConfig`	-	查询区域配置；`collapsible: true` 启用整体折叠，`formConfig.collapsedRows` 启用条件按行收起
`searchFormConfig`	`Partial<UseFormProps>`	-	已废弃的查询表单配置入口，请使用 `searchPanelConfig.formConfig`
`crudConfig`	`CrudConfig`	-	CRUD 增删改查配置（自动注入新增与行内操作）
`pagination`	`boolean \| PaginationConfig`	`true`	分页配置（传入 `false` 显式禁用分页）
`requestConfig`	`RequestConfig`	-	后端数据请求与字段路径映射配置
`treeConfig`	`TreeConfig`	-	树形表格高级配置
`columnSettings`	`ColumnSettingsConfig`	-	列设置 (Popover 显隐与拖拽排序) 配置

2. TableColumnConfig (列表列配置)

继承 BaseColumn 基础列定义，扩展排序、显示控制与单列驱动表单能力：

属性名	类型	默认值	说明
`field`	`string`	必填	映射数据对象的属性字段 key (唯一标识)
`label`	`string`	必填	表格列头显示的文本标题
`width`	`number \| string`	-	列固定宽度 (如 `120` 或 `'120px'`)
`minWidth`	`number \| string`	-	列最小宽度
`align`	`'left' \| 'center' \| 'right'`	`'left'`	单元格文本对齐方式
`fixed`	`'left' \| 'right' \| boolean`	-	是否固定列
`showOverflowTooltip`	`boolean`	`false`	内容超出时是否显示 Tooltip 提示
`sortable`	`boolean \| 'custom'`	`false`	是否支持排序 (`'custom'` 为服务端排序)
`hide`	`boolean`	`false`	彻底隐藏列（表格不展示且【列设置】面板中绝对不显示）
`hidden`	`boolean`	`false`	默认隐藏列（【列设置】面板中显示为未勾选，允许手动勾选）
`children`	`TableColumnConfig[]`	-	多级表头子列配置项
`slot`	`string`	-	自定义单元格内容插槽名
`formatter`	`ColumnFormatter`	-	内置格式化器 (`'money'` \| `'date'` \| `'percent'` \| `'status'`) 或自定义格式化函数 `(row, val) => VNode \| string`
`formatterOptions`	`FormatterOptions`	-	格式化参数配置 (如 `precision`, `format`, `statusMap`)
`formItem`	`FormSchema`	-	单列驱动表单：定义该列在搜索栏与 CRUD 弹窗中的 `FormSchema` 配置

3. RowActionConfig (行操作列配置)

定义表格最右侧或最左侧行操作列的呈现形态：

属性名	类型	默认值	说明
`actions`	`ActionButtonConfig[]`	-	自定义追加的行操作按钮列表
`maxCount`	`number`	`1`	最多直接平铺显示的按钮个数，超出收纳至“更多”下拉菜单
`label`	`string`	`'操作'`	行操作列标题
`width`	`number \| string`	-	行操作列宽度
`minWidth`	`number \| string`	-	行操作列最小宽度
`fixed`	`'left' \| 'right'`	`'right'`	行操作列固定位置
`align`	`'left' \| 'center' \| 'right'`	`'center'`	对齐方式
`showView`	`boolean`	`false`	是否显式展示查看/详情按钮
`showEdit`	`boolean`	`true` (当配置 `updateApi` 时)	是否显式展示编辑按钮
`showDelete`	`boolean`	`true` (当配置 `deleteApi` 时)	是否显式展示删除按钮
`viewText`	`string`	`'查看'`	查看按钮文本
`editText`	`string`	`'编辑'`	编辑按钮文本
`deleteText`	`string`	`'删除'`	删除按钮文本

4. CrudConfig & CrudDialogConfig (CRUD 增删改与弹窗配置)

tableConfig.crudConfig 相关配置项：

CrudConfig

属性名	类型	说明
`createApi`	`(data: Record<string, any>) => Promise<any>`	新增数据接口函数
`updateApi`	`(data: Record<string, any>) => Promise<any>`	更新数据接口函数 (数据包含 `rowKey`)
`deleteApi`	`(row: Record<string, any>) => Promise<any>`	删除数据接口函数 (接收当前行数据)
`dialogConfig`	`CrudDialogConfig`	弹窗尺寸、标题与属性配置
`deleteConfirmText`	`string \| ((row: any) => string)`	删除二次确认框提示文案
`onSuccess`	`(action: 'create' \| 'update' \| 'delete', row?: any) => void`	操作成功后的回调函数
`beforeEdit`	`(row: any) => any \| Promise<any>`	打开编辑弹窗前的钩子（可用于异步拉取完整详情）
`beforeSubmit`	`(data: Record<string, any>, action: 'create' \| 'edit') => Record<string, any> \| Promise<Record<string, any>>`	提交前数据转换钩子

CrudDialogConfig

属性名	类型	默认值	说明
`width`	`string \| number`	`'600px'`	弹窗宽度
`createTitle`	`string`	`'新增'`	新增模态框标题
`editTitle`	`string`	`'编辑'`	编辑模态框标题
`viewTitle`	`string`	`'详情'`	查看模态框标题
`beforeClose`	`(action: 'create' \| 'edit' \| 'view') => boolean \| Promise<boolean>`	关闭弹窗前钩子
`closeOnClickModal`	`boolean`	`false`	是否允许点击遮罩关闭弹窗
`draggable`	`boolean`	`false`	是否开启弹窗鼠标拖拽
`formProps`	`Partial<UseFormProps>`	-	弹窗内表单容器全局配置 (如 `labelWidth`, `gutter` 等)

5. RequestConfig (后端请求与字段映射配置)

属性名	类型	默认值	说明
`api`	`(params: Record<string, any>) => Promise<any>`	必填	异步列表请求 API 函数
`immediate`	`boolean`	`true`	是否在组件初始化时自动立即发送请求
`paramsMap`	`{ page?: string; pageSize?: string }`	`{ page: 'pageNum', pageSize: 'pageSize' }`	分页请求参数名映射
`responseMap`	`{ list?: string; total?: string }`	`{ list: 'data.list', total: 'data.total' }`	响应提取点路径 (支持 `'data.rows'` 等任意嵌套)
`beforeRequest`	`(params: Record<string, any>) => Record<string, any> \| Promise<Record<string, any>>`	-	发送请求前的参数加工转换钩子
`afterResponse`	`(data: any) => any \| Promise<any>`	-	接收响应后的数据加工转换钩子
`syncToUrl`	`boolean`	`false`	是否将当前页码、条数与搜索参数同步到浏览器 URL Query String

6. PaginationConfig (分页配置)

属性名	类型	默认值	说明
`pageSize`	`number`	`10`	默认每页显示条数
`pageSizes`	`number[]`	`[10, 20, 50, 100]`	每页条数可选项数组
`layout`	`string`	`'total, sizes, prev, pager, next, jumper'`	Element Plus 分页组件布局选项
`showTotal`	`boolean`	`true`	是否显示数据总条数

7. ColumnSettingsConfig (列设置与持久化配置)

属性名	类型	默认值	说明
`enabled`	`boolean`	`true`	是否显示工具栏右侧【列设置】Popover 按钮
`storageKey`	`string`	-	本地 localStorage 存储 key（默认使用组件全局标识）
`defaultHidden`	`string[]`	-	默认隐藏的列 `field` 列表
`defaultOrder`	`string[]`	-	默认初始化的列顺序 `field` 数组
`onSave`	`(config: { order: string[]; hidden: string[] }) => void \| Promise<void>`	-	用户调整列显隐与拖拽排序时的保存回调钩子

8. ToolbarConfig (工具栏配置)

属性名	类型	默认值	说明
`title`	`string`	-	顶部工具栏标题
`actions`	`ActionButtonConfig[]`	-	顶部工具栏自定义追加按钮列表
`maxCount`	`number`	`1`	最多直接平铺显示的按钮个数
`morePosition`	`'left' \| 'right'`	`'left'`	“更多”下拉菜单出现的位置
`showDivider`	`boolean`	`true`	是否显示动作按钮与列设置按钮之间的竖向分割线

9. TreeConfig (树形表格配置)

属性名	类型	默认值	说明
`children`	`string`	`'children'`	子节点列表字段名
`hasChildren`	`string`	`'hasChildren'`	标识是否有子节点的字段名（用于懒加载场景）
`defaultExpandAll`	`boolean`	`false`	是否默认展开所有树节点
`defaultExpandedKeys`	`(string \| number)[]`	-	默认展开的行 `rowKey` 集合

10. CrudTable Emits (全量事件清单)

事件名	回调参数	说明
`selection-change`	`(rows: any[]) => void`	当多选框勾选状态改变时触发
`radio-change`	`(row: any) => void`	当单选框选中状态改变时触发（仅 radio 模式）
`sort-change`	`(payload: { field: string; order: string \| null }) => void`	单元格排序改变时触发
`search`	`(params: Record<string, any>) => void`	点击搜索按钮触发
`reset`	`() => void`	点击重置搜索按钮触发
`data-change`	`(data: { list: any[]; total: number }) => void`	列表数据加载/更新完成后触发
`toolbar-action`	`(action: ActionButtonConfig, params: { loading: boolean; selectedRows: any[] }) => void`	点击工具栏自定义按钮时触发
`row-action`	`(action: ActionButtonConfig, row: any, params: { row: any; index: number }) => void`	点击行操作列自定义按钮时触发
`batch-action`	`(action: ActionButtonConfig, rows: any[], params: { rows: any[] }) => void`	批量选择操作按钮点击时触发
`row-click`	`(row: any, column: any, event: Event) => void`	单击表格某一行时触发
`row-dblclick`	`(row: any, column: any, event: Event) => void`	双击表格某一行时触发
`create`	`(data: any) => void`	新增数据成功后触发
`update`	`(data: any) => void`	编辑更新数据成功后触发
`delete`	`(row: any) => void`	删除数据成功后触发

11. CrudTable Methods (实例方法)

通过 ref 获取组件实例后可调用以下方法：

方法名	参数	返回值	说明
`refresh`	-	`void`	刷新表格数据
`clearSelection`	-	`void`	清空选中行（多选/单选）
`getRadioRow`	-	`any \| null`	获取当前单选模式下选中的行数据（仅 radio 模式）
`openCreate`	-	`void`	打开新增弹窗
`openEdit`	`row: any`	`void`	打开编辑弹窗
`openView`	`row: any`	`void`	打开查看弹窗

示例：

vue

<template>
  <FCrudTable ref="tableRef" :table-config="tableConfig" />
</template>

<script setup>
import { ref } from 'vue'

const tableRef = ref()

// 获取单选行
const selectedRow = tableRef.value?.getRadioRow()

// 刷新数据
tableRef.value?.refresh()

// 清空选中
tableRef.value?.clearSelection()
</script>

FCrudTable CRUD 表格 ​

快速上手与演示 ​

基础用法 ​

格式化展示 (Formatter) ​

带搜索区的 CRUD 表格 ​

完整 CRUD 模态框交互 ​

单选模式 (Radio) ​

栅格排版 (Span) 全局默认 vs 字段级特例覆盖法则 ​

栅格列宽 (Span) 的全量 4 级智能解算链条 ​

1. 顶部搜索栏场景 (Search Form) ​

2. 弹窗模态框场景 (Dialog Form) ​

全量 API 参数指南 ​

1. TableConfig (表格核心配置) ​

2. TableColumnConfig (列表列配置) ​

3. RowActionConfig (行操作列配置) ​

4. CrudConfig & CrudDialogConfig (CRUD 增删改与弹窗配置) ​

CrudConfig ​

CrudDialogConfig ​

5. RequestConfig (后端请求与字段映射配置) ​

6. PaginationConfig (分页配置) ​

7. ColumnSettingsConfig (列设置与持久化配置) ​

8. ToolbarConfig (工具栏配置) ​

9. TreeConfig (树形表格配置) ​

10. CrudTable Emits (全量事件清单) ​

11. CrudTable Methods (实例方法) ​