Formily FormCollapse 折叠面板组件实战:Schema 场景下的布局折叠与状态控制
Formily FormCollapse 折叠面板组件实战:Schema 场景下的布局折叠与状态控制
导读
FormCollapse 是 Formily 基于 Ant Design Collapse 封装的折叠面板布局组件,专门用于解决空间受限场景下的长表单分组收纳问题。本文以 @formily/antd 中的 FormCollapse.zh-CN.md 为核心,结合 form-collapse/index.tsx 源码,完整讲解它在 Markup Schema 与 JSON Schema 两种写法下的用法、formCollapse 模型的创建与控制 API,以及面板头部错误角标等内置增强能力。读完本文,你将掌握如何在表单中快速搭建可折叠分区,并通过编程方式精准控制面板的展开与收起。
注意:
FormCollapse只能用于 Schema 场景(即配合createSchemaField与SchemaField使用),不适用于纯 JSX 组件模式。
一、为什么需要 FormCollapse
在注册、订单、设置等业务表单中,字段数量往往远超单屏承载能力。如果全部平铺展示,不仅页面冗长,还会让用户产生视觉压迫感。折叠面板(Collapse)是一种经典的分组收纳交互:每个面板头部展示分组标题,点击即可展开/收起对应字段组,从而在有限空间内呈现更多信息。
Formily 的 FormCollapse 正是在此需求上为表单场景量身定制的能力:
- Schema 驱动:面板结构直接由 Schema 描述,无需手写组件树;
- 响应式状态:通过
formCollapse模型管理激活面板,状态变化自动驱动视图更新; - 表单语义增强:面板内字段的校验错误会自动以角标形式展示在面板头部,用户在折叠状态下也能感知校验失败;
- 与 Formily 生态打通:可借助
form.query()等字段查询 API 联动控制面板的显隐。
二、Markup Schema 案例:三步搭出折叠表单
Markup Schema 是 Formily 推荐的 JSX 风格 Schema 写法。下面的完整示例来自 FormCollapse.zh-CN.md,它创建了一个包含三个面板(A1/A2/A3)、每个面板各含一个必填输入框的折叠表单:
import React from 'react'
import {
FormCollapse,
FormLayout,
FormItem,
Input,
FormButtonGroup,
Submit,
} from '@formily/antd'
import { createForm } from '@formily/core'
import { FormProvider, createSchemaField } from '@formily/react'
import { Button } from 'antd'
const SchemaField = createSchemaField({
components: {
FormItem,
FormCollapse,
Input,
},
})
const form = createForm()
const formCollapse = FormCollapse.createFormCollapse()
export default () => {
return (
<FormProvider form={form}>
<FormLayout labelCol={6} wrapperCol={10}>
<SchemaField>
<SchemaField.Void
title="折叠面板"
x-decorator="FormItem"
x-component="FormCollapse"
x-component-props={{
formCollapse,
}}
>
<SchemaField.Void
name="panel1"
x-component="FormCollapse.CollapsePanel"
x-component-props={{ header: 'A1' }}
>
<SchemaField.String
name="aaa"
title="AAA"
x-decorator="FormItem"
required
x-component="Input"
/>
</SchemaField.Void>
<SchemaField.Void
name="panel2"
x-component="FormCollapse.CollapsePanel"
x-component-props={{ header: 'A2' }}
>
<SchemaField.String
name="bbb"
title="BBB"
x-decorator="FormItem"
required
x-component="Input"
/>
</SchemaField.Void>
<SchemaField.Void
name="panel3"
x-component="FormCollapse.CollapsePanel"
x-component-props={{ header: 'A3' }}
>
<SchemaField.String
name="ccc"
title="CCC"
x-decorator="FormItem"
required
x-component="Input"
/>
</SchemaField.Void>
</SchemaField.Void>
</SchemaField>
<FormButtonGroup.FormItem>
<Button
onClick={() => {
form.query('panel3').take((field) => {
field.visible = !field.visible
})
}}
>
显示/隐藏最后一个Tab
</Button>
<Button
onClick={() => {
formCollapse.toggleActiveKey('panel2')
}}
>
切换第二个Tab
</Button>
<Submit onSubmit={console.log}>提交</Submit>
</FormButtonGroup.FormItem>
</FormLayout>
</FormProvider>
)
}
这个案例揭示了 FormCollapse 的核心结构约定:
- 折叠容器:使用
SchemaField.Void(无字段值节点)承载x-component="FormCollapse",并通过x-component-props传入formCollapse模型; - 折叠面板:每个面板同样是
SchemaField.Void,x-component="FormCollapse.CollapsePanel",面板标题通过x-component-props={{ header: 'A1' }}指定,name即面板的唯一标识(后续所有 API 都以该 name 作为 key); - 面板内容:面板内部的业务字段(如
aaa、bbb、ccc)正常使用FormItem装饰与Input组件,Formily 会自动将它们递归渲染进对应的Collapse.Panel中(对应源码 form-collapse/index.tsx 中的RecursionField递归渲染逻辑); - 外部控制:既可以用
form.query('panel3').take(...)修改字段visible来显隐整个面板,也可以用formCollapse.toggleActiveKey('panel2')编程切换面板展开状态。
三、JSON Schema 案例:同一能力的配置化形态
如果你的表单结构来自后端下发或动态配置,可以使用 JSON Schema 形态。两种写法的 Schema 语义完全一致,只是从 JSX 换成了纯 JSON 对象,关键差异有两点:
- 所有
x-前缀的属性从驼峰式改为短横线式(x-decorator、x-component、x-component-props); formCollapse模型通过scope注入:x-component-props: { formCollapse: '{{formCollapse}}' }中的双花括号表达式会在渲染时从scope中取值。
import React from 'react'
import {
FormCollapse,
FormItem,
FormLayout,
Input,
FormButtonGroup,
Submit,
} from '@formily/antd'
import { createForm } from '@formily/core'
import { FormProvider, createSchemaField } from '@formily/react'
import { Button } from 'antd'
const SchemaField = createSchemaField({
components: {
FormItem,
FormCollapse,
Input,
},
})
const form = createForm()
const formCollapse = FormCollapse.createFormCollapse()
const schema = {
type: 'object',
properties: {
collapse: {
type: 'void',
title: '折叠面板',
'x-decorator': 'FormItem',
'x-component': 'FormCollapse',
'x-component-props': {
formCollapse: '{{formCollapse}}',
},
properties: {
panel1: {
type: 'void',
'x-component': 'FormCollapse.CollapsePanel',
'x-component-props': {
header: 'A1',
},
properties: {
aaa: {
type: 'string',
title: 'AAA',
'x-decorator': 'FormItem',
required: true,
'x-component': 'Input',
},
},
},
panel2: {
type: 'void',
'x-component': 'FormCollapse.CollapsePanel',
'x-component-props': {
header: 'A2',
},
properties: {
bbb: {
type: 'string',
title: 'BBB',
'x-decorator': 'FormItem',
required: true,
'x-component': 'Input',
},
},
},
panel3: {
type: 'void',
'x-component': 'FormCollapse.CollapsePanel',
'x-component-props': {
header: 'A3',
},
properties: {
ccc: {
type: 'string',
title: 'CCC',
'x-decorator': 'FormItem',
required: true,
'x-component': 'Input',
},
},
},
},
},
},
}
export default () => {
return (
<FormProvider form={form}>
<FormLayout labelCol={6} wrapperCol={10}>
<SchemaField schema={schema} scope={{ formCollapse }} />
<FormButtonGroup.FormItem>
<Button
onClick={() => {
form.query('panel3').take((field) => {
field.visible = !field.visible
})
}}
>
显示/隐藏最后一个Tab
</Button>
<Button
onClick={() => {
formCollapse.toggleActiveKey('panel2')
}}
>
切换第二个Tab
</Button>
<Submit onSubmit={console.log}>提交</Submit>
</FormButtonGroup.FormItem>
</FormLayout>
</FormProvider>
)
}
两种写法下,FormButtonGroup.FormItem 中的按钮与提交逻辑完全复用,验证了"同一能力、两种 Schema 载体"的设计理念。
四、FormCollapse API 详解
4.1 FormCollapse 组件属性
| 属性名 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| formCollapse | IFormCollapse | 传入通过 createFormCollapse/useFormCollapse 创建出来的模型 | - |
formCollapse 是组件与模型之间的桥梁:组件从模型读取 activeKeys 决定展开哪些面板,用户点击面板时通过 onChange 回调写回模型(见 源码实现)。因此,只要持有模型引用,就能在任意位置(按钮、联动逻辑、异步回调)控制面板状态。
除 formCollapse 外,其余属性(如 accordion 手风琴模式、bordered 边框等)直接透传给 Ant Design 的 Collapse 组件,可参考 Ant Design Collapse 官方文档。
4.2 FormCollapse.CollapsePanel
对应 Schema 中的 x-component="FormCollapse.CollapsePanel",其 props 透传给 Ant Design Collapse.Panel。在 Markup Schema 中面板标题由 x-component-props={{ header: 'A1' }} 指定,在 JSON Schema 中同理。注意源码中该组件本身只做占位透传(index.tsx),实际渲染的是内部 usePanels 从 Schema 中扫描出的面板集合——也就是说,面板的增删本质上是对 Schema 子节点的增删。
值得留意的是,usePanels 会过滤掉 display === 'none' | 'hidden' 的面板(源码 L39-L59),这解释了为什么示例中通过 field.visible = false 就能隐藏整个面板——它是 Formily 字段显隐机制与面板扫描逻辑协同的结果。
4.3 FormCollapse.createFormCollapse
createFormCollapse 是创建折叠面板响应式模型的工厂函数,其类型签名如下:
type ActiveKey = string | number
type ActiveKeys = string | number | Array<string | number>
interface createFormCollapse {
(defaultActiveKeys?: ActiveKeys): IFormCollapse
}
interface IFormCollapse {
//激活主键列表
activeKeys: ActiveKeys
//是否存在该激活主键
hasActiveKey(key: ActiveKey): boolean
//设置激活主键列表
setActiveKeys(keys: ActiveKeys): void
//添加激活主键
addActiveKey(key: ActiveKey): void
//删除激活主键
removeActiveKey(key: ActiveKey): void
//开关切换激活主键
toggleActiveKey(key: ActiveKey): void
}
各成员的行为与源码一一对应(index.tsx L61-L99):
| 成员 | 作用 | 实现要点 |
|---|---|---|
activeKeys |
当前激活面板 key 列表 | 支持单个值或数组,也可传空 |
hasActiveKey(key) |
判断某面板是否激活 | 数组用 includes 判断,单值用 == 比较 |
setActiveKeys(keys) |
整体设置激活列表 | 直接覆盖 activeKeys |
addActiveKey(key) |
追加激活某面板 | 已激活则忽略;利用 toArr 将单值归一为数组 |
removeActiveKey(key) |
移除某面板激活状态 | 数组形态过滤该项;单值形态重置为空 |
toggleActiveKey(key) |
开关切换面板状态 | 内部组合 hasActiveKey + add/removeActiveKey |
调用建议:在 React 组件外部(如 const formCollapse = FormCollapse.createFormCollapse())创建一次即可复用;也可以不传入 formCollapse,让组件内部基于 defaultActiveKey 自动创建一个模型(源码 useMemo 分支 L106-L110),但此时外部无法编程控制,实际项目中通常显式传入。
默认激活的用法示例:
// 默认展开 panel1 与 panel2
const formCollapse = FormCollapse.createFormCollapse(['panel1', 'panel2'])
// 手风琴模式下默认展开第一块
const formCollapse2 = FormCollapse.createFormCollapse('panel1')
4.4 关于 useFormCollapse
文档在组件属性表中提到了 useFormCollapse(可由 createFormCollapse/useFormCollapse 创建模型)。在当前仓库的 @formily/antd 源码中,useFormCollapse 尚未作为独立导出存在,FormCollapse.createFormCollapse 是实际可用的创建入口,因此建议统一使用 createFormCollapse,它同样满足属性表的模型要求。
五、源码级增强能力:错误角标与递归渲染
除了折叠本身,FormCollapse 还内建了两个对表单场景极具价值的增强:
1. 面板头部错误角标(badgedHeader)
源码 L119-L132 会在渲染每个面板标题时,通过 field.form.queryFeedbacks({ type: 'error', address: 该面板地址 + '.*' }) 查询面板内所有字段的错误反馈。若存在校验错误,面板头部会以 Ant Design Badge 形式显示错误数量角标。这意味着用户无需逐块展开面板即可知道哪个分组校验未通过,配合折叠布局能显著提升长表单的校验体验。面板内字段的必填(required)与校验规则仍然按 Formily 标准机制生效。
2. 面板内容递归渲染
面板内的 Schema 子节点通过 RecursionField 递归渲染,因此面板内可以自由嵌套 FormItem、Input 乃至其他布局组件(如 FormGrid、嵌套折叠等),字段数据流与表单模型自动打通,无需任何额外桥接代码。
3. 模型基于响应式内核
createFormCollapse 使用 @formily/reactive 的 model() 创建响应式模型,并通过 markRaw 标记避免被过度代理(L61-L99)。组件外层包裹 observer,因此 activeKeys 的任何修改都会精确触发视图更新——这正是 toggleActiveKey 等 API 能在按钮回调中"即点即用"的底层原理。
六、与其他布局组件的选型对比
在 Formily 的布局组件体系中,折叠类布局还有 FormStep、FormTab 与 ArrayCollapse(数组折叠),选择时可以参考:
- FormCollapse:无字段值分组收纳,适合"同屏展示但按主题折叠"的静态表单分组;
- FormTab:适合需要"一次只看一个分组"的标签页场景;
- FormStep:适合分步骤完成的流程型表单;
- ArrayCollapse:面向数组字段,每个折叠项对应数组的一个元素(增删操作由数组字段驱动)。
从源码结构看,FormCollapse 与 FormTab、FormStep 采用了几乎一致的"外部模型 + Schema 扫描面板 + 递归渲染"架构,这也意味着你学会其一即可触类旁通。
七、小结与最佳实践
FormCollapse仅用于 Schema 场景,且必须配合createSchemaField注册组件;- 面板结构 = 容器
Void(x-component="FormCollapse")+ 若干面板Void(x-component="FormCollapse.CollapsePanel"),面板name即操作 key; - 创建一次
formCollapse模型并在组件与外部逻辑间共享,即可获得完整的编程控制能力(setActiveKeys/addActiveKey/removeActiveKey/toggleActiveKey/hasActiveKey); - 面板显隐可通过
form.query('xxx').take(field => field.visible = !field.visible)与 Formily 字段联动体系无缝结合; - 校验错误角标是内置能力,无需额外配置即可在面板头部反馈分组内错误数量;
- 其余交互属性(手风琴、边框、动画等)沿用 Ant Design Collapse 的 API,可在组件 props 中直接透传。