快速开始
了解 AutoForm 的核心设计理念和基本使用方式。
什么是 AutoForm
AutoForm 是一个基于 Zod Schema 的自动表单生成系统。通过声明式的 Schema 定义,自动生成完整的表单界面,包括输入控件、验证规则和布局结构。
核心优势
- Schema 即表单 - 一份 Schema 同时定义数据结构、验证规则和 UI 配置
- 类型安全 - 完整的 TypeScript 类型推断,从 Schema 到表单数据
- 零模板代码 - 无需手写
v-for或重复的表单字段模板
基础示例
创建一个简单的用户注册表单:
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod'
const { afz } = useAutoForm()
const toast = useToast()
const schema = afz.object({
username: afz.string('请填写用户名').min(3).max(20).regex(/^\w+$/),
email: afz.email({
controlProps: {
leadingIcon: 'i-lucide-mail',
placeholder: '请输入您的邮箱'
},
error: '请输入有效的邮箱地址'
}).meta({ hint: '邮箱' }),
password: afz.string({ type: 'withPasswordToggle' })
.min(8)
.regex(/[A-Z]/)
.regex(/[a-z]/)
.regex(/\d/),
confirmPassword: afz.string({ type: 'withPasswordToggle' }),
acceptTerms: afz.boolean({
controlProps: { label: '我同意服务条款和隐私政策', required: true }
})
}).refine(
data => data.password === data.confirmPassword,
{ message: '两次密码不一致', path: ['confirmPassword'] }
).refine(
data => data.acceptTerms === true,
{ message: '必须同意条款', path: ['acceptTerms'] }
)
type Schema = z.output<typeof schema>
const form = ref<Partial<Schema>>({})
async function onSubmit(event: FormSubmitEvent<Schema>) {
toast.add({
title: 'Success',
color: 'success',
description: JSON.stringify(event.data, null, 2)
})
}
</script>
<template>
<MAutoForm :schema="schema" :state="form" @submit="onSubmit" />
</template>
API
Props
| Prop | Default | Type |
|---|---|---|
schema | SZod 对象 schema,定义表单字段 | |
state | N extends false ? Partial<InferInput<S>> : never表单的状态对象。 | |
submitButtonProps | ButtonProps提交按钮属性 | |
addButtonProps | ButtonProps数组字段添加按钮属性 | |
controls | AutoFormControls自定义控件映射 | |
globalMeta | ZodAutoFormFieldMeta全局字段元数据配置 | |
validateOn | [] | FormInputEvents[]表单验证时机,详见 UForm 的 validateOn 属性 |
id | string | number | |
validate | (state: Partial<InferInput<S>>) => FormError<string>[] | Promise<FormError<string>[]>Custom validation function to validate the form state. | |
name | N extends true ? string : neverPath of the form's state within it's parent form.
Used for nesting forms. Only available if | |
validateOnInputDelay | `300` | numberDelay in milliseconds before validating the form on input events. |
transform | `true` | TIf true, applies schema transformations on submit. |
nested | `false` | NIf true, this form will attach to its parent Form and validate at the same time. |
onSubmit | (): void | Promise<void> | (event: FormSubmitEvent<FormData<S, T>>): void | Promise<void> | |
acceptcharset | string | |
action | string | |
autocomplete | string | |
enctype | string | |
method | string | |
novalidate | false | true | "true" | "false" | |
target | string | |
submit | true | boolean是否显示默认提交按钮 |
loadingAuto | true | boolean是否启用自动 loading 功能。 |
disabled | booleanDisable all inputs inside the form. | |
ui | { root?: ClassNameValue; base?: ClassNameValue; collapsible?: ClassNameValue; header?: ClassNameValue; footer?: ClassNameValue; actions?: ClassNameValue; } |
Slots
| Slot | Type |
|---|---|
header | AutoFormSlotProps<AutoFormStateType> |
footer | AutoFormSlotProps<AutoFormStateType> |
submit | AutoFormSlotProps<AutoFormStateType> |
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> |
field-error | { error?: string | boolean; } & AutoFormFieldContext<AutoFormStateType, string> |
field-default | { error?: string | boolean; } & 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 | 嵌套字段布局插槽 |
Emits
| Event | Type |
|---|---|
error | [FormErrorEvent] |
Expose
您可以通过 useTemplateRef 访问该类型化组件实例。
| Name | Type |
|---|---|
reset() | void 重置表单到初始状态,包括恢复 props 中的 |
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 文档。Changelog
No recent changes