Formily 表单开发快速入门指南

什么是 Formily

Formily 是阿里巴巴开源的一款企业级表单解决方案，它通过分层架构设计，将表单逻辑与 UI 实现分离，提供了强大的表单状态管理、数据联动和校验能力。相比传统表单开发方式，Formily 具有以下优势：

1. 基于 MVVM 模式，实现数据与视图的双向绑定
2. 支持复杂表单场景下的字段联动
3. 提供丰富的校验规则和扩展机制
4. 适配多种 UI 组件库，保持统一的开发体验

环境准备

安装核心依赖

Formily 采用模块化设计，核心功能由多个独立包组成。首先需要安装核心库：

npm install --save @formily/core

这个包提供了表单的状态管理、校验规则和联动逻辑等核心功能。

选择框架适配器

根据项目使用的框架，安装对应的桥接层：

React 项目：

npm install --save @formily/react

Vue 项目：

npm install --save @formily/vue

集成 UI 组件库

Formily 对主流 UI 组件库进行了二次封装，提供了更好的表单体验：

Ant Design 用户：

npm install --save antd moment @formily/antd

Fusion Design 用户：

npm install --save @alifd/next moment @formily/next

基础表单开发

1. 创建表单模型

首先需要创建一个表单模型实例，它将管理整个表单的状态：

import { createForm } from '@formily/core'

const form = createForm()

createForm 方法会返回一个 Form 实例，包含表单的所有状态和方法。

2. 构建表单结构

使用 Formily 提供的组件构建表单 UI：

import { FormProvider, Field } from '@formily/react'
import { FormItem, Input } from '@formily/antd'

function MyForm() {
  return (
    <FormProvider form={form}>
      <Field
        name="username"
        title="用户名"
        required
        decorator={[FormItem]}
        component={[Input]}
      />
    </FormProvider>
  )
}

3. 表单字段详解

Field 组件是表单的核心，主要属性包括：

• name: 字段名，对应表单数据的键
• title: 字段标签
• required: 是否必填
• decorator: 字段装饰器，通常使用 FormItem
• component: 输入控件，如 Input、Select 等

4. 表单布局控制

FormLayout 组件可以统一控制表单布局：

import { FormLayout } from '@formily/antd'

<FormLayout layout="vertical">
  {/* 字段列表 */}
</FormLayout>

支持 vertical(垂直)、horizontal(水平) 等布局方式。

5. 表单提交处理

使用 Submit 组件处理表单提交：

import { FormButtonGroup, Submit } from '@formily/antd'

<FormButtonGroup>
  <Submit onSubmit={handleSubmit}>提交</Submit>
</FormButtonGroup>

Submit 组件会自动处理 loading 状态，当 onSubmit 返回 Promise 时会显示加载状态。

响应式数据绑定

FormConsumer 组件可以实现响应式数据绑定：

import { FormConsumer } from '@formily/react'

<FormConsumer>
  {() => (
    <div>当前值: {form.values.username}</div>
  )}
</FormConsumer>

当表单值变化时，FormConsumer 会自动重新渲染。

进阶功能

表单校验

Formily 提供了丰富的校验能力：

<Field
  name="email"
  title="邮箱"
  required
  validator={(value) => {
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      return '邮箱格式不正确'
    }
  }}
  decorator={[FormItem]}
  component={[Input]}
/>

字段联动

通过 reactions 属性实现字段联动：

<Field
  name="showExtra"
  component={[Checkbox]}
/>

<Field
  name="extraInfo"
  title="额外信息"
  visible={form.values.showExtra}
  decorator={[FormItem]}
  component={[Input]}
/>

总结

Formily 通过分层架构设计，将表单逻辑与 UI 实现解耦，提供了强大的表单开发能力。本文介绍了 Formily 的核心概念和基础用法，包括：

1. 表单模型的创建与管理
2. 表单字段的定义与配置
3. 表单布局与样式控制
4. 表单提交与数据响应
5. 基础校验与联动实现

掌握了这些基础知识后，开发者可以快速构建出功能完善的企业级表单应用。Formily 还提供了更多高级功能，如表单数组、动态表单、自定义组件等，可以满足各种复杂表单场景的需求。