Fast-Table 快速表格
基于 query-panel pagination table 及表单组件聚合而成的快速表格模板，用以支持快速业务开发
组件概述
Fast-Table 用于把“搜索表单 + 数据表格 + 分页”这类高频业务页面抽象成统一模板，减少列表页开发中的重复拼装工作。
它更适合这几类场景：
- 标准查询列表页，需要快速完成搜索、请求、分页和表格展示。
- 列配置、排序、批量选择等表格能力需要统一处理的业务页面。
- 接口形态相对稳定，但又希望保留插槽扩展能力的中后台页面。
组件本身主要提供这些能力：
- 聚合
EzQueryPanel、EzTable、EzPagination，统一列表页搭建方式。 - 通过
api、columns、params等配置驱动数据请求和表格展示。 - 支持表格上方区域、查询表单区域和数据列插槽，便于做业务扩展。
- 对常见分页请求场景做统一封装，同时保留对自定义业务参数的兼容。
基础用法
INFO
如果你的业务基础请求和当前组件的分页处理不一致，你可以抽取公共方法，转换成新的 Promise 来适配该组件，同时你也可以处理除分页参数以外的其他业务参数。
组合使用
请求适配
INFO
你可以使用 header 插槽快速获取选择项，row-key 的值默认是 id, 在处理选择项这个是非常有必要指定的。
页面状态
INFO
#error 插槽提供了 retry 方法，可以在错误状态下重新发起请求。stage 参数表明错误发生在哪个阶段（beforeSearch、transformParams、api、responseAdapter）。
完整 CRUD 页面模式
推荐的组合方式
- 标准 CRUD 查询区：优先使用
EzQueryPanel+ 原生el-form/el-form-item，保证页面结构直观、可读、易维护 - 数据模型：统一使用
QueryParams<T>作为查询参数类型，包含current/size/asc/desc基础字段 - 参数回填：从 URL 或外部状态回填参数后，调用
captureInitialParams()记录为新基线 - 批量操作：通过
#header插槽获取selectIds和selectList，实现批量删除、导出等能力 - 编辑弹窗：使用
EzDialog+EzDynamicForm组合，统一表单配置风格 - 页面状态：通过
#empty和#error插槽自定义空数据和错误状态展示
如果查询区字段存在局部复用需求，优先抽取 el-form-item 级别的字段片段或字段工厂，而不是把整个查询区提升为配置化模型。
数据流最佳实践
- 参数同步：通过
v-model:params实现查询参数的双向绑定，表单和分页状态自动同步 - 列配置输入：始终显式传入
columns；如果需要响应列管理工具带来的列配置变化，再配合v-model:columns - 固定列约束：当存在
fixed: 'left'/'right'列时，建议其余数据列显式声明width或min-width，避免窄屏和滚动场景下的表头/表体错位 - 重置基线：组件挂载时自动记录初始参数，
reset()恢复到该基线 - 外部回填：从路由或缓存回填参数后，调用
captureInitialParams()更新基线 - 查询时机：新增/编辑成功后调用
search()重置到第一页，删除后调用query()保持当前页
TypeScript 模板类型建议
如果页面里需要依赖表格列插槽的强类型 row / column 推断，推荐通过 createTypedFastTable<T, P>() 创建一个带显式泛型的组件别名，再在模板中使用它。
import { createTypedFastTable } from 'ez-ui'
import type { QueryParams } from 'ez-ui'
interface Item {
id: string
name: string
}
const TypedFastTable = createTypedFastTable<Item, QueryParams<Partial<Item>>>()这样在 #operations、#status 等数据列插槽里，row 会稳定保持为 Item，更适合严格 TypeScript 场景。
列表页操作约定
- 新增/编辑成功：关闭弹窗后调用
search()，让列表回到第一页并重新拉取最新数据 - 删除成功：优先调用
query()，保持当前页语义，避免无必要地重置分页 - 批量删除：默认也沿用
query()语义；如果你的业务要求删除后回到第一页，再显式改为search() - 弹窗关闭时机：建议在提交成功后再关闭弹窗，提交失败时保留表单上下文，便于用户修正
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| api | 快速的接口服务 | Promise<Response> | - |
| before-search | 查询前副作用钩子，会拿到当前查询参数 | (params) => Promise<void> | - |
| transform-params | 请求参数转换钩子，返回值会作为 api 最终入参 | (params) => QueryParams | Promise<QueryParams> | 当前 params 的深拷贝 |
| response-adapter | 响应适配钩子，将接口返回转换为分页结构 | (response) => Page | Promise<Page> | 内置兼容 { code, data: { records, total } } |
| columns / v-model:columns | 表格列配置，columns 为必传；如需监听列管理工具回写可使用 v-model:columns | Table-Columns | - |
| v-model:loading | 异步请求状态 | boolean | false |
| v-model:params | 表单的查询参数，同分页信息双向绑定 | QueryParams | { current: 1, size: 10 } |
| row-key | 行数据的唯一标识字段 | enum | 'id' |
| column-tool | 是否显示列配置工具按钮 | boolean | true |
| border | 是否显示表格边框 | boolean | true |
| ... | 其他属性，直接传递给 ez-table | - | - |
INFO
fast-table 其他属性传递给 ez-table，最后传递到 el-table
INFO
如果接口参数需要二次加工，优先使用 transformParams。它接收当前 params 的深拷贝，你可以在里面做字段裁剪、时间范围拆分、空值清理、字段重命名等处理，返回值会作为 api 的最终入参，不会污染页面上的查询模型。
beforeSearch 更适合做查询前副作用，比如外部埋点、权限判断、补充一些页面状态。
INFO
如果你的接口返回不是 { code, data: { records, total } } 这一类结构，优先通过 responseAdapter 做响应适配，而不是在页面里手动包一层假响应。
INFO
远程排序不再兼容 sortable: 'custom' 这个隐式约定。请直接在列上声明 sortMode: 'remote'，并在需要时通过 sortField 指定真实排序字段名。
QueryParams
| 属性名 | 说明 | 类型 | 是否必须 | 默认值 |
|---|---|---|---|---|
| current | 当前页数，同分页配置双向绑定 | number | 否 | 1 |
| size | 每页显示条目个数，同分页配置双向绑定 | number | 否 | 10 |
| desc | 自定义排序中降序排序字段 | string | 否 | - |
| asc | 自定义排序中升序排序字段 | string | 否 | - |
| ... | 其他属性，自有业务参数 | Record | 否 | - |
排序设计建议
| 场景 | 列配置方式 | 行为 |
|---|---|---|
| 本地排序 | sortable: true 或自定义 sortMethod | 仅在当前表格数据上本地排序，不触发 FastTable 查询 |
| 远程排序 | sortMode: 'remote'，可选 sortField | FastTable 会写入 asc/desc 并重新查询 |
WARNING
当前 FastTable 的本地排序只作用于当前页表格数据。如果你的数据是远程分页返回的，这种本地排序并不是全量数据排序。全量排序应优先使用远程排序，或者由业务层先完成本地排序后再分页。
插槽
| 插槽名 | 说明 | 类型 |
|---|---|---|
| ${prop} | 数据列插槽，同 ez-table | object |
| form | 查询区内容插槽 | object |
| header | 表格上方区域 | object |
| freeArea | 搜索表单与表格之间的自由区域 | object |
| empty | 空数据状态插槽 | - |
| error | 错误状态插槽 | object |
事件
| 事件名 | 说明 | 参数 |
|---|---|---|
| update:columns | 监听列配置变更，通常由列管理工具触发 | Function |
| update:loading | 监听异步请求状态 | Function |
| update:params | 监听查询参数变更 | Function |
| changePage | 分页大小或当前页变更，可根据值判断变更类型 | Function |
| reset | 重置按钮点击事件 | Function |
| query | 查询完成事件 | Function |
| ... | 其他事件，直接传递给 ez-table | - |
INFO
fast-table 其他事件传递给 ez-table，最后传递到 el-table
方法
| 方法名 | 说明 | 类型 |
|---|---|---|
| getTableRef | 获取 el-table 实例 | Function |
| query | 直接触发 api 调用 | Function |
| search | 触发 api 调用，会重置current = 1 | Function |
| patchParams | 局部更新查询参数 | Function |
| replaceParams | 完整替换查询参数 | Function |
| reset | 重置到当前基线参数并重新查询 | Function |
| captureInitialParams | 将当前参数记录为新的重置基线 | Function |
| doLayout | 重新布局表格 | Function |
| clearError | 清除错误状态 | Function |
| getErrorState | 获取当前错误状态 | Function |
INFO
reset() 会恢复到当前记录的初始查询参数，再触发一次查询。组件首次挂载时会自动记录一次基线；如果你在页面外部回填了查询条件，可以手动调用 captureInitialParams() 作为新的重置基线。
INFO
form 和 freeArea 插槽现在会提供统一作用域，你可以直接在插槽内部调用 search()、reset()、query()，或者在回填查询条件后调用 captureInitialParams()。
INFO
如果只是修改部分查询条件，优先用 patchParams()；如果是从路由、缓存或外部状态整体回填一组参数，优先用 replaceParams()。这比直接改 params 更适合承接后续的分页重置、基线同步等统一规则。
INFO
FastTable 现在默认采用“最后一次请求生效”的并发策略。连续触发查询、分页或远程排序时，旧请求即使后返回，也不会覆盖最新结果。
INFO
#empty 插槽用于自定义空数据状态的展示内容。由于其本质上复用的是 el-table 的 empty 插槽，这里不额外提供作用域参数；如果你需要在空状态下重新查询，建议直接调用组件 expose 或页面上的外部方法。
#error 插槽用于自定义错误状态的展示内容，插槽作用域提供 error（错误对象）、stage（错误阶段）、params（发生错误时的参数）和 retry（重试方法）。
错误态默认是“保留当前表格数据并额外展示错误提示”的模式，而不是直接替换整个表格内容区。这意味着如果上一次查询成功、本次查询失败，页面会继续显示旧数据，直到下一次成功查询覆盖它。
当存在错误状态时，#empty 不会同时展示；只有“当前无数据且无错误”时才会进入空状态展示。