ElFormQuery

ElFormQuery 是面向列表筛选场景的 schema 驱动 查询表单：内置 el-form、CSS Grid 响应式列数（与 ElFormLayout 同源解析）、折叠 dense 装箱（操作区固定占用折叠网格右下角一格），并通过 portal-vue 将「查询 / 重置 / 展开收起」与自定义按钮混排到同一操作靶区。表单项由 ElFormRenderer 渲染，字段类型与 EllFieldSchema 对齐。

使用前提

请使用 v-model 绑定筛选数据对象（Record<string, unknown>）；schema 为同级字段数组 EllFormQueryFieldSchema[]（即 EllFieldSchema[]，不支持 group / custom 块）。
grid： 未传时继承 ElLabConfigProvider，再无则使用内置 element-plus 预设（见 ConfigProvider）。
portal-vue： 应用需已注册；操作区通过内置 PortalTarget（multiple）承接 ${uid}-actions，一般无需在页面额外为内置三键单独设靶（自定义扩展按钮见下文）。
为何不复用 ElFormLayout： 折叠态需将操作按钮落在 末行末列 并与 dense 装箱 联动，与通用网格布局目标不同；实现上仅在 @element-plus-lab/utils 层共享 useGridLayout、列数解析等能力。详见表单方案 § 二、el-form-query。

基础用法

v-model + schema + grid（或 fixed-col-count）即可；点击「查询」会先走 el-form.validate()，通过后 emit('search', { ...model })。

与 FormLayout / FormBuilder 的分工

能力	ElFormQuery	ElFormLayout	ElFormBuilder
布局	查询专用网格 + 折叠算法	通用 grid 容器	内用 FormLayout
表单项	仅 schema，无默认插槽手写 item	手写 `ElFormLayoutItem`	schema + 分组 / custom（见 FormBuilder）
操作区	内置查询 / 重置 / 折叠 + portal 混排	无	actions + portal

与 ElFormLayoutItem 同源的标签策略：labelPosition: 'justify'、labelOverflow / labelOverflowType、字段 description / renderLabel / labelConfig（见 FormLayout · labelConfig）。

网格与间距

属性	说明
`grid`	预设名字符串或 `EllGridLayoutConfig`（`breakpoints` + 可选 `colGap` / `rowGap`）
`fixed-col-count`	≥1 时列数不随容器变；行/列间距仍取自 `grid` 与 `col-gap` / `row-gap` / `compact`
`col-gap` / `row-gap`	覆盖 `grid` 中间距；数字按 px
`compact`	`grid` 未写间距时默认 8px；并略缩标签字号

单档固定列数示例：:grid="{ breakpoints: [{ name: 'all', min: 0, cols: 3 }] }"（与 ElFormLayout 一致）。

折叠与展开

传入 default-rows-number（折叠态最大行数）后启用折叠布局；未传则始终按展开态排布，不展示「展开 / 收起」（与 show-collapse-toggle 无关）。
折叠时 可用字段格 ≈ defaultRowsNumber × 当前列数 − 1，右下角一格固定为操作区；装不下的字段 display: none，展开后按 simulateDenseFillExpanded 落位。
v-model:collapsed 与 default-collapsed 控制折叠状态；show-collapse-toggle 控制是否在「需要折叠」（内部 needToggle）时显示切换按钮。
force-wrap：false（默认） 时展开态操作区与末行字段同排合并列；true 时操作区独占字段下方新行并铺满列宽（按钮组可换行）。

defineExpose：collapsed、needToggle、toggleCollapse()，以及列数 currentColCount 等（见下文暴露）。

查询、重置与自动查询

行为	说明
查询	先 `validate()`，再 `searchHandler(model, formRef)` 或 `emit('search', model)`
重置	`resetFields()` 后 `resetHandler` 或 `emit('reset')`
`loading`	绑定内置「查询」按钮 `loading`（仅该按钮）
`immediate`	挂载后 `nextTick` 触发一次与点击查询相同的分发（不再自动校验以外的路径）
`immediate-debounce`	>0 时对 `v-model` deep watch，防抖毫秒后触发与查询相同的分发（不经过按钮校验——与点击查询不同，需注意若需校验应自行在业务里处理）

点击「查询」路径始终先校验；immediate / immediateDebounce 直接分发载荷，适合「进页拉表」或「改条件自动请求」但与校验组合时要自行权衡。

scroll-to-error / scroll-into-view-options：透传 el-form，校验失败滚到首错项。

标签位置与溢出（整表）

属性	说明
`label-width` / `auto-label-width`	与 Element Plus 一致；`justify` 下需合理宽度
`label-position`	`left` / `right` / `top` / `justify`（后者由组件插槽实现字间撑满）
`label-overflow`	仅允许 `true`；未传 `label-overflow-type` 时等价 `wrap`
`label-overflow-type`	`wrap` / `nowrap` / `ellipsis`；勿与 `auto-label-width`、`justify` 同时使用

字段级 description / renderLabel / labelConfig 与 ElFormRenderer、ElFormLayoutItem 对齐；renderLabel 存在时不走内置省略测量逻辑。

Schema 字段要点（`EllFormQueryFieldSchema`）

与 EllFieldSchema 一致，常用键：

键	说明
`field`	与 `model[field]` 绑定；`formItemConfig.prop` 可覆盖校验路径
`label` / `controlType` / `controlConfig`	控件与 EP 属性；未传 `controlType` 视为 `input`
`options`	`select` 等：`{ label, value }[]` 或异步解析函数
`formItemConfig`	`span` / `rules` / `message` / `class` / `style` / 内层透传等
`span`	列合并，语义同 `ElFormLayoutItem`
`dependencies`	`show` / `disabled` / `required` / `rules` / `controlConfig` 等联动
`visible(payload)`	在 `dependencies.show` 为真时进一步控制；`payload.tab` 来自 `active-tab`

已注册的 controlType（可 registerControl 扩展，见 FormRenderer · 注册自定义控件）： input、textarea、input-number、switch、checkbox、select、date-picker、datetime-picker、daterange-picker、time-picker、time-select。

查询栈类型上不允许的顶层键（勿传入）： 见 utils EllFieldSchemaQueryDeniedKeys（如字面 required / rules / render 排除，应放入 formItemConfig 或使用 dependencies）。

联动与显隐

dependencies.show 为假时该项不挂载且不占据折叠网格席位；与函数 visible() 组合时为逻辑与关系。

操作区与 portal-vue

单一目标名：`${uid}-actions`（与根 data-ell-form-query-uid 一致）。uid 未传时内部 ulid()，文档示例建议固定传入便于联调。
内置 portal 的 order：重置 5、查询 10、展开/收起 15。自定义 portal 请使用其它数值（如更小则排在重置左侧，更大则靠右）。

默认插槽（#default）作用域：uid、actionsPortalName（等于 `${uid}-actions`），便于在同一组件内写 <portal :to="actionsPortalName">。

#actions 插槽：传入则完全自定义操作区内容（仍接收 model / formRef），网格内操作格保留，由你自行布局按钮并调用 formRef.validate() 等。

表单宽度与滚动

min-width：表单根节点最小宽度；不足时由外层 .ell-form-query__viewport 横向滚动。
max-width：封顶宽度并在父级内 水平居中。

插槽

插槽	作用域	说明
default	`uid`、`actionsPortalName`	在 `</el-form>` 之后、内置 `<portal>` 之前，用于投递自定义按钮
actions	`model`、`formRef`	覆盖操作区整块默认内容（含 `PortalTarget`）

事件

事件	载荷
search	当前 `model` 浅拷贝（校验通过后）
reset	无
collapse-change	`collapsed: boolean`（与 `toggle-handler` 互斥时以 handler 为准）

暴露（`defineExpose`）

名称	说明
`model`	与 `v-model` 同源
`formRef`	`el-form` 实例
`uid`	解析后的 `uid` ref
`currentColCount`	当前列数
`collapsed` / `needToggle`	折叠状态与是否需展示折叠 UI
`toggleCollapse`	切换折叠
`formItemRef`	与 `ElFormBuilder` 类似的点分路径 → `el-form-item` 代理
`getControlRef` / `getFormItemRef`	按 `EllFormBuilderFieldRefSpec` 取实例
`getSchemaByField` / `getSchema`	按 `field` 取 schema 项

Props

模型与 schema

属性名	描述	类型	默认值
modelValue（`v-model`）	筛选数据	`Record<string, unknown>`	（必填）
schema	字段列表	`EllFormQueryFieldSchema[]`	（必填）
uid	portal / 调试标识	`string`	内部 `ulid()`

网格与布局

属性名	描述	类型	默认值
grid	断点与间距	`EllGridPresetName \| EllGridLayoutConfig`	Provider / 内置预设
fixedColCount	固定列数	`number`	-
defaultRowsNumber	折叠最大行数	`number`	-（不启用折叠）
defaultCollapsed	未用 `v-model:collapsed` 时的初值	`boolean`	`false`
showCollapseToggle	溢出时是否显示展开/收起	`boolean`	`true`
forceWrap	展开态操作区是否独占一行	`boolean`	`false`
compact	紧凑间距与标签字号	`boolean`	`false`
colGap / rowGap	覆盖网格间距	`number \| string`	-
minWidth / maxWidth	表单宽约束	`number \| string`	-

操作按钮与行为

属性名	描述	类型	默认值
showSearch / showReset	是否展示内置按钮	`boolean`	`true`
searchText / resetText	文案	`string`	查询 / 重置
loading	查询按钮 loading	`boolean`	`false`
searchHandler / resetHandler	拦截 emit 的回调	`function`	-
toggleHandler	折叠变化拦截	`(collapsed: boolean) => void`	-
immediate	挂载后触发一次查询分发	`boolean`	`false`
immediateDebounce	表单变更防抖毫秒	`number`	-

标签与表单项

属性名	描述	类型	默认值
labelWidth	`el-form` label-width	`number \| string`	-
labelPosition	含 `justify`	`'left' \| 'right' \| 'top' \| 'justify'`	-
autoLabelWidth	`label-width="auto"`	`boolean`	`false`
labelOverflow	仅 `true`	`true`	-
labelOverflowType	wrap / nowrap / ellipsis	`string`	-
size	透传 `el-form` size	`string`	-
disabled	透传 `el-form` disabled	`boolean`	`false`
activeTab	`visible(payload)` 的 tab	`string`	`''`
scrollToError	透传 `el-form`	`boolean`	-
scrollIntoViewOptions	透传 `el-form`	`object \| boolean`	-

类型说明

import type { ElFormQueryProps, EllFormQueryFieldSchema } from 'element-plus-lab'
import type { EllFieldSchema } from 'element-plus-lab'

EllFormQueryFieldSchema 与 EllFieldSchema 等价（查询栈子集）。

与 packages/components/form-query/src/types.ts 对齐的 Props 摘要

import type { EllGridLayoutConfig, EllGridPresetName } from '@element-plus-lab/utils'
import type { FormInstance } from 'element-plus'
import type { EllFieldSchema } from 'element-plus-lab'

/** schema 元素，与 EllFieldSchema 等价 */
export type EllFormQueryFieldSchema = EllFieldSchema

export interface ElFormQueryProps {
  modelValue: Record<string, unknown>
  schema: EllFormQueryFieldSchema[]
  uid?: string
  grid?: EllGridPresetName | EllGridLayoutConfig
  fixedColCount?: number
  defaultRowsNumber?: number
  defaultCollapsed?: boolean
  showCollapseToggle?: boolean
  forceWrap?: boolean
  showSearch?: boolean
  showReset?: boolean
  searchText?: string
  resetText?: string
  loading?: boolean
  searchHandler?: (model: Record<string, unknown>, formRef: FormInstance | undefined) => void
  resetHandler?: (model: Record<string, unknown>, formRef: FormInstance | undefined) => void
  toggleHandler?: (collapsed: boolean) => void
  scrollToError?: boolean
  scrollIntoViewOptions?: ScrollIntoViewOptions | boolean
  immediate?: boolean
  immediateDebounce?: number
  labelWidth?: number | string
  labelPosition?: 'left' | 'right' | 'top' | 'justify'
  autoLabelWidth?: boolean
  labelOverflow?: true
  labelOverflowType?: 'wrap' | 'nowrap' | 'ellipsis'
  compact?: boolean
  colGap?: number | string
  rowGap?: number | string
  size?: 'large' | 'default' | 'small'
  disabled?: boolean
  activeTab?: string
  minWidth?: number | string
  maxWidth?: number | string
}

v-model:collapsed 由 SFC defineModel 提供，上表未重复列出；发布版以包内 d.ts 为准。

贡献者

jenemy

页面历史

最后编辑于大约 5 小时前

查看完整历史

ElFormQuery ​

基础用法 ​

与 FormLayout / FormBuilder 的分工 ​

网格与间距 ​

折叠与展开 ​

查询、重置与自动查询 ​

标签位置与溢出（整表） ​

Schema 字段要点（EllFormQueryFieldSchema） ​

联动与显隐 ​

操作区与 portal-vue ​

表单宽度与滚动 ​

插槽 ​

事件 ​

暴露（defineExpose） ​

Props ​

模型与 schema ​

网格与布局 ​

操作按钮与行为 ​

标签与表单项 ​

类型说明 ​

相关 ​

贡献者