字段级插槽

View source
字段插槽允许你微调表单中每个字段的各个部分,包括标签、提示、错误信息等。

可用插槽

NameDescription
field-label字段标签
field-hint字段提示文本
field-description字段描述
field-help字段帮助信息
field-error字段错误信息
field-default输入控件

使用方式

通用模式

使用 field-{slotType} 格式,为所有字段应用统一的自定义样式:

字段路径: username
字段路径: email
字段路径: role
字段路径: active
<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} 格式,仅针对特定字段自定义:

这将是您的唯一标识

我们将向此邮箱发送验证链接

  • 至少 8 个字符
  • 包含大小写字母
  • 包含数字和特殊字符
<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-labelfield-label:username,后者会生效。

插槽参数

通用参数

所有字段插槽都接收以下参数:

NameTypeDescription
stateFormState表单数据
pathstring字段路径 (如 'username''profile.name')
valueany当前字段值
setValueSetValueFn设置字段值的函数
errorsunknown[]字段错误列表
loadingboolean表单加载状态

特定插槽参数

不同插槽类型有各自的专属参数:

Slot TypeParameterTypeDescription
field-labellabelstring字段标签文本
field-hinthintstring提示文本
field-descriptiondescriptionstring描述文本
field-helphelpstring帮助文本
field-errorerrorstring | boolean错误信息
field-default 插槽用于自定义基础类型字段(string、number、boolean 等)的输入控件。对于对象和数组字段,请使用 内容插槽 中的 field-content
Copyright © 2025 - 2025 YiXuan - MIT License