配置

深入了解 AutoForm 的配置体系，掌握元数据、控件属性和全局配置的使用方法。

核心类型

ReactiveValue

AutoForm 的配置系统基于 ReactiveValue 类型，它支持三种值的形式：

type ReactiveValue<T, CTX = never> =
  [CTX] extends [never]
    ? MaybeRefOrGetter<T>                    // 无上下文：ref 或 getter
    : MaybeRefOrGetter<T> | ((ctx: CTX) => T) // 有上下文：ref、getter 或上下文函数

三种使用形式：

// 1. 静态值
label: '用户名'

// 2. 响应式引用（ref 或 computed）
const labelRef = ref('用户名')

// 3. 上下文函数（可访问表单状态）
label: ({ state }) => state?.userType === 'business' ? '公司名称' : '姓名'

AutoFormFieldContext

上下文函数接收的参数类型：

interface AutoFormFieldContext<S = any, P extends string = string> {
  readonly state: S           // 表单完整状态
  readonly path: P            // 当前字段路径
  readonly value: any         // 当前字段值
  setValue: Function          // 设置字段值
  readonly errors: unknown[]  // 字段错误列表
  readonly loading: boolean   // 表单加载状态
}

使用示例：

afz.string().meta({
  // 根据表单状态动态显示/隐藏
  hidden: ({ state }) => state?.userType !== 'business',

  // 根据字段值动态提示
  hint: ({ value }) => value ? `已输入 ${value.length} 个字符` : '请输入',

  // 根据错误状态动态样式
  class: ({ errors }) => errors.length > 0 ? 'border-red-500' : ''
})

元数据配置

配置方式

使用 .meta() 方法配置字段的 UI 属性：

afz.string()
  .min(3, '用户名至少 3 个字符')
  .meta({
    label: '用户名',
    description: '请输入您的用户名',
    hint: '3-20 个字符',
    required: true
  })

可用属性

属性	类型	说明
`label`	`ReactiveValue<string>`	字段标签
`description`	`ReactiveValue<string>`	字段描述
`hint`	`ReactiveValue<string>`	提示信息
`help`	`ReactiveValue<string>`	帮助文本
`error`	`ReactiveValue<boolean \| string>`	自定义错误信息
`required`	`ReactiveValue<boolean>`	标记字段为必填
`size`	`ReactiveValue<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'>`	字段大小
`as`	`ReactiveValue<any>`	渲染的元素或组件类型
`name`	`ReactiveValue<string>`	字段名称,用于匹配表单错误
`errorPattern`	`ReactiveValue<RegExp>`	正则表达式,用于匹配表单错误名称
`if`	`ReactiveValue<boolean>`	条件渲染
`hidden`	`ReactiveValue<boolean>`	隐藏字段
`eagerValidation`	`ReactiveValue<boolean>`	启用立即验证
`validateOnInputDelay`	`ReactiveValue<number>`	输入验证延迟
`class`	`ReactiveValue<ClassNameValue>`	自定义 CSS 类名
`ui`	`ReactiveValue<Record<string, any>>`	Nuxt UI 样式自定义对象
`collapsible`	`ReactiveValue<AutoFormNestedCollapsible>`	嵌套字段折叠配置
`fieldSlots`	`ReactiveValue<Partial<AutoFormFieldSlots>>`	字段插槽内容

配置优先级

AutoForm 按以下优先级合并配置（从低到高）：

自动默认值 - 系统根据字段类型自动生成
- label - 根据字段名生成（userName → "User Name"）
- required - 根据 .optional() 自动判断
全局配置 (globalMeta) - 统一配置所有字段
字段级配置 (.meta()) - 针对特定字段的配置

优先级示例：如果全局设置 size: 'lg'，字段设置 size: 'md'，最终生效的是 'md'。

控件配置

AutoFormControlsMeta

控件配置支持以下属性：

interface AutoFormControlsMeta<C extends IsComponent = IsComponent> {
  type?: string                                    // 控件类型名称
  component?: C                                    // 直接传入组件
  controlProps?: ReactiveValue<ComponentProps<C>> // 控件属性
  controlSlots?: ReactiveValue<ComponentSlots<C>> // 控件插槽
  error?: string                                   // 验证错误消息
}

使用方式

方式 1：使用 type 指定控件

afz.string({
  type: 'textarea',
  controlProps: {
    rows: 5,
    placeholder: '请输入...'
  }
})

方式 2：直接传入组件

import CustomComponent from './CustomComponent.vue'

afz.number({
  component: CustomComponent,
  controlProps: {
    max: 5,
    size: 'lg'
  }
})

方式 3：响应式控件配置

afz.string({
  // 响应式属性
  controlProps: ({ state }) => ({
    disabled: state?.readonly === true,
    placeholder: state?.userType === 'business' ? '公司邮箱' : '个人邮箱'
  }),

  // 响应式插槽
  controlSlots: ({ value }) => ({
    trailing: () => h(UBadge, { label: `${value?.length || 0}` })
  })
})

简写语法

支持直接传入字符串作为错误消息：

// 完整写法
afz.email({ error: '请输入有效的邮箱地址' })

// 简写形式
afz.email('请输入有效的邮箱地址')

全局配置

globalMeta 属性

通过 AutoForm 组件的 globalMeta prop 统一配置所有字段：

<MAutoForm
  :schema="schema"
  :state="form"
  :global-meta="{
    size: 'lg',
    required: true,
    validateOnInputDelay: 300
  }"
/>

app.config.ts 全局样式

通过 app.config.ts 全局配置表单样式：

app.config.ts

export default defineAppConfig({
  ui: {
    form: {
      base: 'space-y-4 min-w-0 sm:min-w-md'
    },
    collapsible: {
      slots: {
        content: 'space-y-4'
      }
    }
  }
})

控件类型映射

默认映射

afz 方法	默认控件	说明
`afz.string()`	`UInput`	文本输入框
`afz.number()`	`UInputNumber`	数字输入框
`afz.boolean()`	`UCheckbox`	复选框
`afz.enum()`	`USelect`	下拉选择器
`afz.file()`	`UFileUpload`	文件上传
`afz.calendarDate()`	`DatePicker`	日期选择器
`inputDate`	`UInputDate`	日期输入框
`inputTime`	`UInputTime`	时间输入框

可用的 type 值

type 值	控件组件	说明
`textarea`	`UTextarea`	多行文本输入框
`switch`	`USwitch`	开关切换器
`slider`	`USlider`	滑块选择器
`pinInput`	`UPinInput`	PIN 码输入框
`inputTags`	`UInputTags`	标签输入框
`selectMenu`	`USelectMenu`	下拉菜单选择器
`inputMenu`	`UInputMenu`	输入菜单
`checkboxGroup`	`UCheckboxGroup`	复选框组
`radioGroup`	`URadioGroup`	单选框组
`inputDate`	`UInputDate`	日期输入框
`inputTime`	`UInputTime`	时间输入框
`withClear`	`WithClear`	带清除按钮的输入框
`withPasswordToggle`	`WithPasswordToggle`	带密码显示切换的输入框
`withCopy`	`WithCopy`	带复制按钮的输入框
`withCharacterLimit`	`WithCharacterLimit`	带字符计数的输入框
`colorChooser`	`ColorChooser`	颜色选择器
`starRating`	`StarRating`	星级评分器
`slideVerify`	`SlideVerify`	滑动验证控件

API 参考

AutoForm 组件的完整 API 参考文档

String

String 字段类型的使用方法和配置选项