# Form 使用文档
本文档介绍 AtomUI Form 控件的各种使用方式，示例代码摘自 Gallery 演示程序。
> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/FormShowCase.axaml`
---
## 前置准备
在 AXAML 中使用 Form，需要引入以下命名空间：
```xml
xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"
```
在 C# 代码中引入：
```csharp
using AtomUI.Desktop.Controls; // Form, FormItem, SubmitButton, ResetButton 等
using AtomUI.Controls; // FormLayout, FormValidateTrigger, SizeType 等共享类型
```
---
## 1. 基本用法
最基本的表单包含若干 `FormItem` 和一个 `SubmitButton`。每个 `FormItem` 通过 `LabelText` 设置标签、`FieldName` 指定字段名、`IsRequired` 标记必填，并配置验证器。
```xml
Remember me
```
**关键要点**：
- `LabelColInfo="8*"` 和 `WrapperColInfo="16*"` 按 8:16 比例分配标签和内容区域宽度
- `FormActionsItem` 用于放置操作按钮（不参与验证和数据收集）
- `SubmitButton` 点击时自动触发 Form 验证并提交
---
## 2. 表单方法（Submit / Reset）
通过 `SubmitButton` 和 `ResetButton` 组合使用，支持表单的提交与重置操作：
```xml
```
**说明**：`ResetButton` 点击后会自动清除所有字段值并重置验证状态到初始状态。
---
## 3. 表单布局（Horizontal / Vertical / Inline）
通过 `FormLayout` 属性切换三种布局模式。可以在运行时通过数据绑定动态切换。
```xml
```
### FormItem 独立布局覆盖
在同一个 Form 中，不同的 FormItem 可以使用不同的布局方式：
```xml
```
**提示**：`FormItem.Layout` 属性可覆盖 `Form.FormLayout` 的全局设置，实现混合布局。
---
## 4. 禁用表单
通过设置 `IsEnabled="False"` 禁用整个表单，所有子控件自动进入禁用状态：
```xml
Form disabled
Checkbox
```
---
## 5. 表单样式变体（Outlined / Filled / Borderless / Underlined）
通过 `StyleVariant` 属性统一设置所有子控件的样式变体：
```xml
```
**提示**：`StyleVariant` 支持 `Outline`（默认）、`Filled`、`Borderless`、`Underlined` 四种值，会自动传播到所有支持该属性的子控件。
---
## 6. 必填标记样式（Required Mark）
通过 `RequiredMark` 属性切换必填标记的显示模式，支持 Default、Optional、Hidden、Customize 四种：
```xml
required
optional
```
**四种标记模式说明**：
- `Default`：必填字段显示红色星号（*）
- `Optional`：非必填字段显示"（optional）"文字
- `Hidden`：隐藏所有必填标记
- `Customize`：使用 `CustomRequireMark` 和 `CustomOptionalMark` 自定义标记内容
---
## 7. 表单尺寸控制（SizeType）
通过 `SizeType` 属性统一控制表单中所有子控件的尺寸：
```xml
```
**说明**：`SizeType` 支持 `Small`、`Middle`（默认）、`Large` 三种值，影响标签高度、控件高度和间距。
---
## 8. 标签换行（Label Wrap）
当标签文本较长时，通过 `LabelWrapping="Wrap"` 允许标签自动换行：
```xml
```
**提示**：`LabelColInfo="120"` 设置标签区域固定宽度为 120 像素，`WrapperColInfo="*"` 表示内容区占满剩余空间。
---
## 9. 仅警告规则（WarningOnly）
设置 `WarningOnly="True"` 的验证器不阻止表单提交，仅显示警告信息：
```xml
Fill
```
**说明**：
- `FormStringNotEmptyValidator` 和 `FormStringLengthValidator` 是错误验证器，会阻止提交
- `FormUrlValidator` 设置了 `WarningOnly="True"`，即使 URL 格式不对也只显示警告，不阻止提交
- 验证按声明顺序执行，配合 `ValidateStrategy` 控制执行方式
---
## 10. 验证触发与防抖（Validate Trigger & Debounce）
可以为不同字段配置不同的验证触发方式、防抖时间和验证策略：
```xml
```
**验证触发方式**：
- `OnChanged`（默认）：值变化时立即验证
- `OnBlur`：控件失焦时验证
- `OnSubmit`：仅在提交时验证
**验证策略**：
- `StopWhenFirstFailed`（默认）：遇到第一个错误即停止
- `Sequential`：顺序执行所有验证器
- `Parallel`：并行执行所有验证器
---
## 11. 自动禁用提交按钮（Validate Only）
`SubmitButton` 的 `IsWatchValidateResult` 属性可以实时监听表单验证结果，自动启用/禁用按钮：
```xml
```
**说明**：当 `IsWatchValidateResult="True"` 时，只有当所有必填字段验证通过后，提交按钮才变为可用状态。
---
## 12. 动态表单项
支持在运行时动态添加和删除 FormItem：
```xml
Add field
Add field at head
```
```csharp
// Code-behind：动态添加 FormItem
private int _dynamicFieldIndex;
private void HandleAddFormItem(object? sender, RoutedEventArgs args)
{
var form = this.FindControl