API 参考

AutoForm 组件的完整 API 参考文档

Props

Prop	Default	Type
`submitButtonProps`		`ButtonProps` 提交按钮属性
`controls`		`AutoFormControls` 自定义控件映射
`globalMeta`		`ZodAutoFormFieldMeta` 全局字段元数据配置
`addButtonProps`		`ButtonProps` 数组字段添加按钮属性
`id`		`string \| number`
`schema`		`S` Schema to validate the form state. Supports Standard Schema objects, Yup, Joi, and Superstructs.
`state`		`N extends false ? Partial<InferInput<S>> : never` An object representing the current state of the form.
`validate`		`(state: Partial<InferInput<S>>) => FormError<string>[] \| Promise<FormError<string>[]>` Custom validation function to validate the form state.
`validateOn`	`['blur', 'change', 'input']`	`FormInputEvents[]` The list of input events that trigger the form validation.
`name`		`N extends true ? string : never` Path of the form's state within it's parent form. Used for nesting forms. Only available if `nested` is true.
`validateOnInputDelay`	`300`	`number` Delay in milliseconds before validating the form on input events.
`transform`	`true`	`T` If true, applies schema transformations on submit.
`nested`	`false`	`N` If true, this form will attach to its parent Form and validate at the same time.
`acceptcharset`		`string`
`action`		`string`
`autocomplete`		`string`
`enctype`		`string`
`method`		`string`
`novalidate`		`false \| true \| "true" \| "false"`
`target`		`string`
`submitButton`	`true`	`boolean` 是否显示默认提交按钮
`loadingAuto`	`true`	`boolean` When `true`, all form elements will be disabled on `@submit` event. This will cause any focused input elements to lose their focus state.
`disabled`		`boolean` Disable all inputs inside the form.
`ui`		`{ base?: any; }`

Slots

Slot	Type
`header`	`AutoFormSlotProps<AutoFormStateType>`
`footer`	`AutoFormSlotProps<AutoFormStateType>`
`submit`	`AutoFormSlotProps<AutoFormStateType>`
`field-error`	`{ error?: string \| boolean; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-default`	`{ error?: string \| boolean; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-label`	`{ label?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-hint`	`{ hint?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-description`	`{ description?: string; } & AutoFormFieldContext<AutoFormStateType, string>`
`field-help`	`{ help?: string; } & AutoFormFieldContext<AutoFormStateType, string>`

字段级插槽

除了组件级别的插槽外，AutoForm 还支持字段级别的动态插槽，并提供完整的 TypeScript 类型推断和编辑器自动补全。

命名规则：

插槽模式	示例	说明
`field-{slotType}`	`field-label`, `field-default`	通用插槽，适用于所有字段
`field-{slotType}:{fieldKey}`	`field-label:username`, `field-default:email`	特定字段插槽，享受完整类型推导
`field-{position}:{fieldKey}`	`field-before:profile`, `field-content:tasks`	嵌套字段布局插槽

可用的插槽类型（slotType）：

Slot Type	Description
`label`	自定义字段标签
`hint`	自定义提示信息
`description`	自定义字段描述
`help`	自定义帮助文本
`error`	自定义错误信息显示
`default`	自定义字段控件

类型提示优势：当你在模板中使用字段插槽时（如 #field-default:username），编辑器会自动提示插槽参数的类型，包括 state、path、value、setValue 等上下文属性，并根据 Schema 精确推断字段值类型。查看插槽系统文档了解详细用法。

Emits

Event	Type
`submit`	`[event: FormSubmitEvent<FormData<S, T>>]`
`error`	`[event: FormErrorEvent]`

Expose

您可以通过 useTemplateRef 访问该类型化组件实例。

Name	Type
`reset()`	`void` 重置表单到初始状态，包括恢复 props 中的 `state` 和应用所有默认值
`clear()`	`void` 清空表单所有字段数据
`formRef`	`Ref<InstanceType<typeof UForm> \| null>` UForm 组件的模板引用，可访问底层表单的所有方法和属性

通过 formRef 可以访问 UForm 的所有底层功能，包括 submit()、validate()、clear()、getErrors()、setErrors() 等方法，以及 errors、disabled、dirty、dirtyFields、touchedFields、blurredFields 等响应式属性。详见 Nuxt UI Form 文档。

类型定义

AutoFormFieldContext

字段上下文类型，在插槽和响应式函数中可用：

interface AutoFormFieldContext<S = any, P extends string = string> {
  /** 表单数据 */
  readonly state: S
  /** 字段路径 */
  readonly path: P
  /** 字段值（可能为 undefined） */
  readonly value: FieldValueType<S, P>
  /** 设置字段值的回调函数 */
  setValue: {
    (value: FieldValueType<S, P>): void
    <K extends RelativePath<NonUndefinedFieldValue<S, P>>>(
      relativePath: K extends never ? string : K,
      value: any
    ): void
    (relativePath: string, value: any): void
  }
  /** 字段错误列表 */
  readonly errors: unknown[]
  /** 表单提交加载状态 */
  readonly loading: boolean
  /** 字段折叠状态 */
  readonly open?: boolean
  /** 数组元素下标 */
  readonly count?: number
}

AutoFormLayoutConfig

布局配置类型：

interface AutoFormLayoutConfig<C extends IsComponent = IsComponent> {
  /** 布局容器组件 */
  component?: C
  /** 布局组件属性（根据组件类型自动推断，支持响应式） */
  props?: ReactiveValue<ComponentProps<C>, AutoFormFieldContext>
  /** 布局组件 CSS 类名（支持响应式） */
  class?: ReactiveValue<ClassNameValue, AutoFormFieldContext>
  /** 布局组件插槽（根据组件类型自动推断，支持响应式） */
  slots?: ReactiveValue<Partial<ComponentSlots<C>>, AutoFormFieldContext>
  /** 布局内的字段定义（类似 z.object() 的 shape） */
  fields: Record<string, z.ZodType>
  /** 所有字段统一渲染到的插槽名称（支持响应式） */
  fieldSlot?: ReactiveValue<keyof ComponentSlots<C> & string, AutoFormFieldContext>
  /** 字段到插槽的映射关系（支持响应式，优先级高于 fieldSlot） */
  fieldSlots?: ReactiveValue<Partial<Record<string, keyof ComponentSlots<C> & string>>, AutoFormFieldContext>
}

AutoFormNestedCollapsible

嵌套字段折叠配置类型：

interface AutoFormNestedCollapsible {
  /** 是否启用折叠功能（默认：true） */
  enabled?: boolean
  /** 默认打开状态 */
  defaultOpen?: boolean
  /** 控制打开/关闭 */
  open?: boolean
  /** 禁用折叠功能 */
  disabled?: boolean
  /** 隐藏时卸载内容 */
  unmountOnHide?: boolean
  /** 渲染的元素或组件类型（默认：'div'） */
  as?: unknown
  /** CSS 类名 */
  class?: unknown
  /** UI 配置 */
  ui?: {
    root?: ClassNameValue
    content?: ClassNameValue
  }
}

快速开始

了解 AutoForm 的核心设计理念和基本使用方式

配置

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