使用自动导入的 useAutoForm composable 创建类型化的 Zod Schema,为 AutoForm 组件提供验证规则和控件配置。
<script setup lang="ts">
const { afz } = useAutoForm()
const schema = afz.object({
username: afz.string('用户名不能为空'),
email: afz.email('请输入有效的邮箱地址'),
age: afz.number().min(18, '必须年满 18 岁')
})
const formData = ref()
</script>
<template>
<MAutoForm v-model="formData" :schema="schema" />
</template>
useAutoForm 返回增强的 Zod 工厂对象 afz,支持为 Schema 附加 AutoForm 元数据。.optional(), .nullable(), .default() 等)。afz 工厂创建的 Schema 会自动拦截 Zod 的克隆方法,确保元数据在链式调用时不会丢失。useAutoForm(controls?: AutoFormControls): UseAutoFormReturn
创建 AutoForm 工厂和控件管理器。
const { afz } = useAutoForm({
myCustomInput: defineControl({
component: CustomInputComponent,
controlProps: { class: 'w-full' }
})
})
UInput 组件。UInputNumber 组件。UCheckbox 组件。UFileUpload 组件。DatePicker 组件。afz.string().email()(已在 Zod v4 中弃用)。USelect 组件。// 推荐:柯里化写法(更好的类型推断)
const schema = afz.object<MyType>()({
field: afz.string()
})
// 也可以:直接传参
const schema = afz.object({
field: afz.string()
})
UFormGrid, UCard 等)。const schema = afz.object({
$layout: afz.layout({
component: 'UFormGrid',
props: { columns: 2 }
}),
firstName: afz.string(),
lastName: afz.string()
})
元数据可以是字符串(仅错误消息)或对象:
'textarea', 'switch', 'slider' 等。// 简化写法:仅错误消息
afz.string('这个字段是必填的')
// 完整写法:带控件配置
afz.string({
type: 'textarea',
label: '个人简介',
placeholder: '请输入个人简介',
controlProps: { rows: 4 }
})
| Schema 类型 | 默认控件 | 说明 |
|---|---|---|
string | UInput | 文本输入框 |
number | UInputNumber | 数字输入框 |
boolean | UCheckbox | 复选框 |
enum | USelect | 下拉选择 |
file | UFileUpload | 文件上传 |
calendarDate | DatePicker | 日期选择器 |
通过 type 元数据可以使用以下扩展控件:
switch - 开关组件 (USwitch)textarea - 多行文本 (UTextarea)slider - 滑块 (USlider)pinInput - PIN 码输入 (UPinInput)inputTags - 标签输入 (UInputTags)selectMenu - 下拉菜单 (USelectMenu)inputMenu - 输入菜单 (UInputMenu)checkboxGroup - 复选框组 (UCheckboxGroup)radioGroup - 单选框组 (URadioGroup)withClear - 带清除按钮的输入框withPasswordToggle - 密码显示切换withCopy - 带复制按钮withCharacterLimit - 字符计数限制colorChooser - 颜色选择器starRating - 星级评分以下是一个完整的使用示例:
<script setup lang="ts">
const { afz } = useAutoForm()
// 创建复杂表单 Schema
const schema = afz.object({
// 基础信息布局
$basicLayout: afz.layout({
component: 'UFormGrid',
props: { columns: 2 }
}),
firstName: afz.string('请输入名字'),
lastName: afz.string('请输入姓氏'),
// Email 使用 Zod v4 专用验证
email: afz.email('请输入有效的邮箱地址'),
// 使用自定义控件类型
bio: afz.string({
type: 'textarea',
label: '个人简介',
controlProps: { rows: 4 }
}),
// 带密码切换的输入框
password: afz.string({
type: 'withPasswordToggle',
label: '密码',
placeholder: '请输入密码'
}).min(8, '密码至少 8 位'),
// 开关控件
newsletter: afz.boolean({
type: 'switch',
label: '订阅邮件通知'
}),
// 数字滑块
age: afz.number({
type: 'slider',
label: '年龄',
controlProps: { min: 18, max: 100 }
}),
// 地址信息卡片布局
$addressLayout: afz.layout({
component: 'UCard',
props: {
title: '地址信息',
class: 'mt-4'
}
}),
street: afz.string('请输入街道地址'),
city: afz.string('请输入城市'),
// 日期选择
birthdate: afz.calendarDate('请选择出生日期')
})
const formData = ref()
async function handleSubmit() {
console.log('提交数据:', formData.value)
}
</script>
<template>
<MAutoForm
v-model="formData"
:schema="schema"
@submit="handleSubmit"
/>
</template>
从 Zod v4 开始,某些字符串验证方法已被弃用。使用 afz 时应遵循以下规范:
// ✅ 推荐:使用专用函数
afz.email('请输入邮箱')
afz.url('请输入 URL')
afz.uuid('请输入 UUID')
// ❌ 避免:已弃用的写法
afz.string().email()
afz.string().url()
afz.string().uuid()
使用 afz 工厂创建的 Schema 会自动拦截以下克隆方法,确保元数据不丢失:
.optional() - 设为可选.nullable() - 允许 null.default() - 设置默认值.describe() - 添加描述.meta() - 添加元数据.refine() - 添加自定义验证.transform() - 添加转换函数// 元数据会在链式调用中自动传递
const schema = afz.string({
type: 'withClear',
label: '用户名'
})
.optional() // 元数据保留
.default('') // 元数据保留
当使用自定义控件时,需要通过 defineControl 辅助函数定义:
const { afz, defineControl } = useAutoForm({
myInput: defineControl({
component: MyCustomInput,
controlProps: { class: 'w-full' }
})
})
// 现在可以在 Schema 中使用
const schema = afz.string({
type: 'myInput',
controlProps: { variant: 'outline' }
})
e1be5 — feat: 新增 inputDate、inputTime 和 ISO 日期时间字段支持
90cef — feat: 支持 inputDate 和 inputTime 日期输入控件
04cd2 — refactor: 重组控件默认值分类,补充文档资源引用
f9682 — refactor: 迁移核心工具到 @movk/core 包,更新导入路径
7ca22 — ✨ feat: 增强 AutoForm 类型系统,支持路径字段值提取
5ecc3 — ✨ feat: 添加 StarRating 组件和直接组件示例
6c861 — 🐛 fix: 修复元数据处理逻辑中的空值判断问题
a2759 — ♻️ refactor: 简化对象工厂实现并优化类型定义
570d0 — ♻️ refactor: 优化 afz.object 类型重载顺序以修复类型提示
77be0 — ♻️ refactor: 增强 AutoForm 核心功能支持 Zod v4
e74f2 — ✨ feat: 增强表单控件系统
3d983 — ♻️ refactor: 重构复杂类型工厂方法
bae80 — ✨ feat: 优化 AutoForm 组件与 Zod 工厂,支持枚举类型自动注入 items,简化复杂字段渲染逻辑
c527c — ✨ feat: 增强 AutoForm 支持标签输入控件和日期数组字段
1cf3c — 📚 docs: 恢复 AutoForm 示例页面完整功能并添加新控件
2f4f4 — ✨ feat: 增强数组工厂方法支持元组类型和控件元数据配置
be369 — ♻️ refactor: 提取数组字段默认值收集函数到工具模块并优化装饰器提取逻辑
5019a — ✨ feat: 增强 AutoForm 支持滑块控件和嵌套字段默认值
d3176 — 🐛 fix: 修复布局系统类型错误和调试代码
2fdfd — ♻️ refactor: 简化 AutoForm 布局实现删除冗余工厂文件
212ed — ♻️ refactor: 重构 AutoForm 布局机制支持多布局系统
776fa — ♻️ refactor: 重构 AutoForm 架构为 composable 模式