@formily/vue 使用指南：安装、核心架构与三种开发模式的 Vue 表单解决方案

前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载导读formily/vue 是 Formily 生态面向 Vue 2 / Vue 3 的表单解决方案它并不直接管理表单数据和校验逻辑而是作为一层渲染胶水层把 formily/core 创建的 ViewModel表单模型、字段模型与具体的 UI 组件绑定起来。本文以 packages/vue/docs/README.md 为骨架完整讲解 formily/vue 的安装步骤、六大核心特性、FormProvider 分层架构、表单/字段/协议三类上下文以及 Template、JSON Schema、Markup Schema 三种开发模式最后补充事件绑定与插槽使用的常见问题帮助你从零开始用一套协议驱动逻辑快速搭建高性能、可复用的 Vue 表单。安装Vue 3 与 Vue 2 的差异formily/vue 同时支持 Vue 2 与 Vue 3安装时只需注意 Vue 2 环境需要额外安装vue/composition-api作为补充# Vue 3 $ npm install --save formily/core formily/vue# Vue 2 $ npm install --save formily/core formily/vue vue/composition-api从仓库中 packages/vue/package.json 可以看到formily/vue 2.3.7 的运行时依赖包括formily/core、formily/json-schema、formily/reactive、formily/reactive-vue、formily/shared、formily/validator并借助vue-demi版本要求0.13.6实现 Vue 2 / Vue 3 双端适配同时peerDependencies声明支持vue ^2.6.0 || 3.0.0-rc.0vue/composition-api作为可选 peer 依赖Vue 2 场景必装。如果你需要手动切换 Vue 2 / Vue 3 的类型与运行环境包内还提供了formily-vue-switch与formily-vue-fix两个命令行工具见package.json的bin字段。核心定位连接 ViewModel 与 View 的胶水层官方对 formily/vue 的定位非常清晰它将 ViewModel由 formily/core 管理与组件实现一个状态绑定关系不负责管理表单数据与表单校验仅仅是渲染胶水层。但这层胶水并不脏它把大量跨端、跨框架的脏逻辑优雅解耦让整体代码变得可维护见 guide/README.md。换句话说数据模型、字段状态、校验规则全部由 formily/core 负责formily/vue 只负责翻译——把字段模型的状态同步到组件上把组件的事件同步回字段模型。组件侧的唯一约定是组件只需要支持value属性与onChange事件即value/change双向绑定约定即可自动接入 formily/vue 实现数据层双向绑定。六大核心特性超高性能依赖追踪、按需渲染借助 formily/core 的响应式模型底层是 formily/reactive 的依赖追踪机制formily/vue 无需手动做任何优化即可获得高性能优势精确更新、按需渲染让开发者只需关注业务逻辑无需考虑性能问题。开箱即用组件状态自动绑定formily/vue 提供了一系列 Vue 组件如Field/ArrayField/ObjectField/VoidField。使用时只需给Field组件传入component属性支持value/change双向绑定约定的组件即可即可快速接入接入成本极低。协议驱动标准 JSON-Schemaformily/vue 提供了SchemaField这样的协议驱动组件基于标准 JSON-Schema 进行驱动渲染让表单开发可以更加动态化、可配置化甚至可以做到一份协议多端渲染表单。场景复用抽象场景组件借助协议驱动能力可以将一段携带业务逻辑的协议片段抽象成场景组件帮助用户在某些场景下高效开发例如FormTab、FormStep这类场景组件。智能提示拥抱 TypeScriptFormily 是完全的 TypeScript 项目在 VSCode 或 WebStorm 等 IDE 中开发可以获得最大化的智能提示体验。状态可观测对接 Formily DevTools仓库的 devtools/chrome-extension 目录提供了 Formily DevTools 浏览器扩展的完整源码。安装扩展后可以实时观测模型状态变化方便排查问题。核心架构FormProvider 统一下发上下文formily/vue 的架构相比 formily/core 并不复杂架构总览见 architecture.md纯源码开发用户直接使用Field/ArrayField/ObjectField/VoidField组件动态开发用户基于 JSON-Schema 使用SchemaField组件其内部依赖Field/ArrayField/ObjectField/VoidField组件两类用户都需要用FormProvider组件统一下发表单上下文。对应到仓库源码packages/vue/src 下components/、hooks/、shared/三个目录分别存放组件、组合式 API 与共享工具具体组件与 Hook 的 API 文档可在 packages/vue/docs/api 下查看。六个核心概念formily/vue 本身架构不复杂它只是提供了一系列组件和 Hooks 给用户使用但理解以下六个概念详见 concept.md对用好它至关重要表单上下文、字段上下文、协议上下文、模型绑定、协议驱动、三种开发模式。表单上下文FormContextFormProvider是表单的统一上下文地位非常重要。它将 formily/core 创建出来的Form实例下发到所有子组件中无论是内置组件还是用户扩展的组件都能通过 useForm 读取到Form实例。关于Form模型本身的 API可参考 packages/core/docs/guide/form.md 与packages/core/docs/api/models/目录。字段上下文FieldContextField/ArrayField/ObjectField/VoidField都会给子树下发一个字段上下文可以在自定义组件中通过 useField 读取当前字段模型非常便于做模型映射。协议上下文FieldSchemaContextRecursionField 会给子树下发 Schema 上下文可在自定义组件中通过 useFieldSchema 读取当前字段的 Schema 描述。注意该 Hook 只能用在SchemaField和RecursionField子树中使用。模型绑定Model Binding模型绑定是 MVVM 思想在 Formily 中的落地formily/core是 ViewModelComponent 和 Decorator 是 Viewformily/vue 是把二者绑定的胶水层。实现模型绑定的手段主要有 useField也可以使用 connect 和 mapProps。关于 MVVM 的深入讲解见 packages/core/docs/guide/mvvm.md。协议驱动Schema Driven协议驱动渲染是 formily/vue 学习成本最高的部分但学会后收益很高需要理解 4 个核心概念Schema、递归渲染、协议绑定、三种开发模式。SchemaFormily 的协议驱动基于标准 JSON-Schema同时在标准之上扩展了x-*属性来表达 UI使协议具备完整描述一个复杂表单的能力。完整协议定义见 Schema API 文档。递归渲染Recursion Render递归渲染指组件 A 在某些条件下继续用组件 A 来渲染内容。formily/vue 递归渲染的入口是SchemaField其内部实际使用RecursionField渲染。由于 JSON-Schema 本身就是递归型结构RecursionField渲染时会从顶层 Schema 节点解析非 object / array 类型直接渲染具体组件object 类型遍历properties继续用RecursionField渲染子级 Schema 节点array 类型自增列表需要用户在自定义组件内使用RecursionField进行递归渲染因为自增列表 UI 个性化定制程度高官方把递归渲染权交给用户让协议驱动渲染更加灵活。参考以下递归结构{ type: object, properties: { username: { type: string, x-component: Input }, phone: { type: string, x-component: Input, x-validator: phone }, email: { type: string, x-component: Input, x-validator: email }, contacts: { type: array, x-component: ArrayTable, items: { type: object, properties: { username: { type: string, x-component: Input }, phone: { type: string, x-component: Input, x-validator: phone }, email: { type: string, x-component: Input, x-validator: email } } } } } }SchemaField与RecursionField的差别主要有两点SchemaField支持 Markup 语法会提前解析 Markup 语法生成 JSON Schema 移交给RecursionField渲染因此RecursionField只能基于 JSON Schema 渲染SchemaField渲染的是整体 Schema 协议RecursionField渲染的是局部 Schema 协议。RecursionField可以独立于SchemaField单独使用常用于自定义组件中实现递归渲染能力。它的核心属性见 recursion-field.md包括schemaSchema 对象name/basePath路径名称与基础路径onlyRenderProperties是否只渲染 propertiesonlyRenderSelf是否只渲染自身、不渲染 propertiesmapPropertiesSchema properties 映射器用于改写 schemafilterPropertiesSchema properties 过滤器被过滤的节点不会渲染。自增列表场景的完整示例见 recursion-field-with-component它通过 useField 和 useFieldSchema 获取当前字段上下文中的字段实例与字段 schema。协议绑定Schema Binding协议绑定是将 Schema 协议转换成模型绑定的过程。JSON-Schema 协议是 JSON 字符串、可离线存储而模型绑定是内存间的绑定关系、属于 Runtime 层。例如x-component在 Schema 中是组件的字符串标识但在模型中component需要的是组件引用因此 JSON 字符串与 Runtime 层之间需要转换。总结下来formily/vue 中主要有2 层绑定关系Schema 绑定模型模型绑定组件实现绑定的胶水层就是 formily/vue。需要注意Schema 绑定字段模型之后字段模型感知不到 Schema例如要修改enum实际修改的是字段模型中的dataSource属性。想要更新字段模型可参考Field模型文档packages/core/docs/guide/field.md想要理解 Schema 与字段模型的映射关系可参考 Schema API 文档。三种开发模式formily/vue 面向不同用户提供三种开发模式Template 开发模式、JSON Schema 开发模式、Markup Schema 开发模式。Template 开发模式该模式主要使用Field/ArrayField/ObjectField/VoidField组件以源码方式声明字段。component属性接受[组件, 组件props]形式的元组template FormProvider :formform Field nameinput :component[Input, { placeholder: 请输入 }] / /FormProvider /template script import { Input } from ant-design-vue import { createForm } from formily/core import { FormProvider, Field } from formily/vue import ant-design-vue/dist/antd.css export default { components: { FormProvider, Field }, data() { return { Input, form: createForm(), } }, } /scriptJSON Schema 开发模式该模式通过createSchemaField({ components, scope })工厂函数创建 SchemaField 组件再给SchemaField的schema属性传入 JSON Schema 即可template FormProvider :formform SchemaField :schemaschema / /FormProvider /template script import { Input } from ant-design-vue import { createForm } from formily/core import { FormProvider, createSchemaField } from formily/vue import ant-design-vue/dist/antd.css const { SchemaField } createSchemaField({ components: { Input, }, }) export default { components: { FormProvider, SchemaField }, data() { return { form: createForm(), schema: { type: object, properties: { input: { type: string, x-component: Input, x-component-props: { placeholder: 请输入, }, }, }, }, } }, } /script其中createSchemaField的工厂函数参数与SchemaField属性见 schema-field.md为interface ISchemaFieldFactoryProps { components?: { [key: string]: Vue.Component } // 组件列表 scope?: any // 全局作用域用于实现协议表达式变量注入 } interface ISchemaFieldProps extends IFieldFactoryProps { schema?: ISchema // 字段 schema scope?: any // 协议表达式作用域 name?: string // 字段名称 }Markup Schema 开发模式该模式是对源码开发比较友好的 Schema 开发模式同样使用 SchemaField 相关组件。其特点主要依赖SchemaStringField/SchemaArrayField/SchemaObjectField等描述标签来表达 Schema每个描述标签都代表一个 Schema 节点与 JSON-Schema 等价SchemaField子节点不能随意插 UI 元素因为 SchemaField 只会解析子节点的所有 Schema 描述标签并转换成 JSON Schema最终交给RecursionField渲染想插入 UI 元素可以在SchemaVoidField上通过x-content属性插入。template FormProvider :formform SchemaField SchemaStringField x-componentInput :x-component-props{ placeholder: 请输入 } / div我不会被渲染/div SchemaVoidField x-content我会被渲染 / SchemaVoidField :x-contentComp / /SchemaField /FormProvider /template script import { Input } from ant-design-vue import { createForm } from formily/core import { FormProvider, createSchemaField } from formily/vue import ant-design-vue/dist/antd.css const SchemaComponents createSchemaField({ components: { Input, }, }) const Comp { render(h) { return h(div, [我也会被渲染]) }, } export default { components: { FormProvider, ...SchemaComponents }, data() { return { form: createForm(), Comp, } }, } /scriptcreateSchemaField工厂函数会返回一组 Schema 描述组件包括SchemaField、SchemaMarkupField、SchemaStringField、SchemaObjectField、SchemaArrayField、SchemaBooleanField、SchemaDateField、SchemaDateTimeField、SchemaVoidField、SchemaNumberField。三种模式的完整演示注册表单仓库中 demos/index.vue 是快速开始章节指向的完整示例它演示了 Template 模式下的一个注册表单包含用户名、密码、确认密码三个Field通过reactions实现两次密码一致性校验并用FormConsumer实时预览表单值同时用 connect mapProps 将Form.Item装饰器与字段校验状态、错误信息field.selfErrors、描述field.description绑定template FormProvider :formform Field namename titleName required :decorator[FormItem] :component[Input, { placeholder: Please Input }] / Field namepassword titlePassword required :decorator[FormItem] :component[Input, { type: password, placeholder: Please Input }] :reactionscreatePasswordEqualValidate(confirm_password) / Field nameconfirm_password titleConfirm Password required :decorator[FormItem] :component[Input, { type: password, placeholder: Please Input }] :reactionscreatePasswordEqualValidate(password) / FormConsumer template #default{ form } div stylewhite-space: pre {{ JSON.stringify(form.values, null, 2) }} /div /template /FormConsumer /FormProvider /template常见问题事件绑定与插槽使用如何添加事件在x-component-props中可以用来标识事件同时也支持onXxx方式。两者区别在于使用标识的内容不会再作为 prop 传入组件而onXxx会。这是为了兼容某些具有onXxxprop 的组件如 ElementUI 的 upload 组件。事件名冲突时的优先级更高——例如同时设置了change和onChange只有change会生效。完整示例见 demos/questions/events.vue。如何使用默认插槽使用x-content可以在组件的 default 插槽中插入内容可以传入文本或组件。示例见 demos/questions/default-slot.vue。如何使用具名插槽x-content中以键名来表示插槽名。注意键名不可包含template、render、setup三个关键字否则整个x-content会被当作 Vue 组件进行渲染。示例见 demos/questions/named-slot.vue。如何使用作用域插槽x-content使用函数式组件时渲染函数增加第二个参数通过其props成员访问作用域插槽传入的属性支持observer()和connect()接入组件。示例见 demos/questions/scoped-slot.vue。更多细节可查阅 questions/README.md。延伸阅读组件 APIField、SchemaField、RecursionField、ArrayField、ObjectField、VoidField、FormProvider、FormConsumerHooks APIuseForm、useField、useFieldSchema、useParentForm、useFormEffects共享工具connect、mapProps、mapReadPretty、observer、Schema核心原理核心概念、核心架构、formily/core MVVM 指南formily/vue 的价值在于一次建模、多端复用无论你选择 Template 的源码直写、JSON Schema 的动态下发还是 Markup Schema 的组件化描述底层共享同一套 formily/core 响应式模型与校验体系。理解了三类上下文与两层绑定关系你就能在业务中灵活组合组件、Hooks 与协议写出高性能且易于维护的表单应用。赞分享前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载相关推荐formily/vue 全面解析响应式表单胶水层的架构设计、协议驱动与三种开发模式formily/vue 全面解析响应式表单胶水层的架构设计、协议驱动与三种开发模式 本指南以 formily/vue 官方引导文档为主体系统讲解它如何作前端UI组件Formily React 指南formily/react 的架构、模型绑定与三种开发模式Formily React 指南formily/react 的架构、模型绑定与三种开发模式 导读 formily/react 是 Formily 表单方案前端UI组件Formily React 核心概念全解析表单上下文、模型绑定与三种开发模式Formily React 核心概念全解析表单上下文、模型绑定与三种开发模式 formily/react 是 Formily 体系中连接 formily/前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考