ElFormLayout / ElFormLayoutItem

在 el-form 内提供 CSS Grid 布局：ElFormLayout 解析断点列数或 fixedColCount；ElFormLayoutItem 封装 el-form-item，并支持 表单项级 labelConfig（EllFormFieldLabelConfig，与 ElFormQuery / ElFormBuilder 字段侧标签能力对齐）。ElFormQuery 同样支持 grid + fixedColCount 两种列数方式。

使用方式

需与 el-form 组合：ElFormLayout 只负责网格容器样式，校验与 model 仍在表单上。
grid 未传时继承 ElLabConfigProvider 的默认网格，再无则使用内置 element-plus 预设。
源码：packages/components/form-layout。

基础用法

三列固定网格：第一项占 1 列，第二项 span=2 占两列；间距由 grid.colGap / rowGap 控制。

vue

<el-form :model="model" label-position="left" label-width="100px">
  <ElFormLayout :fixed-col-count="3" :grid="{ colGap: 16, rowGap: 8 }">
    <ElFormLayoutItem label="姓名" prop="name">
      <el-input v-model="model.name" />
    </ElFormLayoutItem>
    <ElFormLayoutItem label="手机" prop="phone" :span="2">
      <el-input v-model="model.phone" />
    </ElFormLayoutItem>
  </ElFormLayout>
</el-form>

`labelConfig`：标签对齐与溢出

字段	说明
`labelWidth`	数值或带单位字符串，合并为 `el-form-item` 的 `label-width`
`labelPosition`	`left` / `right` / `top` / `''` 透传；`justify` 时 EP 仍为 `left`，由组件用插槽做字间撑满
`autoLabelWidth`	`true` 时等价 `label-width="auto"`
`labelOverflow`	仅允许 `true`；未传 `labelOverflowType` 时等价 `wrap`
`labelOverflowType`	`wrap` / `nowrap` / `ellipsis`；需在非 `autoLabelWidth`、非 `justify` 下使用
`description`	标签旁说明（`ElFormLayoutItem` 上与 `ElFormBuilder` 字段 schema 一致；见类型 `EllFormFieldLabelConfig`）
`renderLabel`	自定义标签渲染 `(label: string) => VNodeChild`，与 `description` 等组合行为同 Builder

行为要点：

ellipsis：始终挂载单行省略相关类；label-row 使用 max-width:100% + min-width:0 + overflow:hidden，防止插槽外层被长文案撑开而导致 text-overflow: ellipsis 不显示 …。el-tooltip 仅在实测溢出时可用。
wrap：仅实测溢出的项加样式；自动换行、无行尾省略号（不使用 line-clamp 截断）。
nowrap：在配置了 labelWidth 时不再向 el-form-item 传固定 label-width，标签列随内容伸展，控件区 min-width:0 可收缩。
justify：勿与 autoLabelWidth 或上述溢出策略混用；溢出类需**固定 labelWidth。

API

ElFormLayout Props

属性名	描述	类型	默认值
grid	预设名字符串或 `EllGridLayoutConfig`（断点、`colGap`/`rowGap`）	`EllGridPresetName \| EllGridLayoutConfig`	继承 Provider / 内置预设
fixedColCount	固定列数 ≥1，不随容器宽度变化	`number`	-

ElFormLayout 方法

名称	说明
`currentColCount`（expose）	当前解析列数

ElFormLayoutItem Props

属性名	描述	类型	默认值
span	占 grid 列数，`≤1` 或未传为 1 列	`number`	-
gridColumn	直接写 CSS `grid-column`，优先于 `span`	`string`	-
label	标签文案	`string`	-
prop	字段名	`FormItemProp`	-
rules	校验规则	`Arrayable<FormItemRule>`	-
message	映射为 `el-form-item` `error`	`string`	-
labelConfig	见上表（含可选 `description` / `renderLabel`）	`EllFormFieldLabelConfig`	-
formItemConfig	其余透传 `el-form-item`（与 `labelConfig` 冲突时 `labelWidth`/`labelPosition` 以 `labelConfig` 为准）	`Record<string, unknown>`	-
class	挂在根 `el-form-item`，与 `gridColumn` / `span` 合并样式	`unknown`	-
style	同上	`StyleValue`	-

与 ElFormBuilder 联动

若祖先树中存在 ElFormBuilder（或同源 provide 的字段注册表），且本项配置了 prop，则 ElFormLayoutItem 会注册 getFormItemRef，便于 Builder 通过字段 key 取到对应 el-form-item 实例。

ElFormLayoutItem 方法

名称	说明
`formItemRef`（expose）	内层 `el-form-item` 实例

Slots

ElFormLayout

插槽名	描述
default	子级 `ElFormLayoutItem`

ElFormLayoutItem

插槽名	描述
default	表单控件
label	自定义标签（使用时不走内置 justify / ellipsis 插槽）
error	与 `el-form-item#error` 一致

类型说明

以下为 element-plus-lab 主包已 export type 的标签相关类型，业务可按需：

import type { EllFormFieldLabelConfig, EllFormLayoutItemLabelConfig } from 'element-plus-lab'

显示类型声明

import type { VNodeChild } from 'vue'

/** 表单项级标签行为（与 ElFormQuery / ElFormLayoutItem 对齐）。 */
export interface EllFormLayoutItemLabelConfig {
  labelWidth?: number | string
  labelPosition?: 'left' | 'right' | 'top' | 'justify' | ''
  autoLabelWidth?: boolean
  labelOverflow?: true
  labelOverflowType?: 'wrap' | 'nowrap' | 'ellipsis'
}

/** 在 EllFormLayoutItemLabelConfig 上扩展 Builder / 字段 schema 常用项。 */
export interface EllFormFieldLabelConfig extends EllFormLayoutItemLabelConfig {
  description?: string
  renderLabel?: (label: string) => VNodeChild
}

实现以 @element-plus-lab/utils 中 form-layout-label.ts / form-schema.ts 为准；文档摘抄便于对照，发布版以包内 d.ts 为准。

贡献者

jenemy

页面历史

最后编辑于大约 5 小时前

查看完整历史

ElFormLayout / ElFormLayoutItem ​

基础用法 ​

labelConfig：标签对齐与溢出 ​

API ​

ElFormLayout Props ​

ElFormLayout 方法 ​

ElFormLayoutItem Props ​

ElFormLayoutItem 方法 ​

Slots ​

相关 ​

类型说明 ​

贡献者