| Name | Description |
|---|---|
field-label | 字段标签 |
field-hint | 字段提示文本 |
field-description | 字段描述 |
field-help | 字段帮助信息 |
field-error | 字段错误信息 |
field-default | 输入控件 |
使用 field-{slotType} 格式,为所有字段应用统一的自定义样式:
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod/v4'
const toast = useToast()
const { afz } = useAutoForm()
const schema = afz.object({
username: afz.string().min(3).meta({ label: '用户名' }),
email: afz.email().meta({ label: '邮箱' }),
role: afz.enum(['admin', 'user', 'guest']).meta({ label: '角色' }),
active: afz.boolean({ controlProps: { label: '是否激活账户' } }).meta({ label: '激活状态' })
})
type Schema = z.output<typeof schema>
const form = ref<Partial<Schema>>({})
async function onSubmit(event: FormSubmitEvent<Schema>) {
toast.add({
title: '提交成功',
color: 'success',
description: JSON.stringify(event.data, null, 2)
})
}
</script>
<template>
<UCard>
<MAutoForm :schema="schema" :state="form" @submit="onSubmit">
<template #field-label="{ label, path }">
<UBadge
:color="path === 'username' ? 'primary' : path === 'email' ? 'success' : path === 'role' ? 'info' : 'warning'"
variant="subtle"
size="xs"
>
{{ label }}
</UBadge>
</template>
<template #field-hint="{ path }">
<span class="inline-flex items-center gap-1.5 text-xs text-gray-500 dark:text-gray-400 mt-1">
<UIcon name="i-lucide-sparkles" class="size-3" />
<span>字段路径: {{ path }}</span>
</span>
</template>
<template #field-error="{ error }">
<transition
enter-active-class="transition duration-200 ease-out"
enter-from-class="opacity-0 -translate-y-1"
enter-to-class="opacity-100 translate-y-0"
leave-active-class="transition duration-150 ease-in"
leave-from-class="opacity-100 translate-y-0"
leave-to-class="opacity-0 -translate-y-1"
>
<UAlert
v-if="error"
color="error"
variant="subtle"
icon="i-lucide-triangle-alert"
:description="String(error)"
class="mt-2"
/>
</transition>
</template>
</MAutoForm>
</UCard>
</template>
使用 field-{slotType}:{fieldPath} 格式,仅针对特定字段自定义:
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod/v4'
const toast = useToast()
const { afz } = useAutoForm()
const schema = afz.object({
username: afz.string().min(3, '用户名至少 3 个字符').meta({ label: '用户名' }),
email: afz.email('请输入有效的邮箱地址').meta({ label: '邮箱' }),
password: afz.string().min(8, '密码至少 8 个字符').meta({ label: '密码' }),
bio: afz.string({ type: 'textarea' }).meta({ label: '个人简介' })
})
type Schema = z.output<typeof schema>
const form = ref<Partial<Schema>>({})
async function onSubmit(event: FormSubmitEvent<Schema>) {
toast.add({
title: '提交成功',
color: 'success',
description: JSON.stringify(event.data, null, 2)
})
}
</script>
<template>
<UCard>
<MAutoForm
:schema="schema"
:state="form"
:global-meta="{
ui: {
label: 'flex items-center',
hint: 'flex items-center'
}
}"
@submit="onSubmit"
>
<template #field-label:username="{ label }">
<span>{{ label }}</span>
<UBadge
color="primary"
variant="subtle"
size="xs"
class="ml-2"
>
必填
</UBadge>
</template>
<template #field-hint:username>
<UIcon name="i-lucide-info" class="text-warning mr-2" />
<span>这将是您的唯一标识</span>
</template>
<template #field-label:email="{ label }">
<UBadge icon="i-lucide-mail" :label="label" />
</template>
<template #field-description:email>
<span class="text-xs mt-1 text-success-600">
我们将向此邮箱发送验证链接
</span>
</template>
<template #field-help:password>
<ul class="space-y-0.5 list-disc list-inside">
<li>至少 8 个字符</li>
<li>包含大小写字母</li>
<li>包含数字和特殊字符</li>
</ul>
</template>
<template #field-error:bio="{ error }">
<span v-if="error" class="text-xs text-red-700 dark:text-red-300 bg-red-50 p-2 rounded w-full">
<UIcon name="i-lucide-frown" class="text-red-500" />
{{ error }}
</span>
</template>
</MAutoForm>
</UCard>
</template>
field-label 和 field-label:username,后者会生效。所有字段插槽都接收以下参数:
| Name | Type | Description |
|---|---|---|
state | FormState | 表单数据 |
path | string | 字段路径 (如 'username' 或 'profile.name') |
value | any | 当前字段值 |
setValue | SetValueFn | 设置字段值的函数 |
errors | unknown[] | 字段错误列表 |
loading | boolean | 表单加载状态 |
不同插槽类型有各自的专属参数:
| Slot Type | Parameter | Type | Description |
|---|---|---|---|
field-label | label | string | 字段标签文本 |
field-hint | hint | string | 提示文本 |
field-description | description | string | 描述文本 |
field-help | help | string | 帮助文本 |
field-error | error | string | boolean | 错误信息 |