目录

Formily v2.x 完整教程——Vue 3 + Element Plus 可视化拖拽表单设计器

1. Formily 核心概念

1.1 整体架构——MVVM 模式

1.2 Form 与 Field 的区别与关系

1.3 SchemaField 与递归渲染

1.4 响应式原理（@formily/reactive）

1.5 JSON Schema 协议与 x- 扩展属性

完整的 x- 扩展属性列表

内置表达式作用域

1.6 Path 路径系统

2. @formily/core 详解

2.1 createForm 完整参数

2.2 Form 实例的核心 API

2.3 createField 与字段模型

2.4 校验系统

2.5 联动系统

命令式联动（Effects API）

声明式联动（x-reactions 协议）

主动联动 vs 被动联动

3. @formily/vue 详解

3.1 核心组件

3.2 createSchemaField 完整用法

3.3 三种开发模式

模式一：JSON Schema（推荐用于表单设计器）

模式二：Markup Schema

模式三：Template 原始模式

3.4 connect / mapProps / mapReadPretty

3.5 Vue 3 Composition API 集成

4. @formily/element-plus 详解

4.1 安装

4.2 完整组件列表

输入类组件

布局类组件

自增类组件

操作类组件

阅读态组件

4.3 FormItem 装饰器详解

4.4 FormGrid 网格布局

4.5 ArrayItems 自增列表

5. @formily/json-schema 详解

5.1 Schema 类

5.2 Schema 实例方法

5.3 Schema 编译与表达式

5.4 递归 Schema 与 $ref

5.5 Schema 扩展属性（x- 完整列表）

6. @formily/validator 详解

6.1 内置校验规则

6.2 自定义校验函数（三种返回值）

6.3 异步校验

6.4 校验触发时机

7. 实战最佳实践

7.1 动态表单（增删字段、条件渲染）

动态增减字段

条件渲染（字段联动显隐）

7.2 表单联动（跨字段校验）

7.3 自定义组件开发指南

7.4 表单设计器开发思路（拖拽 + Schema 驱动）

7.5 性能优化

大表单优化

懒加载

7.6 常见坑点与解决方案

8. Formily vs 其他方案对比

8.1 对比总表

8.2 Formily 的优势与适用场景

8.3 Vue 生态内的选择建议

附录：安装与项目配置

Formily v2.x 完整教程——Vue 3 + Element Plus 可视化拖拽表单设计器

适用版本：Formily v2.3.x（当前最新稳定版）  

技术栈：Vue 3 (Composition API) + @formily/core + @formily/vue + @formily/element-plus  

完成日期：2026-07-23  

主要参考来源：Formily 官方文档 (formilyjs.org)、(vue.formilyjs.org)、(element-plus.formilyjs.org)、(core.formilyjs.org)、(reactive.formilyjs.org)，GitHub 源码 (github.com/alibaba/formily)

1. Formily 核心概念

1.1 整体架构——MVVM 模式

Formily 采用 MVVM（Model-View-ViewModel） 设计模式，将表单系统清晰地分为三层 (vue.formilyjs.org)：

@formily/vue 是将 ViewModel 和 View 绑定起来的胶水层，实现绑定的手段主要有 useField、connect 和 mapProps。

1.2 Form 与 Field 的区别与关系

Form（表单实例）

├── values          ← 表单数据（所有字段的值集合）

├── initialValues   ← 初始值

├── fields          ← 所有字段实例的集合

├── valid           ← 是否整体合法

├── errors          ← 整体错误集合

└── lifecycle       ← 表单生命周期

   │

   ├── Field（普通字段）

   │   ├── value / initialValue

   │   ├── valid / errors / warnings

   │   ├── visible / hidden / display

   │   ├── editable / readOnly / disabled

   │   ├── decorator (FormItem) + component (Input/Select...)

   │   └── reactions / validator

   │

   ├── VoidField（虚拟字段）

   │   ├── 没有 value，不对应数据结构中的路径

   │   ├── 用于布局容器（如 FormGrid、Card）

   │   └── 拥有 visible / display / editable 等状态

   │

   ├── ArrayField（数组字段）

   │   ├── value 是数组类型

   │   └── 提供 push / pop / shift / unshift / move 等操作方法

   │

   └── ObjectField（对象字段）

       ├── value 是对象类型

       └── 子属性自动创建为子 Field

关键字段类型对比：

1.3 SchemaField 与递归渲染

SchemaField 是 协议驱动渲染 的入口，内部使用 RecursionField 实现递归渲染 (vue.formilyjs.org)：

SchemaField（入口）

 └── RecursionField（递归渲染器）

      ├── 非 object/array → 直接渲染 x-component 对应的组件

      ├── object → 遍历 properties，递归调用 RecursionField

      └── array → 渲染 x-component（如 ArrayTable），内部由组件自行递归

SchemaField vs RecursionField：

• SchemaField 支持 Markup 语法，渲染整体 Schema 协议

• RecursionField 只能基于 JSON Schema 渲染，渲染局部 Schema 协议

1.4 响应式原理（@formily/reactive）

Formily 的响应式系统借鉴了 MobX 的实现，基于 Proxy 拦截 get 和 set 操作 (reactive.formilyjs.org)。

核心机制：

// 1. observable - 将对象变为可观察的

import { observable, autorun, reaction, observe, batch } from '@formily/reactive'

const obs = observable({

 aa: { bb: 123 },

 cc: { dd: 456 }

})

// 2. autorun - 自动收集 get 依赖，set 时重新执行

autorun(() => {

 console.log('aa.bb =', obs.aa.bb) // 首次执行 + 依赖变化时执行

})

obs.aa.bb = 321 // 触发 autorun 重新执行

// 3. reaction - 分离数据追踪和副作用

reaction(

 () => obs.aa.bb,        // 追踪函数

 (value) => console.log(value) // 副作用函数

)

// 4. observe - 更底层的监听，输出变更信息

observe(obs, (change) => {

 console.log('change:', change) // { type: 'set', key, value, oldValue }

})

// 5. batch - 批量更新，减少重复触发

batch(() => {

 obs.aa.bb = 100

 obs.cc.dd = 200

 // 只触发一次副作用

})

精准更新原理：

• 使用栈式 ReactionStack 记录当前执行上下文

• 组件通过 observer 包裹后，渲染时自动收集依赖

• 当某个字段值变化时，只有依赖该字段的组件重新渲染（O(1) 渲染复杂度）

• 使用位掩码（Bitmask） 快速对比字段状态变更类型（value / visible / disabled）

1.5 JSON Schema 协议与 x- 扩展属性

Formily 在标准 JSON Schema 基础上，扩展了 x-* 属性来表达 UI 和逻辑协议 (vue.formilyjs.org)：

完整的 x- 扩展属性列表

更多内容详情见 本站资源    https://www.changliuyun.com/workspace/word/PZjEdbY5QkFaqAReaxKncyXZDz4q