AtomUI/docs/Desktop.Controls/Form/FormUsage.md

Form 使用文档

本文档介绍 AtomUI Form 控件的各种使用方式，示例代码摘自 Gallery 演示程序。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/FormShowCase.axaml

---

前置准备

在 AXAML 中使用 Form，需要引入以下命名空间：

xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // Form, FormItem, SubmitButton, ResetButton 等
using AtomUI.Controls;            // FormLayout, FormValidateTrigger, SizeType 等共享类型

---

1. 基本用法

最基本的表单包含若干 FormItem 和一个 SubmitButton。每个 FormItem 通过 LabelText 设置标签、FieldName 指定字段名、IsRequired 标记必填，并配置验证器。

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left">
    <atom:FormItem LabelText="Username"
                   FieldName="username"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your username!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="Password"
                   FieldName="password"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your password!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit RevealPassword="False"
                       PasswordChar="•"
                       IsEnableRevealButton="True" />
    </atom:FormItem>
    <atom:FormItem FieldName="remember">
        <atom:CheckBox>Remember me</atom:CheckBox>
    </atom:FormItem>
    
    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

关键要点：

• LabelColInfo="8*" 和 WrapperColInfo="16*" 按 8:16 比例分配标签和内容区域宽度
• FormActionsItem 用于放置操作按钮（不参与验证和数据收集）
• SubmitButton 点击时自动触发 Form 验证并提交

---

2. 表单方法（Submit / Reset）

通过 SubmitButton 和 ResetButton 组合使用，支持表单的提交与重置操作：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left">
    <atom:FormItem LabelText="Note"
                   FieldName="note"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please enter Note" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="Gender"
                   FieldName="gender"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please enter Gender" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:Select IsAllowClear="True"
                     PlaceholderText="Select a option and change input text above"
                     HorizontalAlignment="Stretch">
            <atom:SelectOption Header="male" Content="male" />
            <atom:SelectOption Header="female" Content="female" />
            <atom:SelectOption Header="other" Content="other" />
        </atom:Select>
    </atom:FormItem>

    <atom:FormActionsItem>
        <StackPanel Orientation="Horizontal" Spacing="10">
            <atom:SubmitButton />
            <atom:ResetButton />
        </StackPanel>
    </atom:FormActionsItem>
</atom:Form>

说明：ResetButton 点击后会自动清除所有字段值并重置验证状态到初始状态。

---

3. 表单布局（Horizontal / Vertical / Inline）

通过 FormLayout 属性切换三种布局模式。可以在运行时通过数据绑定动态切换。

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           FormLayout="{Binding FormLayout}"
           HorizontalAlignment="Left"
           MinWidth="600">
    <atom:FormItem LabelText="Field A" FieldName="FieldA">
        <atom:LineEdit MinWidth="160"/>
    </atom:FormItem>
    <atom:FormItem LabelText="Field B" FieldName="Field B">
        <atom:LineEdit MinWidth="160"/>
    </atom:FormItem>

    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

FormItem 独立布局覆盖

在同一个 Form 中，不同的 FormItem 可以使用不同的布局方式：

<atom:Form FormLayout="Horizontal">
    <atom:FormItem LabelText="horizontal" FieldName="horizontal"
                   LabelColInfo="4*"
                   WrapperColInfo="20*"
                   IsRequired="True"
                   Layout="Horizontal">
        <atom:LineEdit/>
    </atom:FormItem>

    <atom:FormItem LabelText="vertical"
                   FieldName="vertical"
                   IsRequired="True"
                   Layout="Vertical">
        <atom:LineEdit/>
    </atom:FormItem>
</atom:Form>

提示：FormItem.Layout 属性可覆盖 Form.FormLayout 的全局设置，实现混合布局。

---

4. 禁用表单

通过设置 IsEnabled="False" 禁用整个表单，所有子控件自动进入禁用状态：

<atom:CheckBox IsChecked="{Binding IsFormDisabled, Mode=TwoWay}">Form disabled</atom:CheckBox>
<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           IsEnabled="{Binding IsFormDisabled, Converter={x:Static BoolConverters.Not}}">
    <atom:FormItem LabelText="Checkbox" FieldName="checkbox">
        <atom:CheckBox>Checkbox</atom:CheckBox>
    </atom:FormItem>
    <atom:FormItem LabelText="Input" FieldName="input">
        <atom:LineEdit/>
    </atom:FormItem>
    <atom:FormItem LabelText="Select" FieldName="select">
        <atom:Select HorizontalAlignment="Stretch">
            <atom:SelectOption Header="Demo" Content="demo"/>
        </atom:Select>
    </atom:FormItem>
    <!-- 支持的控件：CheckBox, RadioButton, LineEdit, Select, TreeSelect, Cascader,
         DatePicker, RangeDatePicker, NumericUpDown, TextArea, ToggleSwitch,
         Upload, Slider, ColorPicker, Rate, Mentions, TreeView 等 -->
</atom:Form>

---

5. 表单样式变体（Outlined / Filled / Borderless / Underlined）

通过 StyleVariant 属性统一设置所有子控件的样式变体：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           StyleVariant="{Binding FormStyleVariant}">
    <atom:FormItem LabelText="Input"
                   FieldName="input"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="Select"
                   FieldName="select"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:Select HorizontalAlignment="Stretch" />
    </atom:FormItem>

    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

提示：StyleVariant 支持 Outline（默认）、Filled、Borderless、Underlined 四种值，会自动传播到所有支持该属性的子控件。

---

6. 必填标记样式（Required Mark）

通过 RequiredMark 属性切换必填标记的显示模式，支持 Default、Optional、Hidden、Customize 四种：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           HorizontalAlignment="Left"
           MinWidth="600"
           RequiredMark="{Binding FormRequiredMark}">
    <!-- 自定义必填/可选标记 -->
    <atom:Form.CustomRequireMark>
        <atom:Tag TagColor="Error">required</atom:Tag>
    </atom:Form.CustomRequireMark>
    <atom:Form.CustomOptionalMark>
        <atom:Tag TagColor="Warning">optional</atom:Tag>
    </atom:Form.CustomOptionalMark>
    
    <atom:FormItem IsRequired="True" LabelText="Field A" FieldName="FieldA"
                   Tooltip="This is a required field">
        <atom:LineEdit PlaceholderText="input placeholder"/>
    </atom:FormItem>
    <atom:FormItem LabelText="Field B" FieldName="Field B"
                   Tooltip="Tooltip with customize icon"
                   TooltipIcon="{antdicons:AntDesignIconProvider InfoCircleOutlined}">
        <atom:LineEdit PlaceholderText="input placeholder"/>
    </atom:FormItem>
    <atom:FormActionsItem>
        <atom:SubmitButton/>
    </atom:FormActionsItem>
</atom:Form>

四种标记模式说明：

• Default：必填字段显示红色星号（*）
• Optional：非必填字段显示"（optional）"文字
• Hidden：隐藏所有必填标记
• Customize：使用 CustomRequireMark 和 CustomOptionalMark 自定义标记内容

---

7. 表单尺寸控制（SizeType）

通过 SizeType 属性统一控制表单中所有子控件的尺寸：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           SizeType="{Binding FormSizeType}">
    <atom:FormItem LabelText="Input" FieldName="input">
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="InputNumber" FieldName="inputNumber">
        <atom:NumericUpDown Width="200" />
    </atom:FormItem>
    <atom:FormItem LabelText="Switch" FieldName="switch">
        <atom:ToggleSwitch />
    </atom:FormItem>
    <atom:FormItem LabelText="Select" FieldName="select">
        <atom:Select HorizontalAlignment="Stretch" Mode="Multiple">
            <atom:SelectOption Header="BBB"/>
            <atom:SelectOption Header="AAA"/>
        </atom:Select>
    </atom:FormItem>

    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

说明：SizeType 支持 Small、Middle（默认）、Large 三种值，影响标签高度、控件高度和间距。

---

8. 标签换行（Label Wrap）

当标签文本较长时，通过 LabelWrapping="Wrap" 允许标签自动换行：

<atom:Form LabelColInfo="120"
           WrapperColInfo="*"
           MinWidth="600"
           HorizontalAlignment="Left"
           LabelWrapping="Wrap">
    <atom:FormItem LabelText="Normal label"
                   FieldName="username"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your username!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="A super long label text"
                   FieldName="password"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your username!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
</atom:Form>

提示：LabelColInfo="120" 设置标签区域固定宽度为 120 像素，WrapperColInfo="*" 表示内容区占满剩余空间。

---

9. 仅警告规则（WarningOnly）

设置 WarningOnly="True" 的验证器不阻止表单提交，仅显示警告信息：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           Submitted="HandleNoBlockFormSubmitted"
           Validated="HandleNoBlockFormValidated">
    <atom:FormItem LabelText="Url"
                   FieldName="url"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please enter URL!" />
                <atom:FormUrlValidator Message="URL is not a valid url!" WarningOnly="True" />
                <atom:FormStringLengthValidator Message="URL must be at least 6 characters!"
                                                MinimumLength="6"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>

    <atom:FormActionsItem>
       <StackPanel Orientation="Horizontal" Spacing="10">
           <atom:SubmitButton />
           <atom:Button ButtonType="Default" Click="HandleFillClicked">Fill</atom:Button>
       </StackPanel>
    </atom:FormActionsItem>
</atom:Form>

说明：

• FormStringNotEmptyValidator 和 FormStringLengthValidator 是错误验证器，会阻止提交
• FormUrlValidator 设置了 WarningOnly="True"，即使 URL 格式不对也只显示警告，不阻止提交
• 验证按声明顺序执行，配合 ValidateStrategy 控制执行方式

---

10. 验证触发与防抖（Validate Trigger & Debounce）

可以为不同字段配置不同的验证触发方式、防抖时间和验证策略：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           IsValidateFeedbackEnabled="True">
    <!-- 失焦时验证 -->
    <atom:FormItem LabelText="Field A"
                   FieldName="fieldA"
                   ValidateTrigger="OnBlur">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringLengthValidator Message="Field A must be up to 3 characters!"
                                                MaximumLength="3"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit PlaceholderText="Validate required onBlur"/>
    </atom:FormItem>

    <!-- 防抖验证（1秒后触发） -->
    <atom:FormItem LabelText="FieldB"
                   FieldName="fieldB"
                   ValidateDebounce="00:00:01">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringLengthValidator Message="Field B must be up to 3 characters!"
                                                MaximumLength="3"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit PlaceholderText="Validate required debounce after 1s"/>
    </atom:FormItem>

    <!-- 短路验证（遇到第一个错误即停） -->
    <atom:FormItem LabelText="FieldC"
                   FieldName="fieldC"
                   ValidateStrategy="StopWhenFirstFailed">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringLengthValidator Message="Field C must be up to 6 characters!"
                                                MaximumLength="6"/>
                <atom:FormStringLengthValidator Message="Continue input to exceed 6 chars!"
                                                MaximumLength="3"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit PlaceholderText="Validate one by one"/>
    </atom:FormItem>
</atom:Form>

验证触发方式：

• OnChanged（默认）：值变化时立即验证
• OnBlur：控件失焦时验证
• OnSubmit：仅在提交时验证

验证策略：

• StopWhenFirstFailed（默认）：遇到第一个错误即停止
• Sequential：顺序执行所有验证器
• Parallel：并行执行所有验证器

---

11. 自动禁用提交按钮（Validate Only）

SubmitButton 的 IsWatchValidateResult 属性可以实时监听表单验证结果，自动启用/禁用按钮：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           FormLayout="Vertical">
    <atom:FormItem LabelText="Name"
                   FieldName="name"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please enter Name!"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>

    <atom:FormItem LabelText="Age"
                   FieldName="age"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please enter Age!"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>

    <atom:FormActionsItem>
        <StackPanel Orientation="Horizontal" Spacing="10">
            <atom:SubmitButton IsWatchValidateResult="True"/>
            <atom:ResetButton />
        </StackPanel>
    </atom:FormActionsItem>
</atom:Form>

说明：当 IsWatchValidateResult="True" 时，只有当所有必填字段验证通过后，提交按钮才变为可用状态。

---

12. 动态表单项

支持在运行时动态添加和删除 FormItem：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           Name="DynamicForm">
    <atom:FormItem LabelText="Passengers"
                   FieldName="passengers">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator
                    Message="Please input passenger's name or delete this field!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>

    <atom:FormActionsItem>
        <atom:Button ButtonType="Dashed"
                     HorizontalAlignment="Stretch"
                     Icon="{antdicons:AntDesignIconProvider PlusOutlined}"
                     Click="HandleAddFormItem">
            Add field
        </atom:Button>
    </atom:FormActionsItem>
    <atom:FormActionsItem>
        <atom:Button ButtonType="Dashed"
                     HorizontalAlignment="Stretch"
                     Icon="{antdicons:AntDesignIconProvider PlusOutlined}"
                     Click="HandleAddFormItemAtHead">
            Add field at head
        </atom:Button>
    </atom:FormActionsItem>
    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

// Code-behind：动态添加 FormItem
private int _dynamicFieldIndex;

private void HandleAddFormItem(object? sender, RoutedEventArgs args)
{
    var form = this.FindControl<Form>("DynamicForm")!;
    var formItem = new FormItem
    {
        LabelText = $"Passenger {++_dynamicFieldIndex}",
        FieldName = $"passenger_{_dynamicFieldIndex}",
        Content   = new LineEdit()
    };
    // 插入到最后一个 FormActionsItem 之前
    form.Items.Insert(form.Items.Count - 3, formItem);
}

说明：

• 使用 form.Items.Add() 或 form.Items.Insert() 添加新字段
• 使用 form.DeleteFormItem(item) 删除字段
• 设置 IsShowItemDeleteButton="True" 可在每个数据项旁显示删除按钮
• MinItemCount 控制最少保留的数据项数量

---

13. 自定义表单控件

第三方或自定义控件需要实现 IFormItemAware 接口才能参与表单验证和数据收集：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           FormLayout="Inline">
    <atom:FormItem LabelText="Price"
                   FieldName="price"
                   Width="350">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <gallery:PriceValidator Message="Price must be greater than zero!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <gallery:PriceInput />
    </atom:FormItem>
    <atom:FormActionsItem>
        <atom:SubmitButton />
    </atom:FormActionsItem>
</atom:Form>

实现 IFormItemAware：

public class PriceInput : UserControl, IFormItemAware
{
    public event EventHandler? ValueChanged;
    
    public void SetFormValue(object? value) { /* 设置值到控件 */ }
    public object? GetFormValue() { /* 返回当前值 */ }
    public void ClearFormValue() { /* 清除值 */ }
    public void NotifyValidateStatus(FormValidateStatus status) { /* 更新状态 */ }
}

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/FormShowCase.axaml 中 "Customized Form Controls" 示例。

---

14. FormItemDecorator 装饰器

当需要在主控件旁边附加额外内容（如单位文本），使用 FormItemDecorator 包装：

<atom:FormItem LabelText="InputNumber" FieldName="inputNumber">
    <atom:FormItemDecorator>
        <atom:NumericUpDown Minimum="1" Maximum="10" Width="120"/>
        <atom:FormItemDecorator.Extra>
            machines
        </atom:FormItemDecorator.Extra>
    </atom:FormItemDecorator>
</atom:FormItem>

说明：FormItemDecorator 会代理子控件的 IFormItemAware 接口，确保包装后的控件仍能正常参与表单验证和数据收集。

---

15. 内联登录表单

使用 FormLayout="Inline" 创建紧凑的导航栏登录表单：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left"
           FormLayout="Inline">
    <atom:FormItem LabelText="Username"
                   FieldName="username">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your username!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit InnerLeftContent="{antdicons:AntDesignIconProvider UserOutlined}"
                       PlaceholderText="Username"
                       Width="200"/>
    </atom:FormItem>
    <atom:FormItem LabelText="Password"
                   FieldName="password">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your password!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit InnerLeftContent="{antdicons:AntDesignIconProvider LockOutlined}"
                       PlaceholderText="Password"
                       Width="200"/>
    </atom:FormItem>
    <atom:FormActionsItem>
        <atom:SubmitButton IsWatchValidateResult="True" Content="Log in"/>
    </atom:FormActionsItem>
</atom:Form>

---

16. 隐藏标签登录表单

使用 IsHideItemLabel="True" 隐藏所有 FormItem 的标签区域，常用于独立的登录页面：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="400"
           HorizontalAlignment="Left"
           IsHideItemLabel="True">
    <atom:FormItem FieldName="username">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your username!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit InnerLeftContent="{antdicons:AntDesignIconProvider UserOutlined}"
                       PlaceholderText="Username"/>
    </atom:FormItem>
    <atom:FormItem FieldName="password">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your password!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit InnerLeftContent="{antdicons:AntDesignIconProvider LockOutlined}"
                       PlaceholderText="Password"/>
    </atom:FormItem>
    <atom:FormItem FieldName="remember">
        <atom:CheckBox IsChecked="True">Remember me</atom:CheckBox>
        <atom:FormItem.Extra>
            <atom:HyperLinkButton>Forgot password</atom:HyperLinkButton>
        </atom:FormItem.Extra>
    </atom:FormItem>
    <atom:FormActionsItem>
        <StackPanel>
            <atom:SubmitButton Content="Log in" HorizontalAlignment="Stretch"/>
            <StackPanel Orientation="Horizontal" Spacing="5">
                <TextBlock>Or</TextBlock>
                <atom:HyperLinkTextBlock>Register now!</atom:HyperLinkTextBlock>
            </StackPanel>
        </StackPanel>
    </atom:FormActionsItem>
</atom:Form>

---

17. 注册表单（综合示例）

一个包含多种控件类型的完整注册表单：

<atom:Form LabelColInfo="8*"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left">
    <atom:FormItem LabelText="Email"
                   FieldName="email"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your E-mail!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="Password"
                   FieldName="password"
                   IsRequired="True"
                   IsValidateFeedbackEnabled="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your password!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit RevealPassword="False"
                       PasswordChar="•"
                       IsEnableRevealButton="True" />
    </atom:FormItem>
    <atom:FormItem LabelText="Nickname"
                   FieldName="nickname"
                   IsRequired="True"
                   Tooltip="What do you want others to call you?">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input your nickname!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:LineEdit />
    </atom:FormItem>
    <atom:FormItem LabelText="Habitual Residence"
                   FieldName="residence"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select your habitual residence!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:Cascader HorizontalAlignment="Stretch" IsAllowClear="True">
            <atom:CascaderOption Header="Zhejiang" Value="zhejiang">
                <atom:CascaderOption Header="Hangzhou" Value="hangzhou">
                    <atom:CascaderOption Header="West Lake" Value="xihu" />
                </atom:CascaderOption>
            </atom:CascaderOption>
        </atom:Cascader>
    </atom:FormItem>
    <atom:FormItem LabelText="Gender"
                   FieldName="gender"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select gender!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:Select DefaultValues="male" HorizontalAlignment="Stretch">
            <atom:SelectOption Header="Male" Content="male"/>
            <atom:SelectOption Header="Female" Content="female"/>
            <atom:SelectOption Header="Other" Content="other"/>
        </atom:Select>
    </atom:FormItem>
    <atom:FormItem LabelText="Intro"
                   FieldName="intro"
                   IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormStringNotEmptyValidator Message="Please input Intro!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:TextArea IsShowCount="True" MaxLength="100"/>
    </atom:FormItem>
    <atom:FormItem FieldName="agreement" IsRequired="True">
        <atom:CheckBox IsChecked="True">
           <StackPanel Orientation="Horizontal" Spacing="5">
               <TextBlock>I have read the</TextBlock>
               <atom:HyperLinkTextBlock>agreement</atom:HyperLinkTextBlock>
           </StackPanel>
        </atom:CheckBox>
    </atom:FormItem>
    <atom:FormActionsItem>
        <atom:SubmitButton Content="Register"/>
    </atom:FormActionsItem>
</atom:Form>

---

18. 时间类控件

Form 支持所有 AtomUI 的时间选择控件：

<atom:Form LabelColInfo="200"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left">
    <atom:FormItem LabelText="DatePicker" FieldName="datePicker" IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select time!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:DatePicker PlaceholderText="Select date!"/>
    </atom:FormItem>

    <atom:FormItem LabelText="DatePicker[showTime]" FieldName="datePickerShowTime" IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select time!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:DatePicker PlaceholderText="Select date!" IsShowTime="True"/>
    </atom:FormItem>

    <atom:FormItem LabelText="RangePicker" FieldName="rangePicker" IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select time!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:RangeDatePicker PlaceholderText="Start date"
                              SecondaryPlaceholderText="End date"/>
    </atom:FormItem>

    <atom:FormItem LabelText="TimePicker" FieldName="timePicker" IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select time!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:TimePicker PlaceholderText="Start time"/>
    </atom:FormItem>

    <atom:FormActionsItem>
        <atom:SubmitButton/>
    </atom:FormActionsItem>
</atom:Form>

---

19. 自定义验证状态展示

可以使用 FormAssertValidator 来强制设置验证状态，配合 IsValidateFeedbackEnabled 显示反馈图标：

<atom:FormItem LabelText="Success"
               FieldName="success"
               IsValidateFeedbackEnabled="True">
    <atom:FormItem.Validators>
        <atom:FormValidatorProvider>
            <atom:FormAssertValidator AssertResult="True"/>
        </atom:FormValidatorProvider>
    </atom:FormItem.Validators>
    <atom:LineEdit PlaceholderText="I'm the content"/>
</atom:FormItem>

<atom:FormItem LabelText="Warning"
               FieldName="warning"
               IsValidateFeedbackEnabled="True">
    <atom:FormItem.Validators>
        <atom:FormValidatorProvider>
            <atom:FormAssertValidator AssertResult="False" WarningOnly="True"/>
        </atom:FormValidatorProvider>
    </atom:FormItem.Validators>
    <atom:LineEdit PlaceholderText="I'm the content"/>
</atom:FormItem>

<atom:FormItem LabelText="Fail"
               FieldName="fail"
               IsValidateFeedbackEnabled="True"
               Help="Should be combination of numbers and alphabets">
    <atom:FormItem.Validators>
        <atom:FormValidatorProvider>
            <atom:FormAssertValidator AssertResult="False"/>
        </atom:FormValidatorProvider>
    </atom:FormItem.Validators>
    <atom:LineEdit PlaceholderText="unavailable choice"/>
</atom:FormItem>

<atom:FormItem LabelText="Validating"
               FieldName="validating"
               Help="The information is being validated"
               IsValidateFeedbackEnabled="True">
    <atom:FormItem.Validators>
        <atom:FormValidatorProvider>
            <atom:FormAssertValidator AssertResult="True" Delay="00:01:00"/>
        </atom:FormValidatorProvider>
    </atom:FormItem.Validators>
    <atom:LineEdit PlaceholderText="I'm the content is being validated"/>
</atom:FormItem>

说明：

• IsValidateFeedbackEnabled="True" 在输入控件内显示验证状态图标（✓ / ⚠ / ✗ / ⏳）
• Help 属性显示固定帮助文本，颜色随验证状态变化
• FormAssertValidator 的 Delay 属性可模拟异步验证延迟

---

20. 其他表单控件

Form 支持几乎所有 AtomUI 数据录入和交互控件：

<atom:Form LabelColInfo="200"
           WrapperColInfo="16*"
           MinWidth="600"
           HorizontalAlignment="Left">
    <!-- 纯文本 -->
    <atom:FormItem LabelText="Plain Text" FieldName="plainText">
        <atom:TextBlock Text="China"/>
    </atom:FormItem>
    
    <!-- 单选 / 多选 Select -->
    <atom:FormItem LabelText="Select" FieldName="select" IsValidateFeedbackEnabled="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="Please select your country!" />
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:Select PlaceholderText="Please select a country" HorizontalAlignment="Stretch">
            <atom:SelectOption Header="China" Content="china"/>
            <atom:SelectOption Header="U.S.A" Content="usa"/>
        </atom:Select>
    </atom:FormItem>
    
    <!-- FormItemDecorator + NumericUpDown -->
    <atom:FormItem LabelText="InputNumber" FieldName="inputNumber">
       <atom:FormItemDecorator>
           <atom:NumericUpDown Minimum="1" Maximum="10" Width="120"/>
           <atom:FormItemDecorator.Extra>
               machines
           </atom:FormItemDecorator.Extra>
       </atom:FormItemDecorator>
    </atom:FormItem>
    
    <!-- 开关 -->
    <atom:FormItem LabelText="Switch" FieldName="switch">
        <atom:ToggleSwitch/>
    </atom:FormItem>
    
    <!-- 滑块 -->
    <atom:FormItem LabelText="Slider" FieldName="slider">
        <atom:Slider Minimum="0" Maximum="100"/>
    </atom:FormItem>
    
    <!-- 单选按钮组 -->
    <atom:FormItem LabelText="radio-group" FieldName="radioGroup">
        <atom:RadioButtonGroup>
            <atom:RadioButton Tag="a">item 1</atom:RadioButton>
            <atom:RadioButton Tag="b">item 2</atom:RadioButton>
            <atom:RadioButton Tag="c">item 3</atom:RadioButton>
        </atom:RadioButtonGroup>
    </atom:FormItem>
    
    <!-- 复选框组 -->
    <atom:FormItem LabelText="Checkbox.Group" FieldName="checkboxGroup">
        <atom:CheckBoxGroup Width="150" HorizontalAlignment="Left">
            <atom:CheckBox Tag="a">A</atom:CheckBox>
            <atom:CheckBox Tag="b" IsChecked="True" IsEnabled="False">B</atom:CheckBox>
            <atom:CheckBox Tag="c">C</atom:CheckBox>
        </atom:CheckBoxGroup>
    </atom:FormItem>
    
    <!-- 评分 -->
    <atom:FormItem LabelText="Rate" FieldName="rate">
        <atom:Rate/>
    </atom:FormItem>
    
    <!-- 颜色选择器 -->
    <atom:FormItem LabelText="ColorPicker" FieldName="colorPicker" IsRequired="True">
        <atom:FormItem.Validators>
            <atom:FormValidatorProvider>
                <atom:FormNotNullValidator Message="color is required!"/>
            </atom:FormValidatorProvider>
        </atom:FormItem.Validators>
        <atom:ColorPicker/>
    </atom:FormItem>

    <!-- 上传 -->
    <atom:FormItem LabelText="Upload" FieldName="upload">
        <atom:Upload>
            <atom:Button Icon="{antdicons:AntDesignIconProvider UploadOutlined}">
                Click to Upload
            </atom:Button>
        </atom:Upload>
    </atom:FormItem>
    
    <!-- 拖拽上传 -->
    <atom:FormItem LabelText="Dragger" FieldName="dragger">
        <atom:Upload>
            <atom:UploadDefaultDropArea/>
        </atom:Upload>
    </atom:FormItem>
    
    <atom:FormActionsItem>
        <atom:SubmitButton/>
    </atom:FormActionsItem>
</atom:Form>

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/FormShowCase.axaml 中 "Other Form Controls" 示例。

---

常见组合模式

基本提交/重置

<atom:FormActionsItem>
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:SubmitButton />
        <atom:ResetButton />
    </StackPanel>
</atom:FormActionsItem>

带验证监听的提交按钮

<atom:FormActionsItem>
    <atom:SubmitButton IsWatchValidateResult="True" Content="Log in"/>
</atom:FormActionsItem>

动态添加按钮

<atom:FormActionsItem>
    <atom:Button ButtonType="Dashed"
                 HorizontalAlignment="Stretch"
                 Icon="{antdicons:AntDesignIconProvider PlusOutlined}"
                 Click="HandleAddFormItem">
        Add field
    </atom:Button>
</atom:FormActionsItem>

C# 代码操作表单

// 获取 Form 引用
var form = this.FindControl<Form>("MyForm")!;

// 手动触发验证
form.Validate();

// 异步验证并获取结果
var result = await form.ValidateAsync(CancellationToken.None);

// 提交表单
form.Submit();

// 重置表单
form.Reset();

// 批量设置值
form.SetFormValues(new FormValues(new Dictionary<string, object?>
{
    ["username"] = "admin",
    ["password"] = "123456"
}));

// 监听提交事件
form.Submitted += (sender, args) =>
{
    var values = args.Values; // IFormValues
    // 处理提交的数据...
};