---
title: Form 表单
description: 用于表单校验与提交处理的包裹组件
links:
  source: form/form.tsx
  rac: https://react-spectrum.adobe.com/react-aria/Form.html
---

## 用法

```tsx
import { Form } from '@heroui/react';
```

<ComponentPreview name="form-basic" />

## 组件结构

```tsx
import {Form, Button} from '@heroui/react';

export default () => (
  <Form>
    {/* Form fields go here */}
    <Button type="submit"/>
    <Button type="reset"/>
  </Form>
)
```

## 示例

### 渲染函数

<ComponentPreview
  name="form-render-function"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="form-custom-styles" />

### 全局 CSS

要自定义表单布局与间距，可在 `<Form>` 上使用 `className` prop，或通过 `@layer components` 添加项目级类。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

`Form` 渲染原生 `<form>` 元素，聚焦校验与提交。`@heroui/styles` 中无专用 BEM 类——从全局 CSS 应用容器样式，控件级自定义请使用字段组件。

```css
@layer components {
  .form-layout {
    @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm;
  }
}
```

```tsx
<Form className="form-layout" onSubmit={handleSubmit}>
  {/* TextField, Input, Button, etc. */}
</Form>
```

分组字段与共享布局请使用 [Fieldset](./fieldset)，并定位 `.fieldset`、`.fieldset__legend` 等相关类。单个控件请参阅 [TextField](./text-field)、[Input](./input)、[Label](./label)、[FieldError](./field-error) 的 **Global CSS** 部分。

## 样式参考

HeroUI 对在 `@heroui/styles` 中提供样式的组件遵循 [BEM](https://getbem.com/) 方法论。

`Form` 渲染原生 `<form>` 元素，无专用 BEM 类。通过 `className` 应用布局、间距与表面样式。字段外观与校验状态来自 `TextField`、`Input`、`Label`、`Description`、`FieldError` 等子组件。结构化多字段布局请与 [Fieldset](./fieldset) 组合使用。

## API 参考

### Form

Form 组件是 React Aria Form 原语的包裹层，提供表单校验与提交处理能力。

| Prop | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `action` | `string \| FormHTMLAttributes['action']` | - | 提交表单数据的 URL |
| `className` | `string` | - | 应用于 form 元素的 Tailwind CSS 类 |
| `children` | `React.ReactNode` | - | 表单内容（字段、按钮等） |
| `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | 表单数据提交的编码类型 |
| `method` | `'get' \| 'post'` | - | 提交表单时使用的 HTTP 方法 |
| `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单校验失败时调用。默认聚焦第一个无效字段。使用 `preventDefault()` 可自定义聚焦行为 |
| `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单重置时调用 |
| `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | 表单提交时调用 |
| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | 提交后显示响应的位置 |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验还是 ARIA 校验。`native` 阻止提交，`aria` 实时显示错误 |
| `validationErrors` | `ValidationErrors` | - | 按字段名映射的服务端校验错误。立即显示，用户修改字段时清除 |
| `aria-label` | `string` | - | 表单的无障碍标签 |
| `aria-labelledby` | `string` | - | 标注表单的元素 ID。提供时创建 form landmark |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### Form Validation

Form 组件集成 React Aria 校验系统，支持：

- 使用内置 HTML5 校验属性（`required`、`minLength`、`pattern` 等）
- 在 TextField 组件上提供自定义校验函数
- 使用 FieldError 组件展示校验错误
- 在正确校验后处理表单提交
- 通过 `validationErrors` prop 提供服务端校验错误

#### Validation Behavior

`validationBehavior` prop 控制校验展示方式：

- **`native`**（默认）：使用原生 HTML 校验，有错误时阻止提交
- **`aria`**：使用 ARIA 属性校验，用户输入时实时显示错误，不阻止提交

可在表单级或单个字段级设置此行为。

### Form Submission

表单可通过多种方式提交：

- **传统提交**：设置 `action` prop 提交到 URL
- **JavaScript 处理**：使用 `onSubmit` 处理表单数据
- **FormData API**：在 submit 处理函数中使用 FormData API 访问表单数据

FormData 示例：

```tsx
function handleSubmit(e: FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);
  const data = Object.fromEntries(formData);
  console.log('Form data:', data);
}
```

### Integration with Form Fields

Form 组件与 HeroUI 表单字段组件无缝协作：

- **TextField**：带标签与校验的文本输入
- **Checkbox**：布尔选择
- **RadioGroup**：多选一
- **Switch**：开关控件
- **Button**：提交与重置操作

所有字段组件放在 Form 内时会自动集成 Form 的校验与提交行为。

### Advanced Usage

更高级用法包括：
- 自定义校验上下文
- 表单 context provider
- 与第三方库集成
- 校验错误时的自定义焦点管理

请参阅 [React Aria Form 文档](https://react-spectrum.adobe.com/react-aria/Form.html)。

## 无障碍

使用 React Aria 组件时，表单默认可访问。主要特性包括：

- 原生 `<form>` 元素语义
- 使用 `aria-label` 或 `aria-labelledby` 创建 form landmark
- 校验错误时自动焦点管理
- 使用 `validationBehavior="aria"` 时的 ARIA 校验属性

## 相关案例

<RelatedShowcases component="Form" />

## 相关组件

<RelatedComponents component="form" />