---
title: "快速开始"
description: "了解 AutoForm 的核心设计理念和基本使用方式。"
seo_title: "Quickstart"
seo_description: "Get started with AutoForm — define a Zod schema with afz, derive types, and render a full form with validation in a few lines."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/auto-form/quickstart"
---
# 快速开始

> 了解 AutoForm 的核心设计理念和基本使用方式。

## 什么是 AutoForm

AutoForm 是一个基于 Zod Schema 的自动表单生成系统。通过声明式的 Schema 定义，自动生成完整的表单界面，包括输入控件、验证规则和布局结构。

> \[\!NOTE\]
> 
> **核心优势**
> 
> - **Schema 即表单** \- 一份 Schema 同时定义数据结构、验证规则和 UI 配置
> - **类型安全** \- 完整的 TypeScript 类型推断，从 Schema 到表单数据
> - **零模板代码** \- 无需手写 `v-for` 或重复的表单字段模板

## 基础示例

创建一个简单的用户注册表单：

```vue [AutoFormBasicExample.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({
  username: afz.string('请填写用户名').min(3).max(20).regex(/^\w+$/),
  email: afz.email({
    controlProps: {
      leadingIcon: 'i-lucide-mail',
      placeholder: '请输入您的邮箱'
    },
    error: '请输入有效的邮箱地址'
  }).meta({ hint: '邮箱' }),
  password: afz.string({ type: 'withPasswordToggle' })
    .min(8)
    .regex(/[A-Z]/)
    .regex(/[a-z]/)
    .regex(/\d/),
  confirmPassword: afz.string({ type: 'withPasswordToggle' }),
  acceptTerms: afz.boolean({
    controlProps: { label: '我同意服务条款和隐私政策', required: true }
  })
}).refine(
  data => data.password === data.confirmPassword,
  { message: '两次密码不一致', path: ['confirmPassword'] }
).refine(
  data => data.acceptTerms === true,
  { message: '必须同意条款', path: ['acceptTerms'] }
)

type Schema = z.output<typeof schema>

const form = ref<Partial<Schema>>({})

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

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

## API

### Props

```ts
/**
 * Props for the MAutoForm component
 */
interface MAutoFormProps {
  /**
   * Zod 对象 schema，定义表单字段
   */
  schema: S;
  /**
   * 表单的状态对象。
   */
  state?: (N extends false ? Partial<InferInput<S>> : never) | undefined;
  /**
   * 是否显示默认提交按钮
   * @default "true"
   */
  submit?: boolean | undefined;
  /**
   * 提交按钮属性
   */
  submitButtonProps?: ButtonProps | undefined;
  /**
   * 数组字段添加按钮属性
   */
  addButtonProps?: ButtonProps | undefined;
  /**
   * 自定义控件映射
   */
  controls?: AutoFormControls | undefined;
  /**
   * 全局字段元数据配置
   */
  globalMeta?: ZodAutoFormFieldMeta | undefined;
  /**
   * 是否启用自动 loading 功能。
   * @default "true"
   */
  loadingAuto?: boolean | undefined;
  /**
   * 表单验证时机，详见 UForm 的 validateOn 属性
   * @default "[]"
   */
  validateOn?: FormInputEvents[] | undefined;
  ui?: (Record<string, C> & { root?: SlotClass; base?: SlotClass; collapsible?: SlotClass; header?: SlotClass; footer?: SlotClass; actions?: SlotClass; }) | undefined;
  id?: string | number | undefined;
  /**
   * Custom validation function to validate the form state.
   */
  validate?: ((state: Partial<InferInput<S>>) => FormError<string>[] | Promise<FormError<string>[]>) | undefined;
  /**
   * Disable all inputs inside the form.
   */
  disabled?: boolean | undefined;
  /**
   * The `name` attribute of the form element.
   * For nested forms (`nested` is true), this is also used as the path of the form's state within its parent form.
   */
  name?: string | undefined;
  /**
   * Delay in milliseconds before validating the form on input events.
   */
  validateOnInputDelay?: number | undefined;
  /**
   * If true, applies schema transformations on submit.
   */
  transform?: T | undefined;
  /**
   * If true, this form will attach to its parent Form and validate at the same time.
   */
  nested?: N | undefined;
  onSubmit?: (() => void) | ((event: FormSubmitEvent<FormData<S, T>>) => void) | undefined;
  acceptcharset?: string | undefined;
  action?: string | undefined;
  autocomplete?: string | undefined;
  enctype?: string | undefined;
  method?: string | undefined;
  novalidate?: Booleanish | undefined;
  target?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the MAutoForm component
 */
interface MAutoFormSlots {
  header(): any;
  footer(): any;
  submit(): any;
  field-label(): any;
  field-hint(): any;
  field-description(): any;
  field-help(): any;
  field-error(): any;
  field-default(): any;
}
```

> \[\!NOTE\]
> 
> 除了组件级别的插槽外，AutoForm 还支持字段级别的动态插槽，并提供完整的 TypeScript 类型推断和编辑器自动补全。
> 
> | 插槽模式                          | 示例                                            | 说明                  |
> | ----------------------------- | --------------------------------------------- | ------------------- |
> | `field-{slotType}`            | `field-label`, `field-default`                | 通用插槽，适用于所有字段        |
> | `field-{slotType}:{fieldKey}` | `field-label:username`, `field-default:email` | 特定字段插槽，享受**完整类型推导** |
> | `field-{position}:{fieldKey}` | `field-before:profile`, `field-content:tasks` | 嵌套字段布局插槽            |

### Emits

```ts
/**
 * Emitted events for the MAutoForm component
 */
interface MAutoFormEmits {
  error: (payload: [FormErrorEvent]) => void;
}
```

### Expose

您可以通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="[\"nofollow\"]"} 访问该类型化组件实例。

| Name      | Type                                                                       |
| --------- | -------------------------------------------------------------------------- |
| `reset()` | `void`   
 重置表单到初始状态，包括恢复 props 中的 `state` 和应用所有默认值                        |
| `clear()` | `void`   
 清空表单所有字段数据                                                      |
| `formRef` | `Ref<InstanceType<typeof UForm> | null>`   
 UForm 组件的模板引用，可访问底层表单的所有方法和属性 |

> \[\!TIP\]
> See: https://ui.nuxt.com/docs/components/form#expose
> 
> 通过 
> 
> formRef
> 
>  可以访问 UForm 的所有底层功能，包括 
> 
> submit()
> 
> 、
> 
> validate()
> 
> 、
> 
> clear()
> 
> 、
> 
> getErrors()
> 
> 、
> 
> setErrors()
> 
>  等方法，以及 
> 
> errors
> 
> 、
> 
> disabled
> 
> 、
> 
> dirty
> 
> 、
> 
> dirtyFields
> 
> 、
> 
> touchedFields
> 
> 、
> 
> blurredFields
> 
>  等响应式属性。详见 Nuxt UI Form 文档。

## Theme

<component-theme slug="AutoForm"></component-theme>## Changelog

See commit history for [src/runtime/components/快速开始.vue](https://github.com/mhaibaraai/movk-nuxt/commits/main/src/runtime/components/快速开始.vue).


## Sitemap

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