---
title: "Array 数组"
description: "afz.array() 的元素定义、元数据覆盖与到多值控件的映射。"
seo_title: "Array Field"
seo_description: "How a Zod array field maps to AutoForm controls — element schema, meta override, input tags, checkbox group and object array collapsibles."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/auto-form/array"
---
# Array 数组

> afz.array() 的元素定义、元数据覆盖与到多值控件的映射。

> \[\!NOTE\]
> See: https://zod.dev/api#arrays
> 
> 使用 
> 
> afz.array()
> 
>  创建数组字段：

## ElementSchema

定义数组元素的类型，决定输出类型为 `T[]`：

```ts
// 字符串数组
const schema1 = afz.array(afz.string())
// 输出类型：string[]

// 对象数组
const schema2 = afz.array(afz.object({
  name: afz.string(),
  age: afz.number()
}))
// 输出类型：{ name: string, age: number }[]
```

## Meta

> \[\!NOTE\]
> 
> 用于
> 
> 覆盖数组元素的默认控件
> 
> 和配置元数据，同时保持输出类型不变：

> \[\!TIP\]
> 
> 对于对象数组（如 `afz.array(afz.object({...}))`），系统会自动使用折叠面板渲染，无需手动指定控件类型。
> 
> 不指定控件类型，数组元素使用默认映射：
> 
> ```ts
> afz.array(afz.string(), {
>   label: '标签列表',
>   hint: '添加多个标签'
> })
> // string[] - 元素默认使用 input 控件
> ```
> 
> 通过 `type` 覆盖数组**元素的默认控件**，输出类型保持不变：
> 
> ```ts
> afz.array(afz.string(), {
>   type: 'checkboxGroup',  // 覆盖 string 的默认 input 控件
>   controlProps: {
>     items: ['reading', 'gaming', 'sports']
>   }
> })
> // 输出类型仍为：string[]
> // 但使用 checkboxGroup 渲染（多选）
> ```
> 
> `afz.string()` 本来会被映射为 `input` 控件，通过第二个参数的 `type: 'checkboxGroup'` 覆盖了这个默认映射，将其改为多选框形式。
> 
> 直接传入自定义组件实例：
> 
> ```ts
> import MyArrayControl from './MyArrayControl.vue'
> 
> afz.array(afz.string(), {
>   component: MyArrayControl,
>   controlProps: { /* ... */ }
> })
> ```

## `InputTags`

> \[\!NOTE\]
> See: https://ui.nuxt.com/docs/components/input-tags
> 
> InputTags 组件文档

标签输入框，设置 `type: 'inputTags'`，适合自由文本标签：

```vue [AutoFormFieldArrayInputTagsExample.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({
  tags: afz.array(afz.string(), {
    type: 'inputTags'
  })
    .default(['tag1', 'tag2'])
    .meta({
      label: '标签输入',
      hint: '输入后按 Enter 添加标签'
    })
})

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

## `CheckboxGroup`

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

复选框组，设置 `type: 'checkboxGroup'`，适合预定义选项多选：

```vue [AutoFormFieldArrayCheckboxGroupExample.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({
  notifications: afz.array(afz.string(), {
    type: 'checkboxGroup',
    controlProps: {
      items: [
        { label: '邮件', value: 'email' },
        { label: '短信', value: 'sms' },
        { label: '电话', value: 'phone' }
      ]
    }
  })
    .default(['email'])
    .meta({
      label: '复选框组',
      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>
```

## 对象数组

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

对象数组自动使用折叠面板渲染，支持添加、删除项：

```vue [AutoFormFieldArrayObjectExample.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({
  experience: afz.array(
    afz.object({
      company: afz.string({
        controlProps: {
          placeholder: '公司名称'
        }
      }).min(1).meta({ label: '公司' }),
      position: afz.string({
        controlProps: {
          placeholder: '职位'
        }
      }).min(1).meta({ label: '职位' }),
      years: afz.number({
        controlProps: {
          placeholder: '工作年限'
        }
      }).int().min(0).max(50).meta({ label: '年限', hint: '工作年数' })
    }).meta({ label: '工作经历' })
  ).default([{
    company: '示例公司',
    position: '软件工程师',
    years: 3
  }]).meta({
    label: '工作经历列表',
    collapsible: { defaultOpen: true }
  })
})

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.