Movk Nuxt

Enum

View source

Enum 字段类型的使用方法和配置选项

基础用法

使用 afz.enum() 创建枚举字段：

Select

Select 组件文档

原生选择框，适合简单的枚举值：

<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({
  status: afz.enum(['active', 'inactive', 'pending'])
    .default('active')
    .meta({
      label: '选择框',
      placeholder: '请选择状态',
      hint: '基础枚举选择'
    })
})

async function onSubmit(event: FormSubmitEvent<z.output<typeof schema>>) {
  toast.add({
    title: 'Success',
    color: 'success',
    description: JSON.stringify(event.data, null, 2)
  })
}
</script>

<template>
  <MAutoForm :schema="schema" @submit="onSubmit" />
</template>

SelectMenu

SelectMenu 组件文档

下拉菜单，设置 type: 'selectMenu'，支持搜索、图标、分组：

<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({
  fruit: afz.enum([], {
    type: 'selectMenu',
    controlProps: {
      placeholder: '选择水果',
      valueKey: 'value',
      items: [
        { label: '苹果', value: 'apple' },
        { label: '香蕉', value: 'banana' },
        { label: '橙子', value: 'orange' }
      ]
    }
  })
    .meta({
      label: '下拉菜单'
    })
})

async function onSubmit(event: FormSubmitEvent<z.output<typeof schema>>) {
  toast.add({
    title: 'Success',
    color: 'success',
    description: JSON.stringify(event.data, null, 2)
  })
}
</script>

<template>
  <MAutoForm :schema="schema" @submit="onSubmit" />
</template>

RadioGroup

RadioGroup 组件文档

单选按钮组，设置 type: 'radioGroup'，适合 2-4 个选项：

<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({
  theme: afz.enum([], {
    type: 'radioGroup',
    controlProps: {
      valueKey: 'id',
      items: [
        { label: 'System', description: '跟随系统设置', id: 'system' },
        { label: 'Light', description: '浅色主题', id: 'light' },
        { label: 'Dark', description: '深色主题', id: 'dark' }
      ]
    }
  })
    .default('system')
    .meta({
      label: '单选组'
    })
})

async function onSubmit(event: FormSubmitEvent<z.output<typeof schema>>) {
  toast.add({
    title: 'Success',
    color: 'success',
    description: JSON.stringify(event.data, null, 2)
  })
}
</script>

<template>
  <MAutoForm :schema="schema" @submit="onSubmit" />
</template>

API

afz.enum(values, meta?)

Values

决定字段的输出类型，支持三种形式：

1. 空数组 `[]`

返回 ZodString，用于运行时动态选项：

const schema = afz.object({
  category: afz.enum([], {
    type: 'selectMenu',
    controlProps: {
      items: categories.value  // 运行时动态数据
    }
  })
})
// 输出类型：string

2. 字符串数组

返回 ZodEnum，提供类型安全的字面量联合类型：

const Fruits = ['apple', 'banana', 'orange'] as const
const schema = afz.object({
  fruit: afz.enum(Fruits)
})
// 输出类型：'apple' | 'banana' | 'orange'

3. 枚举对象

返回 ZodEnum，支持 TypeScript 原生枚举：

enum Status {
  Active = 'active',
  Inactive = 'inactive'
}
const schema = afz.object({
  status: afz.enum(Status)
})
// 输出类型：Status

枚举值配置优先级

controlProps.items 以最高优先级决定渲染内容，enum() 的第一个参数决定输出类型，两者可以兼用。

配置方式

方式 1：自动提取枚举值

系统会自动将枚举值转换为 items：

const Fruits = ['apple', 'banana', 'orange'] as const

const schema = afz.object({
  fruit: afz.enum(Fruits, {
    type: 'selectMenu',
    controlProps: {
      placeholder: '选择水果'
      // 系统自动转换：items: ['apple', 'banana', 'orange']
    }
  })
})

方式 2：手动提供 items

使用空数组 [] 作为第一个参数，完全由 items 决定类型和渲染：

const schema = afz.object({
  fruit: afz.enum([], {
    type: 'selectMenu',
    controlProps: {
      valueKey: 'value',
      items: [
        { label: '苹果', value: 'apple' },
        { label: '香蕉', value: 'banana' }
      ]
    }
  })
})

方式 3：类型 + 自定义显示（推荐）

同时使用枚举参数和 items，既保证类型安全，又自定义显示：

const schema = afz.object({
  gender: afz.enum(['male', 'female', 'other'], {
    type: 'radioGroup',
    controlProps: {
      items: [
        { label: '男', value: 'male' },
        { label: '女', value: 'female' },
        { label: '其他', value: 'other' }
      ]
    }
  })
})
// 输出类型：'male' | 'female' | 'other'
// 显示内容：男 / 女 / 其他

优先级规则：

controlProps.items 存在时，以其为准进行渲染
enum([...]) 参数决定 TypeScript 输出类型
两者可以组合使用，实现类型安全 + 自定义显示

Date

Date 字段类型的使用方法和配置选项

Array

Array 字段类型的使用方法和配置选项