Formily：跨端高性能动态表单方案——React/Vue 双框架下的分布式状态管理与 JSON Schema 驱动解析

• 前端
• UI组件

Formily 是面向 React/React Native/Vue 2/Vue 3 的高性能表单解决方案，核心解决受控模式下表单整树渲染的性能瓶颈，并通过深度整合 JSON Schema 协议支持后端驱动渲染。本文以项目官方中文说明为主体，结合仓库源码与核心架构文档，完整讲解其背景动机、六大核心特性、跨框架组件体系以及可视化 Form Builder 能力，帮助你理解并落地这套"分布式状态管理 + 数据驱动渲染"的表单架构。

背景：受控模式下表单为何会卡顿

在 React 等前端框架中，表单组件默认走受控模式：输入框的value与onChange被框架接管，任何一次输入都会触发状态更新与组件重渲染。当表单字段数量较多、字段之间存在数据联动时，一次输入往往牵动整棵树的状态变更，整树渲染问题随之而来——这是大型业务表单页面卡顿的核心原因。

Formily 的解法是：将每个表单字段的状态从整棵树中剥离，做分布式管理。字段状态各自独立维护、独立订阅、独立渲染，谁变化就只重渲染谁，从而在联动频繁的场景下大幅降低渲染压力。与此同时，Formily 深度整合 JSON Schema 协议，让后端返回一份 Schema 即可驱动前端渲染出完整表单，解决了"后端驱动表单渲染"这类中后台系统的典型诉求。

这两点正是整个 Formily 项目的立足之本，也是理解后续所有特性的钥匙。

六大核心特性概览

官方中文说明将项目能力归纳为六点，它们共同构成了 Formily 的完整形态：

1. 可设计（Form Builder）——借助可视化表单设计器可以快速搭建表单，无需手写代码；
2. 高性能——字段分布式渲染，大大减轻 React 渲染压力；
3. 组件体系——支持 Ant Design / Fusion Next（@alifd/next）两大组件体系；
4. 写法可迁移——JSX 标签化写法与 JSON Schema 数据驱动方案无缝迁移过渡；
5. 副作用独立管理——联动、校验等副作用逻辑独立成模块，覆盖各种复杂场景；
6. 复杂布局——支持表单网格、折叠、标签页、步骤条等复杂布局方案。

特性一：字段分布式渲染——内核的响应式领域模型

"分布式渲染"不是营销话术，而是有明确的代码架构支撑。核心包packages/core对外导出的模型包括Form、Field、ArrayField、ObjectField、VoidField、Heart、LifeCycle、Graph、Query（见 packages/core/src/models/index.ts），每个字段都是一个独立的模型实例，拥有自己的值、校验、显隐、联动等状态。

官方核心架构文档（packages/core/docs/guide/architecture.zh-CN.md）明确指出：Formily 内核其实是一个 @formily/reactive 领域模型。实际消费领域模型时，主要依赖 @formily/reactive 的响应器（Reactions）机制做依赖追踪——在响应器中消费 Form/Field/ArrayField/ObjectField/VoidField 模型的任意属性，被依赖的属性一旦变化，响应器就会重复执行，从而实现表单层面的响应式（Reactive）编程模型。

packages/reactive包（packages/reactive/src/index.ts）为整个体系提供了基础设施：observable（可观察对象）、autorun/tracker/reaction（依赖追踪与响应）、batch（批量更新）、action（事务）等。它独立于任何 UI 框架，因此同样适用于 Vue（packages/reactive-vue）与 React（packages/reactive-react）。这套"模型层 + 响应器层"的分层设计，从源码层面印证了官方文档对高性能的承诺——字段状态独立可订阅，框架层不再需要为每个字段维护整树依赖。

特性二：JSON Schema 数据驱动——一份 Schema 渲染整张表单

Formily 对 JSON Schema 的整合并非简单映射，而是实现了完整的 Schema 编译与状态映射管线，集中在packages/json-schema包中。

Schema 字段到表单状态的映射

packages/json-schema/src/shared.ts中的SchemaStateMap展示了 Schema 关键字与表单状态的一一对应关系，例如：

• title→title，description→description
• default→initialValue，enum→dataSource
• readOnly/x-read-only→readOnly，writeOnly→editable
• x-editable→editable，x-disabled→disabled
• x-visible→visible，x-hidden→hidden，x-display→display
• x-pattern→pattern，x-validator→validator
• x-decorator→decoratorType，x-component→componentType
• x-decorator-props→decoratorProps，x-component-props→componentProps

其中x-前缀是 Formily 对 JSON Schema 的扩展约定，用于声明组件、装饰器及其属性，是"数据驱动渲染"的关键。同时，SchemaValidatorMap将required、format、pattern、minimum/maximum、minLength/maxLength、const、multipleOf、uniqueItems等标准 JSON Schema 校验关键字直接映射为表单校验规则。

模板表达式编译

Schema 的值支持{{ expression }}模板表达式语法，由 packages/json-schema/src/compiler.ts 中的compile/shallowCompile实现：以当前作用域scope为根，用with($root)执行表达式，从而支持在 Schema 中引用变量、执行联动计算。同时提供registerCompiler允许开发者替换默认编译器，silent可切换静默模式（编译出错时不抛异常）。x-compile-omitted可用于声明某些字段跳过编译，配合traverseSchema（见 shared.ts）实现精确的编译控制。

字段组件与递归渲染

在 React 侧，packages/react包（packages/react/src/index.ts）对外同时导出@formily/json-schema与表单组件。组件层（packages/react/src/components）提供：

• FormProvider：表单上下文提供者；
• SchemaField：JSON Schema 驱动的字段渲染器，是数据驱动方案的核心入口；
• RecursionField：Schema 递归渲染器，处理properties、items等嵌套结构；
• Field/ArrayField/ObjectField/VoidField：JSX 标签化写法对应的字段组件；
• ExpressionScope/RecordScope/RecordsScope：表达式作用域与数据记录作用域，用于联动与遍历场景；
• FormConsumer/ReactiveField：响应式消费模型状态。

Vue 侧（packages/vue/src/index.ts）结构一致，同样导出@formily/json-schema与组件层，并额外通过Vue2Components兼容 Vue 2 组件写法。这意味着同一份 Schema 可以在 React 与 Vue 之间无缝复用，这正是官方"JSX 标签化写法 / JSON Schema 数据驱动方案无缝迁移"的底层支撑。

特性三：副作用逻辑独立管理——联动与校验

联动与校验逻辑是表单的"副作用"来源。Formily 将副作用从组件渲染中剥离，独立成可维护的模块：

• 核心包在 packages/core/src/effects/index.ts 中提供onFormEffects与onFieldEffects两类副作用钩子，配合LifeCycle（生命周期）与Heart（心跳机制，见 packages/core/src/models）实现字段之间的依赖订阅与响应；
• 校验规则引擎由packages/validator包独立承载（formats、rules、template、parser、validator等模块），支持标准格式校验、自定义规则与国际化文案；
• Schema 中的x-reactions/x-linkages（见 shared.ts 中的SchemaNestedMap）则提供了 Schema 层面的声明式联动能力。

这种"渲染与副作用解耦"的架构，让复杂的跨字段联动（如省市联动、根据选项显隐、动态禁用、异步校验）可以集中管理，而不是散落在各个组件的生命周期函数里。

特性四：跨框架与多组件体系支持

从仓库packages目录可以清晰看到 Formily 的跨端矩阵：

例如packages/antd/src下按组件维度组织目录：array-cards、array-collapse、array-table、cascader、date-picker、form-grid、form-item、form-tab、form-step、select-table、upload等，基本覆盖中后台表单的全部高频组件场景。packages/next与packages/element保持同构的组织方式，方便在不同技术栈间迁移。

特性五：复杂布局方案

复杂布局不是"额外插件"，而是内置能力。packages/antd/src下与布局相关的组件包括：

• FormGrid：栅格化布局，支持响应式断点；
• FormLayout：表单整体布局（label 位置、间距、尺寸），配套useResponsiveFormLayout（packages/antd/src/form-layout/useResponsiveFormLayout.ts）实现响应式；
• FormCollapse / FormTab / FormStep：折叠面板、标签页、步骤条三种多区块布局；
• FormDialog / FormDrawer：弹窗/抽屉中的表单；
• ArrayCards / ArrayCollapse / ArrayItems / ArrayTable / ArrayTabs：数组字段的五种展示形态，覆盖从卡片到表格到标签页的嵌套数据编辑场景。

Element 版本同样内置form-grid、form-tab、form-step、array-cards、array-table等布局与数组组件，说明复杂布局能力是跨框架统一提供的。

Form Builder：可视化搭建表单

Formily 生态提供了 Form Builder（基于 Designable 方案构建）可视化表单设计器，通过拖拽组件、配置属性即可快速生成表单，再以 Schema 形式输出，与数据驱动渲染无缝衔接。官方说明将其列为第一特性"可设计"，意味着从"设计器拖拽"到"代码运行"的全链路打通：设计器产出的 Schema 即运行时渲染的 Schema，无需二次转换。

生态与配套资源

围绕 Formily 还衍生出一系列配套产品，包括 Formily 自身生态（@formily/core等 npm 包体系）、可视化设计器 Designable、以及企业级 React 框架 icejs（与 Formily 深度集成）等。仓库内还提供了packages/benchmark（性能基准测试，见 packages/benchmark/src/index.tsx）与packages/reactive-test-cases-for-react18（React 18 场景用例），用于验证与回归响应式渲染的性能表现。

在仓库中运行与测试

本仓库采用 Lerna + Yarn Workspaces 管理（package.json），工作区覆盖packages/*与devtools/*。常用开发命令：

# 启动文档站点（dumi） yarn start # 运行全部测试（Jest + 覆盖率） yarn test # 按包定向测试 yarn test:core # 内核模型 yarn test:schema # JSON Schema 编译与映射 yarn test:react # React 桥接层 yarn test:vue # Vue 桥接层 yarn test:antd # Ant Design 组件库 yarn test:reactive # 响应式基础设施 # 构建所有包（输出 lib/dist/esm） yarn build

以上脚本均定义在根 package.json 的scripts字段中，测试按包隔离（jest packages/<pkg>/），便于针对特定层次进行验证与调试。

总结

Formily 的核心价值可以概括为三条主线：

1. 性能：字段分布式状态管理 + 响应式依赖追踪（packages/core+packages/reactive），从架构层面规避受控表单的整树渲染问题；
2. 数据驱动：深度整合 JSON Schema，配合x-扩展约定与{{ }}模板表达式（packages/json-schema），让后端 Schema 直接驱动表单渲染；
3. 跨端统一：同一套模型与 Schema 语义覆盖 React / Vue 2 / Vue 3，并提供 Ant Design、Fusion Next、Element 三套组件实现。

官方文档将项目定位为跨设备（Cross Device）与高性能（High Performance）的普通表单 / 动态（JSON Schema）表单 / 表单构建器统一方案。理解"分布式字段模型 + 响应器 + Schema 编译"这三位一体的架构，你就能在任意支持框架中快速上手，并把复杂联动与布局需求落地为可维护的代码。

• 前端
• UI组件