Formily API文档：核心方法与配置详解-优快云博客

Formily API文档：核心方法与配置详解

【免费下载链接】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 是一个跨设备高性能的表单解决方案，支持 React/React Native/Vue 2/Vue 3 等多种框架。本文将详细介绍 Formily 的核心 API 方法与配置选项，帮助开发者快速上手并高效使用 Formily 构建复杂表单应用。

核心概念与架构

Formily 的核心架构基于响应式状态管理和组件化设计，主要包含以下模块：

核心模块：packages/core/ - 提供表单状态管理、校验引擎和核心 API
UI 适配层：如 packages/antd/、packages/element/ - 适配不同 UI 组件库
响应式系统：packages/reactive/ - 基于观察者模式的状态管理
文档与示例：docs/ - 包含完整的使用指南和示例代码

表单生命周期

Formily 定义了完整的表单生命周期，通过监听生命周期事件可以实现复杂的业务逻辑。关键生命周期类型定义在 packages/core/src/types.ts 中，主要包括：

ON_FORM_INIT - 表单初始化
ON_FORM_SUBMIT - 表单提交
ON_FIELD_VALUE_CHANGE - 字段值变更
ON_FIELD_VALIDATE_SUCCESS - 字段校验成功

核心 API 方法

createForm - 创建表单实例

createForm 是 Formily 的入口方法，用于创建表单核心领域模型（ViewModel）。

import { createForm } from '@formily/core'

const form = createForm({
  initialValues: { username: 'admin' },
  validateFirst: true,
  effects: (form) => {
    // 表单副作用逻辑
  }
})

参数说明：

initialValues - 初始值
validateFirst - 是否优先显示第一个校验错误
effects - 表单副作用函数，用于处理联动逻辑

详细定义见 packages/core/src/models/form.ts（注：实际文件未找到，基于文档推断）

Field - 字段定义

Field 组件用于声明表单字段，支持配置校验规则、UI 组件等。

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

<Field
  name="username"
  title="用户名"
  required
  initialValue="Hello world"
  decorator={[FormItem]}
  component={[Input]}
  validator={(value) => {
    if (!value) return '用户名不能为空'
    return ''
  }}
/>

核心属性：

name - 字段路径，支持嵌套路径如 user.name
title - 字段标题
required - 是否必填
decorator - 装饰器组件，通常为 FormItem
component - 输入组件，如 Input、Select 等
validator - 自定义校验函数

详细属性定义见 packages/core/src/types.ts

响应式联动

Formily 提供两种联动模式：主动模式和被动模式，满足不同场景需求。

主动模式 - onFieldValueChange

通过监听字段变化主动更新其他字段状态：

import { createForm, onFieldValueChange } from '@formily/core'

const form = createForm({
  effects() {
    onFieldValueChange('select', (field) => {
      form.setFieldState('input', (state) => {
        state.display = field.value // 控制输入框显示状态
      })
    })
  }
})

被动模式 - onFieldReact

声明式依赖跟踪，当依赖字段变化时自动重新计算：

import { createForm, onFieldReact } from '@formily/core'

const form = createForm({
  effects() {
    onFieldReact('input', (field) => {
      // 被动依赖 select 字段
      field.display = field.query('select').value()
    })
  }
})

更多联动示例见 docs/guide/advanced/linkages.zh-CN.md

表单校验

Formily 内置强大的校验引擎，支持多种校验方式，定义在 packages/validator/ 中。

内置规则校验

支持必填、长度、格式等多种内置校验规则：

<Field
  name="email"
  title="邮箱"
  required
  validator={{
    format: 'email', // 邮箱格式校验
    max: 50 // 最大长度 50
  }}
  component={[Input]}
/>

自定义校验规则

通过 registerValidateRules 注册全局校验规则：

import { registerValidateRules } from '@formily/core'

registerValidateRules({
  passwordStrength(value) {
    if (!/^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/.test(value)) {
      return '密码必须包含字母和数字，且至少8位'
    }
    return ''
  }
})

// 使用
<Field
  name="password"
  title="密码"
  validator={{ passwordStrength: true }}
/>

详细校验规则见 docs/guide/advanced/validate.zh-CN.md

高级配置

异步数据源

通过 dataSource 属性和副作用函数实现异步加载选项：

<Field
  name="city"
  title="城市"
  component={[Select]}
  reactions={(field) => {
    field.loading = true
    fetch('/api/cities')
      .then(res => res.json())
      .then(data => {
        field.dataSource = data
        field.loading = false
      })
  }}
/>

详细实现见 docs/guide/advanced/async.zh-CN.md

业务逻辑管理

Formily 提供两种业务逻辑组织方式：

局部逻辑 - 通过 reactions 属性直接在字段上定义：

<Field
  name="fieldA"
  reactions={(field) => {
    // 基于当前字段状态更新其他字段
  }}
/>

全局逻辑 - 在 effects 中集中管理：

createForm({
  effects(form) {
    // 批量处理多个字段逻辑
    onFieldValueChange('*(field1,field2,field3)', (field) => {
      // 统一处理逻辑
    })
  }
})

最佳实践见 docs/guide/advanced/business-logic.zh-CN.md

快速开始示例

以下是一个完整的表单示例，包含输入框、提交按钮和实时响应显示：

import React from 'react'
import { createForm } from '@formily/core'
import { FormProvider, Field, FormConsumer } from '@formily/react'
import { FormLayout, FormItem, Input, Submit } from '@formily/antd'

const form = createForm()

export default () => (
  <FormProvider form={form}>
    <FormLayout layout="vertical">
      <Field
        name="username"
        title="用户名"
        required
        initialValue="Hello Formily"
        decorator={[FormItem]}
        component={[Input]}
      />
      <FormConsumer>
        {() => (
          <div style={{ margin: '16px 0' }}>
            实时值: {form.values.username}
          </div>
        )}
      </FormConsumer>
      <Submit onSubmit={console.log}>提交</Submit>
    </FormLayout>
  </FormProvider>
)

更多示例见 docs/guide/quick-start.zh-CN.md

总结

Formily 提供了一套完整的表单解决方案，核心优势包括：

响应式状态管理 - 基于观察者模式的高效状态更新
灵活的联动机制 - 支持主动和被动两种联动模式
强大的校验引擎 - 内置丰富校验规则，支持自定义扩展
跨框架兼容 - 同时支持 React 和 Vue 生态系统

通过本文介绍的 API 和配置，开发者可以快速构建复杂的表单应用。完整文档和更多示例请参考：

官方文档：docs/
核心源码：packages/core/
快速入门：docs/guide/quick-start.zh-CN.md

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考