---
title: "Enum 枚举"
description: "afz.enum() 的配置方式与到选择类控件的映射。"
seo_title: "Enum Field"
seo_description: "How a Zod enum field maps to AutoForm controls — select, select menu and radio group — with item override strategies."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/auto-form/enum"
---
# Enum 枚举

> afz.enum() 的配置方式与到选择类控件的映射。

> \[\!NOTE\]
> See: https://zod.dev/api#enums
> 
> 使用 
> 
> afz.enum()
> 
>  创建枚举字段：

> \[\!TIP\]
> 
> 用于覆盖默认控件和配置元数据，支持三种配置方式：
> 
> 不指定控件类型，使用默认的 `select` 控件：
> 
> ```ts
> afz.enum(['a', 'b'], {
>   label: '选择选项',
>   hint: '请选择一个'
> })
> ```
> 
> 通过 `type` 覆盖默认控件，同时保持输出类型不变：
> 
> ```ts
> afz.enum(['a', 'b', 'c'], {
>   type: 'radioGroup',  // 覆盖默认的 select
>   controlProps: {
>     items: [
>       { label: '选项A', value: 'a' },
>       { label: '选项B', value: 'b' }
>     ]
>   }
> })
> // 输出类型仍为：'a' | 'b' | 'c'
> // 但使用 radioGroup 渲染
> ```
> 
> 直接传入自定义组件实例：
> 
> ```ts
> import MyEnumControl from './MyEnumControl.vue'
> 
> afz.enum(['a', 'b'], {
>   component: MyEnumControl,
>   controlProps: { /* ... */ }
> })
> ```

> \[\!TIP\]
> 
> 枚举值配置：`controlProps.items` 以最高优先级决定渲染内容，`enum()` 的第一个参数决定输出类型，两者可以兼用。
> 
> - 方式 1：自动提取枚举值，系统会自动将枚举值转换为 `items`：```ts
>   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` 决定类型和渲染：```ts
>   const schema = afz.object({
>   fruit: afz.enum([], {
>     type: 'selectMenu',
>     controlProps: {
>       valueKey: 'value',
>       items: [
>         { label: '苹果', value: 'apple' },
>         { label: '香蕉', value: 'banana' }
>       ]
>     }
>   })
>   })
>   ```
> - 方式 3：类型 + 自定义显示（推荐），同时使用枚举参数和 `items`，既保证类型安全，又自定义显示：```ts
>   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'
>   // 显示内容：男 / 女 / 其他
>   ```

## `Select`

> \[\!NOTE\]
> See: https://ui.nuxt.com/docs/components/select
> 
> Select 组件文档

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

```vue [AutoFormFieldEnumSelectExample.vue]
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod'

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`

> \[\!NOTE\]
> See: https://ui.nuxt.com/docs/components/select-menu
> 
> SelectMenu 组件文档

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

```vue [AutoFormFieldEnumSelectMenuExample.vue]
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod'

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`

> \[\!NOTE\]
> See: https://ui.nuxt.com/docs/components/radio-group
> 
> RadioGroup 组件文档

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

```vue [AutoFormFieldEnumRadioGroupExample.vue]
<script lang="ts" setup>
import type { FormSubmitEvent } from '@nuxt/ui'
import type { z } from 'zod'

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>
```


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.