快速开始
什么是 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/v4'
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>
<UCard>
<MAutoForm :schema="schema" :state="form" @submit="onSubmit" />
</UCard>
</template>
代码解析
<script setup lang="ts">
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod/v4'
const { afz } = useAutoForm()
const toast = useToast()
// 1. 定义 Schema
const schema = afz.object({
username: afz.string().min(3).meta({ label: '用户名' }),
email: afz.email().meta({ label: '邮箱' }),
age: afz.number().min(18).meta({ label: '年龄' })
})
// 2. 类型推导
type Schema = z.output<typeof schema>
// 3. 表单状态
const form = ref<Partial<Schema>>({})
// 4. 提交处理
async function onSubmit(event: FormSubmitEvent<Schema>) {
toast.add({
title: '提交成功',
description: JSON.stringify(event.data, null, 2)
})
}
</script>
<template>
<!-- 5. 渲染表单 -->
<MAutoForm :schema="schema" :state="form" @submit="onSubmit" />
</template>
核心概念
Schema 定义
useAutoForm 返回核心对象 afz（AutoForm Zod），它是 Zod 的增强版封装。
const { afz } = useAutoForm()
const schema = afz.object({
username: afz.string().min(3),
email: afz.email(),
age: afz.number().min(18)
})
afz 代理了 Zod 的方法，自动拦截并注入 AutoForm 元数据。这确保了：- 元数据传递 - UI 配置（如
label、placeholder）能正确传递给表单组件 - 链式调用保留 - 调用
.optional()、.default()等方法时元数据不会丢失 - 控件映射 - 自动将 Zod 类型映射到对应的 UI 控件
// 使用 afz，元数据完整传递
const schema = afz.object({
username: afz.string().meta({ label: '用户名' }).optional()
})
// 原生 Zod 可能丢失 UI 配置
import { z } from 'zod/v4'
const schema = z.object({
username: z.string() // 无法配置 label、placeholder 等
})
控件映射
AutoForm 根据 Zod 类型自动选择对应的 UI 控件：
| afz 方法 | 默认控件 | 说明 |
|---|---|---|
afz.string() | UInput | 文本输入框 |
afz.number() | UInputNumber | 数字输入框 |
afz.boolean() | UCheckbox | 复选框 |
afz.enum() | USelect | 下拉选择器 |
afz.file() | UFileUpload | 文件上传 |
afz.calendarDate() | DatePicker | 日期选择器 |
元数据配置
使用 .meta() 方法配置字段的 UI 属性：
const schema = afz.object({
username: afz.string()
.min(3, '用户名至少 3 个字符')
.meta({
label: '用户名',
description: '请输入您的用户名',
hint: '3-20 个字符',
placeholder: '请输入',
required: true
})
})
Changelog
50467 — chore: 更新依赖和清理临时文件
7dec6 — feat: AutoForm 支持自定义提交按钮属性
b29b9 — refactor: 提取独立的 Zod AutoForm 元数据类型定义
f9682 — refactor: 迁移核心工具到 @movk/core 包，更新导入路径
031e1 — ♻️ refactor: 增强 AutoForm 组件功能并修复图标名称
2ed2f — ✨ feat: 条件渲染支持和上下文系统重构
a1c7a — 🐛 fix: 修复布局系统 schema 类型包裹问题
bae80 — ✨ feat: 优化 AutoForm 组件与 Zod 工厂，支持枚举类型自动注入 items，简化复杂字段渲染逻辑
c527c — ✨ feat: 增强 AutoForm 支持标签输入控件和日期数组字段
01a81 — 🐛 fix: 修复数组项删除时组件状态被重置的问题
5019a — ✨ feat: 增强 AutoForm 支持滑块控件和嵌套字段默认值
d556e — ✨ feat: 增强 AutoForm 数组字段支持添加区域管理示例
2fdfd — ♻️ refactor: 简化 AutoForm 布局实现删除冗余工厂文件
776fa — ♻️ refactor: 重构 AutoForm 架构为 composable 模式
c0332 — ✨ feat: 重新实现 AutoForm 布局分组功能
3873e — ♻️ refactor: 移除 AutoForm 布局分组功能
f97bf — ✨ feat: 新增 AutoForm 布局分组功能
7099c — ♻️ refactor: 优化输入增强组件的实现
d97ef — ♻️ refactor: 优化 AutoForm 组件架构和渲染逻辑