3分钟上手Formily：组件API全解析与实战示例

你还在为复杂表单开发烦恼吗？从字段联动到动态校验，从跨框架兼容到性能优化，Formily一站式解决前端表单开发痛点。本文将带你极速掌握Formily核心组件API，结合10+实战场景示例，让你从此告别重复编码！

安装与环境配置

Formily支持React/Vue双框架，通过npm/yarn即可快速安装核心依赖：

# React项目
npm install @formily/core @formily/react

# Vue项目
npm install @formily/core @formily/vue

完整安装指南可参考快速入门文档，框架适配细节在packages/react/和packages/vue/目录中提供了源码实现。

核心组件架构

Formily采用分层设计理念，核心组件分为：

• 基础表单层：Form组件负责数据管理与状态控制
• 字段控件层：Input组件、Select组件等基础UI组件
• 布局容器层：FormGrid组件、FormTab组件等布局控件
• 高级功能层：ArrayTable组件处理动态列表，FormStep组件实现分步表单

组件关系如图所示：

Formily组件架构

常用API速查

Form组件核心属性

属性名	类型	描述	默认值
initialValues	object	初始表单值	{}
onFinish	(values) => void	提交成功回调	-
layout	'horizontal'|'vertical'	布局方向	'horizontal'

完整API定义见Form组件源码

字段控件通用属性

所有表单控件均支持以下通用属性：

{
  name: string;          // 字段路径
  title: string;         // 标签文本
  required?: boolean;    // 是否必填
  validate?: Rule[];     // 校验规则
  visible?: boolean;     // 是否可见
  disabled?: boolean;    // 是否禁用
}

校验规则定义可参考validator模块

实战场景示例

1. 登录注册表单

使用Formily快速实现带实时校验的登录表单：

import { Form, Input, Password, Submit } from '@formily/element'

export default () => (
  <Form onFinish={values => console.log(values)}>
    <Input name="username" title="用户名" required />
    <Password name="password" title="密码" required />
    <Submit>登录</Submit>
  </Form>
)

完整示例代码：login-register.md

2. 动态列表表单

通过ArrayTable组件实现可增删的动态列表：

动态列表表单

import { Form, ArrayTable, Input, NumberPicker } from '@formily/element'

export default () => (
  <Form>
    <ArrayTable name="products" title="产品列表">
      <Input name=".name" title="产品名称" />
      <NumberPicker name=".price" title="产品价格" />
    </ArrayTable>
  </Form>
)

组件实现原理：array-table/

3. 分步表单

使用FormStep组件实现多步骤引导式表单：

分步表单示例

高级功能指南

跨框架兼容

Formily通过适配器模式实现React/Vue双框架支持：

• React适配器：packages/react/src/form.tsx
• Vue适配器：packages/vue/src/form.vue

性能优化

对于超大型表单（100+字段），可启用虚拟滚动优化：

import { Form, VirtualList } from '@formily/element'

<Form>
  <VirtualList name="largeData" height={500}>
    {/* 大量字段 */}
  </VirtualList>
</Form>

优化策略详情：性能优化指南

开发工具支持

Formily提供Chrome开发者工具扩展，可实时调试表单状态：

Formily DevTools

安装方法：chrome-extension/

学习资源汇总

• 官方文档：docs/
• 组件源码：packages/element/src/
• 示例项目：docs/scenes/
• 视频教程：README.md

掌握这些资源，你将快速从表单开发新手成长为专家！现在就打开你的IDE，尝试用Formily重构你的第一个表单吧！