Formily Element 折叠面板(FormCollapse)完全指南:Schema 驱动的折叠表单布局实战

原创2026-09-22 17:05:012,293 阅读
文章标签:前端UI组件

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:

  1. 显式传入 activeKey prop(优先级最高);
  2. 模型上的 activeKeys(非空时);
  3. attrs.accordion 为真时,仅取第一个面板的 name(手风琴模式);
  4. 兜底返回所有面板 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 校验、联动体系的深度集成。

登录后查看全文
formily