Formily Element 折叠面板(FormCollapse)完全指南:Schema 驱动的折叠表单布局实战
Formily Element 折叠面板(FormCollapse)完全指南:Schema 驱动的折叠表单布局实战
在表单字段多、页面空间有限的业务场景中,折叠面板是"分面收纳"布局的首选方案。本文以 Formily 生态的 Element UI 适配层(
@formily/element)为背景,系统讲解折叠面板组件FormCollapse的适用场景、Markup Schema 与 JSON Schema 两种写法、createFormCollapse模型 API 的完整类型与实现原理,并深入源码剖析面板收集、激活键推导、错误徽标渲染等底层细节,帮助你在 Vue 2 + Element UI 项目中落地可复用的折叠表单。
FormCollapse 是 Formily 在 Element UI 组件库上的封装组件,用于在布局空间要求较高的表单场景中,将表单项分组收纳进可折叠面板。与普通 el-collapse 不同,它深度绑定 Formily 的 Schema 体系与响应式模型:每个面板对应一个 void 类型的 Schema 节点,面板内部再递归渲染真实字段。需要特别注意的是——它只能用在 Schema 场景(即 Markup Schema 或 JSON Schema),不能像普通组件那样在 el-form 中手工堆叠使用。
一、快速开始:Markup Schema 案例
在模板中,通过 createSchemaField 注册 FormCollapse 与 FormItem、Input 等字段组件,随后用 SchemaVoidField 声明折叠面板容器与面板项。完整可运行示例位于 markup-schema.vue:
<template>
<Form :form="form" :label-col="6" :wrapper-col="10">
<SchemaField>
<SchemaVoidField
type="void"
title="折叠面板"
x-decorator="FormItem"
x-component="FormCollapse"
:x-component-props="{ formCollapse }"
>
<SchemaVoidField
type="void"
name="tab1"
x-component="FormCollapse.Item"
:x-component-props="{ title: 'A1' }"
>
<SchemaStringField
name="aaa"
x-decorator="FormItem"
title="AAA"
required
x-component="Input"
/>
</SchemaVoidField>
<!-- tab2 / tab3 结构相同,面板内分别放 bbb / ccc 字段 -->
</SchemaVoidField>
</SchemaField>
<FormButtonGroup alignFormItem>
<Button
@click="
() => {
form.query('tab3').take((field) => {
field.visible = !field.visible
})
}
"
>
显示/隐藏最后一个Tab
</Button>
<Button @click="formCollapse.toggleActiveKey('tab2')">
切换第二个Tab
</Button>
<Submit @submit="log">提交</Submit>
</FormButtonGroup>
</Form>
</template>
<script>
import { createForm } from '@formily/core'
import { createSchemaField } from '@formily/vue'
import {
FormItem,
FormCollapse,
FormButtonGroup,
Submit,
Input,
Form,
} from '@formily/element'
import { Button } from 'element-ui'
const SchemaField = createSchemaField({
components: {
FormItem,
FormCollapse,
Input,
},
})
export default {
components: { Form, FormButtonGroup, Button, Submit, ...SchemaField },
data() {
const form = createForm()
const formCollapse = FormCollapse.createFormCollapse()
return { form, formCollapse }
},
methods: {
log(values) {
console.log(values)
},
},
}
</script>
要点拆解:
- 容器声明:外层
SchemaVoidField用x-component="FormCollapse"声明折叠面板容器,type="void"表示它不产生表单值;x-component-props.formCollapse传入通过FormCollapse.createFormCollapse()创建的模型实例。 - 面板声明:每个面板是内层
SchemaVoidField,name即面板唯一标识(后续操作激活状态的 key),x-component="FormCollapse.Item",标题通过x-component-props.title设置。 - 字段挂载:面板内部的
SchemaStringField(如aaa)才是真正持有数据的字段,面板展开/收起只影响渲染,不影响字段的值结构与校验逻辑。 - 联动控制:面板的显隐可以通过
form.query('tab3').take(field => field.visible = !field.visible)动态切换;激活状态则通过formCollapse.toggleActiveKey('tab2')直接操作模型。
二、JSON Schema 案例
如果你使用服务端下发的 JSON Schema 驱动表单,写法与 Markup Schema 完全等价,完整示例见 json-schema.vue。核心差异在于用 :schema="schema" 传入普通对象,并通过 :scope="{ formCollapse }" 将模型注入 Schema 表达式作用域:
<template>
<FormProvider :form="form">
<FormLayout :label-col="6" :wrapper-col="10">
<SchemaField :schema="schema" :scope="{ formCollapse }" />
<FormButtonGroup alignFormItem>
<Button @click="formCollapse.toggleActiveKey('tab2')">
切换第二个Tab
</Button>
<Submit @submit="log">提交</Submit>
</FormButtonGroup>
</FormLayout>
</FormProvider>
</template>
<script>
const schema = {
type: 'object',
properties: {
collapse: {
type: 'void',
title: '折叠面板',
'x-decorator': 'FormItem',
'x-component': 'FormCollapse',
'x-component-props': {
formCollapse: '{{formCollapse}}', // scope 中的模型,表达式引用
},
properties: {
tab1: {
type: 'void',
'x-component': 'FormCollapse.Item',
'x-component-props': { title: 'A1' },
properties: {
aaa: {
type: 'string',
title: 'AAA',
'x-decorator': 'FormItem',
required: true,
'x-component': 'Input',
},
},
},
// tab2 / tab3 结构相同
},
},
},
}
</script>
JSON Schema 写法中,formCollapse: '{{formCollapse}}' 是字符串形式的模板表达式,运行时由 scope 中的同名变量解析替换。其余节点语义与 Markup Schema 一一对应,可参照 antd 版本的 FormCollapse 文档 理解两者在 React 侧的等价结构。
三、API 详解
3.1 FormCollapse
| 属性名 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| formCollapse | IFormCollapse | 传入通过 createFormCollapse 创建出来的模型 | 无 |
formCollapse 属性控制面板的激活状态。若未传入,组件内部会自动创建一个空模型(见下节 takeActiveKeys 逻辑)。其余属性(如 accordion 手风琴模式、change 事件等)透传给 Element UI 的 el-collapse,可参考 Element UI 官方 Collapse 组件的属性、事件与插槽约定,本文不再赘述。
3.2 FormCollapse.Item
面板项组件,对应 el-collapse-item。x-component-props 中 title 为面板标题(支持插槽定制),其余属性参考 Element UI Collapse 组件。注意源码中 FormCollapseItem 本身只是一个占位透传组件(见 form-collapse/index.ts),真正渲染由外层 FormCollapse 统一完成——这解释了为什么它只能存在于 Schema 场景。
3.3 FormCollapse.createFormCollapse 与 IFormCollapse 模型
文档给出的完整类型定义如下:
type ActiveKey = string | number
type ActiveKeys = string | number | Array<string | number>
interface createFormCollapse {
(defaultActiveKeys?: ActiveKeys): IFormCollpase
}
interface IFormCollapse {
//激活主键列表
activeKeys: ActiveKeys
//是否存在该激活主键
hasActiveKey(key: ActiveKey): boolean
//设置激活主键列表
setActiveKeys(keys: ActiveKeys): void
//添加激活主键
addActiveKey(key: ActiveKey): void
//删除激活主键
removeActiveKey(key: ActiveKey): void
//开关切换激活主键
toggleActiveKey(key: ActiveKey): void
}
createFormCollapse(defaultActiveKeys?) 接受可选的默认激活主键列表;不传时 activeKeys 为 undefined,此时组件会依据 takeActiveKeys 规则自动推导初始激活面板(见下文源码解析)。
四、源码级原理剖析
FormCollapse 的完整实现位于 packages/element/src/form-collapse/index.ts,核心逻辑可拆解为四层。
4.1 响应式模型:基于 @formily/reactive 的 createFormCollapse
createFormCollapse 通过 @formily/reactive 的 model 工厂创建响应式模型(源码 L60-L98),每个方法的实现细节:
setActiveKeys(keys):直接整体赋值activeKeys。hasActiveKey(key):activeKeys为数组时用includes判断;为标量时用宽松相等(==)比较——注意这里刻意使用==,保证字符串与数字 key 可互相匹配。addActiveKey(key):先经hasActiveKey去重,再用toArr归一化后concat。removeActiveKey(key):数组模式过滤掉匹配项;标量模式则直接置空字符串。toggleActiveKey(key):有则删、无则加,实现开关切换。
模型本身通过 useFormCollapse 风格的响应式机制与表单联动,activeKeys 的变化会触发视图重渲染(组件由 @formily/reactive-vue 的 observer 包裹,见 L100)。
4.2 面板收集:usePanels 与 Schema 遍历
usePanels(源码 L41-L58)遍历容器 Schema 的所有 properties:
- 通过
collapseField.query(collapseField.address.concat(name)).take()取出对应字段实例,跳过display === 'none'或'hidden'的面板(即隐藏面板不再渲染)。 - 仅收集
x-component中包含'FormCollapse.Item'的节点,收集结果为{ name, props, schema }三元组,props合并了面板的x-component-props与 fallback key(未显式传 key 时用面板 name)。
4.3 激活键推导:takeActiveKeys 的四级优先级
组件内 takeActiveKeys(源码 L117-L123)决定最终传给 el-collapse 的 value:
- 显式传入
activeKeyprop(优先级最高); - 模型上的
activeKeys(非空时); attrs.accordion为真时,仅取第一个面板的 name(手风琴模式);- 兜底返回所有面板 name 数组(全部展开)。
面板切换时,组件将新 key 同时派发 input 事件并写回模型 setActiveKeys(L155-L160),保证"用户手动点击"与"代码控制"两条路径的状态同步。
4.4 错误徽标:面板级校验反馈
badgedHeader(源码 L125-L143)通过 field.value.form.queryFeedbacks({ type: 'error', address: ... }) 查询当前面板子树内的全部错误,命中时在标题右侧渲染 Element UI 的 Badge 徽标(数量即错误条数)。样式类名 form-collapse-errors-badge 定义在 style.scss,相关样式(collapse、collapse-item、badge 主题)由 style.ts 统一引入,组件导出入口见 packages/element/src/index.ts。
五、最佳实践与注意事项
- 仅限 Schema 场景:
FormCollapse依赖 Schema 结构(x-component="FormCollapse.Item"的识别与面板遍历),脱离 Schema 直接手写 JSX/模板没有意义。 void节点定位:面板容器与面板项均为type: 'void',不会进入表单值;若误设为object等值类型,会在 values 中产生多余结构。- 默认展开策略:想默认展开指定面板,给
createFormCollapse(['tab1', 'tab2'])传初始 key;想全部展开可直接不传(组件默认全开);手风琴模式配合accordion属性时默认只开第一个。 - key 类型一致性:
ActiveKey支持字符串与数字,但hasActiveKey对标量用==比较、对数组用includes(严格相等)。若以数组形式传入数字 key 而面板 name 是字符串,可能匹配失败,建议统一使用字符串 key。 - 显隐联动:通过
form.query(name).take(field => field.visible = ...)控制面板显隐时,隐藏面板会被usePanels直接跳过,无需额外清理激活状态。 - 校验反馈:面板内字段未通过校验时,错误徽标会自动出现在对应面板标题上,这是 FormCollapse 相比裸用
el-collapse的额外收益,无需手工编排。
至此,你已掌握在 Vue + Element UI 项目中通过 @formily/element 的 FormCollapse 组织折叠表单的完整姿势:两种 Schema 写法可任选,createFormCollapse 模型提供细粒度的激活状态控制,源码中的面板收集、激活推导与错误徽标机制则保证了它与 Formily 校验、联动体系的深度集成。