Formily FormCollapse 折叠面板组件实战:Schema 场景下的布局折叠与状态控制

原创2026-09-23 13:47:271,337 阅读
文章标签:前端UI组件

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 的核心结构约定:

  1. 折叠容器:使用 SchemaField.Void(无字段值节点)承载 x-component="FormCollapse",并通过 x-component-props 传入 formCollapse 模型;
  2. 折叠面板:每个面板同样是 SchemaField.Void,x-component="FormCollapse.CollapsePanel",面板标题通过 x-component-props={{ header: 'A1' }} 指定,name 即面板的唯一标识(后续所有 API 都以该 name 作为 key);
  3. 面板内容:面板内部的业务字段(如 aaa、bbb、ccc)正常使用 FormItem 装饰与 Input 组件,Formily 会自动将它们递归渲染进对应的 Collapse.Panel 中(对应源码 form-collapse/index.tsx 中的 RecursionField 递归渲染逻辑);
  4. 外部控制:既可以用 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 中直接透传。
登录后查看全文
formily