Formily动态表单引擎：JSON Schema极速开发

【免费下载链接】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框架的JSON Schema动态表单技术，通过声明式配置快速构建高性能表单应用，彻底解决传统表单开发中的效率瓶颈。

什么是JSON Schema驱动开发

JSON Schema是一种用于描述JSON数据结构的规范，Formily通过深度整合JSON Schema协议，实现了表单的"一次定义，多端运行"。与传统的手动编写表单组件相比，JSON Schema驱动开发具有以下优势：

• 跨端一致性：同一套Schema配置可在React、Vue等不同框架中运行
• 后端可控：服务端可直接返回Schema配置动态渲染表单
• 类型安全：通过TypeScript类型系统确保数据结构正确性
• 扩展性强：支持自定义组件、校验规则和联动逻辑

Formily的JSON Schema核心实现位于packages/json-schema/src/index.ts，通过导出schema和types模块提供完整的类型定义和解析能力。

快速上手：5分钟创建第一个动态表单

环境准备

首先需要安装Formily核心库和UI适配层，以React+Ant Design为例：

npm install --save @formily/core @formily/react antd @formily/antd

基础示例

以下是一个简单的用户信息表单实现，完整代码可参考docs/guide/quick-start.zh-CN.md：

import React from 'react'
import { createForm } from '@formily/core'
import { FormProvider, createSchemaField } from '@formily/react'
import { Form, FormItem, Input, NumberPicker, Submit } from '@formily/antd'

// 创建表单实例
const form = createForm()

// 创建SchemaField组件
const SchemaField = createSchemaField({
  components: {
    FormItem,
    Input,
    NumberPicker
  }
})

export default () => (
  <FormProvider form={form}>
    <Form layout="vertical">
      <SchemaField>
        {/* 字符串类型字段 */}
        <SchemaField.String
          name="username"
          title="用户名"
          required
          x-decorator="FormItem"
          x-component="Input"
          x-component-props={{ placeholder: "请输入用户名" }}
        />
        {/* 数字类型字段 */}
        <SchemaField.Number
          name="age"
          title="年龄"
          x-decorator="FormItem"
          x-component="NumberPicker"
          x-component-props={{ min: 0, max: 150 }}
        />
      </SchemaField>
      <Submit onSubmit={values => console.log(values)}>提交</Submit>
    </Form>
  </FormProvider>
)

在这个示例中，我们通过SchemaField.String和SchemaField.Number定义了两个表单字段，使用x-decorator和x-component属性分别指定了字段的装饰器组件和输入组件。

核心功能：让表单开发效率倍增

声明式校验规则

Formily支持通过JSON Schema原生关键字定义校验规则，如required、minLength、maxLength等，同时也支持自定义校验函数：

<SchemaField.String
  name="email"
  title="邮箱"
  required
  format="email" // 内置邮箱格式校验
  x-decorator="FormItem"
  x-component="Input"
  // 自定义校验规则
  validate={[
    {
      test: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
      message: "请输入有效的邮箱地址"
    }
  ]}
/>

完整的校验规则文档可参考官方指南docs/guide/advanced/validate.zh-CN.md。

智能数据联动

Formily提供了强大的表单字段联动能力，支持主动模式和被动模式两种联动方式。以下是一个基于x-reactions属性实现的字段显隐控制：

<SchemaField.String
  name="showExtraInfo"
  title="是否显示额外信息"
  enum={[
    { label: "是", value: true },
    { label: "否", value: false }
  ]}
  x-component="Select"
  x-decorator="FormItem"
  x-reactions={{
    target: "extraInfo",
    fulfill: {
      state: {
        visible: "{{$self.value === true}}"
      }
    }
  }}
/>

<SchemaField.String
  name="extraInfo"
  title="额外信息"
  x-decorator="FormItem"
  x-component="Input.TextArea"
  x-visible={false} // 默认隐藏
/>

更复杂的联动场景，如一对多联动、依赖联动等，可以参考docs/guide/advanced/linkages.zh-CN.md。

动态数组操作

对于需要动态增删的列表型数据，Formily提供了ArrayCards、ArrayItems等组件，结合JSON Schema的type: 'array'和items属性即可实现：

<SchemaField.Array
  name="hobbies"
  title="爱好"
  x-decorator="FormItem"
  x-component="ArrayCards"
  x-component-props={{
    addText: "添加爱好",
    cardProps: { title: "爱好" }
  }}
>
  <SchemaField.String
    x-component="Input"
    placeholder="请输入爱好"
  />
</SchemaField.Array>

实战技巧：从业务场景出发

分步表单实现

对于复杂表单，我们通常会将其拆分为多个步骤，Formily的FormStep组件结合JSON Schema可以轻松实现这一需求：

import { FormStep } from '@formily/antd'

<SchemaField.Object
  name="stepForm"
  x-component="FormStep"
  x-component-props={{
    steps: [
      { title: "基本信息" },
      { title: "详细信息" },
      { title: "确认提交" }
    ]
  }}
>
  {/* 第一步：基本信息 */}
  <SchemaField.Object
    name="basic"
    x-component="FormStep.Content"
    x-component-props={{ step: 0 }}
  >
    <SchemaField.String name="name" title="姓名" required x-decorator="FormItem" x-component="Input" />
  </SchemaField.Object>
  
  {/* 第二步：详细信息 */}
  <SchemaField.Object
    name="detail"
    x-component="FormStep.Content"
    x-component-props={{ step: 1 }}
  >
    <SchemaField.String name="address" title="地址" required x-decorator="FormItem" x-component="Input" />
  </SchemaField.Object>
  
  {/* 第三步：确认提交 */}
  <SchemaField.Object
    name="confirm"
    x-component="FormStep.Content"
    x-component-props={{ step: 2 }}
  >
    {/* 确认信息展示 */}
  </SchemaField.Object>
</SchemaField.Object>

完整的分步表单示例可参考docs/guide/scenes/step-form.zh-CN.md。

表格型表单

在后台系统中，我们经常需要编辑表格数据，Formily的ArrayTable组件可以将数组类型字段渲染为表格，并支持行内编辑：

<SchemaField.Array
  name="products"
  title="产品列表"
  x-decorator="FormItem"
  x-component="ArrayTable"
  x-component-props={{
    bordered: true,
    columns: [
      { title: "产品名称", dataIndex: "name", width: 200 },
      { title: "单价", dataIndex: "price", width: 100 },
      { title: "数量", dataIndex: "quantity", width: 100 },
    ]
  }}
>
  <SchemaField.Object>
    <SchemaField.String name="name" title="产品名称" required />
    <SchemaField.Number name="price" title="单价" required minimum={0} />
    <SchemaField.Number name="quantity" title="数量" required minimum={1} default={1} />
  </SchemaField.Object>
</SchemaField.Array>

性能优化：让复杂表单如丝般顺滑

Formily采用分布式状态管理和精确依赖收集机制，确保即使是包含成百上千个字段的复杂表单也能保持高性能。核心优化点包括：

1. 按需渲染：只有当字段状态变化时，才会重新渲染对应的UI组件
2. 批量更新：通过batch API将多次状态更新合并为一次渲染
3. 虚拟滚动：对于超长列表，可使用VirtualList组件实现虚拟滚动

import { batch } from '@formily/core'

// 批量更新多个字段状态
batch(() => {
  form.setFieldState('field1', state => {
    state.value = 'value1'
  })
  form.setFieldState('field2', state => {
    state.value = 'value2'
  })
})

高级应用：自定义组件与扩展

注册自定义组件

如果内置组件无法满足需求，Formily允许你注册自定义组件，并在JSON Schema中通过x-component引用：

import { registerFormComponents } from '@formily/react'
import { MyCustomComponent } from './MyCustomComponent'

// 注册自定义组件
registerFormComponents({
  MyCustomComponent
})

// 在Schema中使用
<SchemaField.String
  name="custom"
  title="自定义组件"
  x-decorator="FormItem"
  x-component="MyCustomComponent"
  x-component-props={{ /* 组件属性 */ }}
/>

自定义JSON Schema关键字

Formily支持扩展JSON Schema关键字，以满足特定业务需求：

import { extendSchemaField } from '@formily/core'

// 扩展一个"phone"关键字，用于手机号格式化
extendSchemaField({
  type: 'string',
  keyword: 'phone',
  transform: (schema) => {
    if (schema.phone) {
      schema.format = 'tel'
      schema.validate = schema.validate || []
      schema.validate.push({
        test: /^1[3-9]\d{9}$/,
        message: '请输入有效的手机号'
      })
    }
    return schema
  }
})

// 使用自定义关键字
<SchemaField.String
  name="phone"
  title="手机号"
  phone // 自定义关键字
  x-decorator="FormItem"
  x-component="Input"
/>

学习资源：快速提升Formily技能

• 官方文档：docs/guide/index.zh-CN.md
• API参考：packages/core/docs/api/index.zh-CN.md
• 示例代码：docs/guide/scenes/
• 视频教程：可访问官方网站查看（此处省略外部链接）

总结：为什么选择JSON Schema驱动开发

通过本文的介绍，我们了解了Formily中JSON Schema动态表单的核心功能和使用方法。采用JSON Schema驱动开发可以带来以下收益：

1. 提高开发效率：声明式配置减少了大量重复代码
2. 增强可维护性：表单结构和逻辑集中在Schema中，便于维护
3. 促进前后端协作：后端可直接提供Schema配置，减少沟通成本
4. 提升用户体验：内置的校验和联动功能让表单交互更友好

如果你正在寻找一种能够显著提升表单开发效率的方案，不妨尝试Formily的JSON Schema动态表单技术，相信它会给你带来惊喜！

最后，欢迎通过README.zh-cn.md了解更多关于Formily的信息，也欢迎参与项目贡献，一起完善这个优秀的表单解决方案。

【免费下载链接】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