useAutoForm

用于创建类型化 Zod Schema 和管理 AutoForm 控件的 composable。

Usage

使用自动导入的 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 元数据。
元数据会自动在 Zod 的链式调用中持久化（如 .optional(), .nullable(), .default() 等）。

使用 afz 工厂创建的 Schema 会自动拦截 Zod 的克隆方法，确保元数据在链式调用时不会丢失。

自定义控件注册

当使用自定义控件时，需要通过 defineControl 辅助函数定义：

const { afz, defineControl } = useAutoForm({
  myInput: defineControl({
    component: MyCustomInput,
    controlProps: { class: 'w-full' }
  })
})

// 现在可以在 Schema 中使用
const schema = afz.string({
  type: 'myInput',
  controlProps: { variant: 'outline' }
})

控件映射

默认

Schema 类型	默认控件	说明
`string`	`UInput`	文本输入框
`number`	`UInputNumber`	数字输入框
`boolean`	`UCheckbox`	复选框
`enum`	`USelect`	下拉选择
`file`	`UFileUpload`	文件上传
`calendarDate`	`DatePicker`	日期选择器

扩展控件类型

通过 type 元数据可以使用以下扩展控件：

type 类型	控件	说明
`switch`	`USwitch`	开关
`textarea`	`UTextarea`	多行文本输入框
`slider`	`USlider`	滑块
`pinInput`	`UPinInput`	验证码输入框
`inputTags`	`UInputTags`	标签输入
`selectMenu`	`USelectMenu`	选择菜单
`inputMenu`	`UInputMenu`	输入菜单
`checkboxGroup`	`UCheckboxGroup`	复选框组
`radioGroup`	`URadioGroup`	单选框组
`withClear`	`UInput`	带清除按钮的输入框
`withPasswordToggle`	`UInput`	密码显示切换
`withCopy`	`UInput`	带复制按钮
`withCharacterLimit`	`UInput`	字符计数限制
`colorChooser`	`UColorPicker`	颜色选择器
`starRating`	`StarRating`	星级评分
`slideVerify`	`SlideVerify`	滑动验证

API

useAutoForm()

useAutoForm(controls?: AutoFormControls): UseAutoFormReturn

创建 AutoForm 工厂和控件管理器。

Parameters

controls

AutoFormControls

自定义控件映射对象，用于扩展或覆盖默认控件。

Returns

afz

TypedZodFactory

类型化的 Zod 工厂对象，用于创建带元数据的 Schema。

defineControl

Function

定义控件的辅助函数。

DEFAULT_CONTROLS

Object

默认控件映射对象。

controls

Object

传入的自定义控件映射。

getAutoFormMetadata

Function

从 Schema 中提取自定义元数据的工具函数。

afz 工厂方法

基础类型

afz.string()

(meta?: string | AutoFormMeta) => ZodString

创建字符串类型 Schema，默认映射到 UInput 组件。

afz.number()

(meta?: string | AutoFormMeta) => ZodNumber

创建数字类型 Schema，默认映射到 UInputNumber 组件。

afz.boolean()

(meta?: string | AutoFormMeta) => ZodBoolean

创建布尔类型 Schema，默认映射到 UCheckbox 组件。

afz.file()

(meta?: string | AutoFormMeta) => ZodFile

创建文件类型 Schema，默认映射到 UFileUpload 组件。

afz.calendarDate()

<T = CalendarDate>(meta?: string | AutoFormMeta) => ZodType<T>

创建日期类型 Schema，默认映射到 DatePicker 组件。

Zod v4 专用验证

afz.email()

(meta?: string | AutoFormMeta) => ZodEmail

创建 Email 验证 Schema。推荐使用此方法代替 afz.string().email()（已在 Zod v4 中弃用）。

afz.url()

(meta?: string | AutoFormMeta) => ZodUrl

创建 URL 验证 Schema。

afz.uuid()

(meta?: string | AutoFormMeta) => ZodUuid

创建 UUID 验证 Schema。

集合类型

afz.array()

(schema: ZodType, overwrite?: AutoFormMeta) => ZodArray

创建数组类型 Schema。

afz.tuple()

(schemas: [ZodType, ...ZodType[]], overwrite?: AutoFormMeta) => ZodTuple

创建元组类型 Schema。

afz.enum()

(values: any, overwrite?: AutoFormMeta) => ZodEnum

创建枚举类型 Schema，默认映射到 USelect 组件。

对象类型

afz.object()

(shape: ZodRawShape, meta?: AutoFormMeta) => ZodObject

创建标准对象 Schema。支持柯里化写法以获得更好的类型推断。

// 推荐：柯里化写法（更好的类型推断）
const schema = afz.object<MyType>()({
  field: afz.string()
})

// 也可以：直接传参
const schema = afz.object({
  field: afz.string()
})

afz.looseObject()

(shape: ZodRawShape, meta?: AutoFormMeta) => ZodObject

创建宽松对象 Schema（允许额外字段）。

afz.strictObject()

(shape: ZodRawShape, meta?: AutoFormMeta) => ZodObject

创建严格对象 Schema（不允许额外字段）。

布局系统

afz.layout()

<C extends IsComponent>(config: AutoFormLayoutConfig<C>) => ZodType

创建布局字段，用于在表单中插入布局组件（如 UFormGrid, UCard 等）。

元数据选项

元数据可以是字符串（仅错误消息）或对象：

type

string

控件类型，如 'textarea', 'switch', 'slider' 等。

label

string

字段标签文本。

description

string

字段描述文本。

placeholder

string

输入框占位符。

controlProps

object

传递给控件组件的 props。

error

string

自定义错误消息。

// 简化写法：仅错误消息
afz.string('这个字段是必填的')

// 完整写法：带控件配置
afz.string({
  type: 'textarea',
  label: '个人简介',
  placeholder: '请输入个人简介',
  controlProps: { rows: 4 }
})

Changelog

f541f — feat: 集成 SlideVerify 为 AutoForm 控件

30cef — fix: 改进 DEFAULT_CONTROLS 类型定义以增强类型推导

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 模式

布局系统

使用布局系统灵活控制表单字段的视觉呈现和组织结构

useApiFetch

基于 Nuxt useFetch 封装的 API 请求 composable，提供自动认证、业务状态码检查和 Toast 提示。