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

Form 自定义样式指南

Form 的视觉表现通过 ControlTheme + Design Token 系统控制。表单系统包含多个控件（Form、FormItem、SubmitButton、ResetButton、FormItemDecorator），每个控件都有独立的 ControlTheme。

---

1. 通过属性直接控制

Form 系统提供了丰富的属性，覆盖了绝大多数自定义场景：

表单级属性

<!-- 布局模式：水平 / 垂直 / 内联 -->
<atom:Form FormLayout="Horizontal" />
<atom:Form FormLayout="Vertical" />
<atom:Form FormLayout="Inline" />

<!-- 标签宽度比例 -->
<atom:Form LabelColInfo="8*" WrapperColInfo="16*" />

<!-- 固定标签宽度 -->
<atom:Form LabelColInfo="120" WrapperColInfo="*" />

<!-- 标签对齐方式 -->
<atom:Form LabelAlign="Left" />    <!-- 默认 Right -->

<!-- 必填标记模式 -->
<atom:Form RequiredMark="Default" />     <!-- 红色星号 -->
<atom:Form RequiredMark="Optional" />    <!-- 显示 "(optional)" -->
<atom:Form RequiredMark="Hidden" />      <!-- 隐藏标记 -->
<atom:Form RequiredMark="Customize" />   <!-- 自定义标记 -->

<!-- 统一尺寸 -->
<atom:Form SizeType="Large" />
<atom:Form SizeType="Middle" />
<atom:Form SizeType="Small" />

<!-- 统一样式变体 -->
<atom:Form StyleVariant="Outline" />
<atom:Form StyleVariant="Filled" />
<atom:Form StyleVariant="Borderless" />
<atom:Form StyleVariant="Underlined" />

<!-- 标签换行 -->
<atom:Form LabelWrapping="Wrap" />

<!-- 隐藏标签 -->
<atom:Form IsHideItemLabel="True" />

<!-- 显示冒号 -->
<atom:Form IsShowColon="False" />

<!-- 验证反馈图标 -->
<atom:Form IsValidateFeedbackEnabled="True" />

字段级属性

<!-- 独立布局覆盖 -->
<atom:FormItem Layout="Vertical" />

<!-- 独立标签宽度覆盖 -->
<atom:FormItem LabelColInfo="4*" WrapperColInfo="20*" />

<!-- 帮助文本 -->
<atom:FormItem Help="Should be combination of numbers and alphabets" />

<!-- 工具提示 -->
<atom:FormItem Tooltip="What do you want others to call you?" />

<!-- 自定义提示图标 -->
<atom:FormItem TooltipIcon="{antdicons:AntDesignIconProvider InfoCircleOutlined}" />

<!-- 单字段验证反馈 -->
<atom:FormItem IsValidateFeedbackEnabled="True" />

<!-- 独立验证触发 -->
<atom:FormItem ValidateTrigger="OnBlur" />

<!-- 验证防抖 -->
<atom:FormItem ValidateDebounce="00:00:01" />

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/FormShowCase.axaml

---

2. 通过 Style 覆盖样式

全局 Form 样式

<Window.Styles>
    <!-- 所有表单统一内边距 -->
    <Style Selector="atom|Form">
        <Setter Property="Padding" Value="16" />
    </Style>
</Window.Styles>

修改 FormItem 标签样式

<!-- 修改标签字体大小和颜色 -->
<Style Selector="atom|FormItem /template/ TextBlock#PART_Label">
    <Setter Property="FontSize" Value="16" />
    <Setter Property="FontWeight" Value="SemiBold" />
</Style>

<!-- 修改必填星号颜色 -->
<Style Selector="atom|FormItem /template/ TextBlock#PART_DefaultRequireMark">
    <Setter Property="Foreground" Value="Orange" />
</Style>

<!-- 修改冒号间距 -->
<Style Selector="atom|FormItem /template/ TextBlock#PART_Colon">
    <Setter Property="Margin" Value="4,0,8,0" />
</Style>

按验证状态定制样式

<!-- 错误状态下的错误消息颜色 -->
<Style Selector="atom|FormItem[ValidateStatus=Error] /template/ TextBlock#PART_ErrorMsg">
    <Setter Property="Foreground" Value="Red" />
    <Setter Property="FontWeight" Value="Bold" />
</Style>

<!-- 警告状态下的帮助文本颜色 -->
<Style Selector="atom|FormItem[ValidateStatus=Warning] /template/ TextBlock#HelpText">
    <Setter Property="Foreground" Value="DarkOrange" />
</Style>

按布局定制样式

<!-- 垂直布局时标签左对齐 + 自定义间距 -->
<Style Selector="atom|FormItem[Layout=Vertical] /template/ Panel#PART_LabelLayout">
    <Setter Property="HorizontalAlignment" Value="Left" />
    <Setter Property="Margin" Value="0,0,0,8" />
</Style>

按尺寸定制样式

<!-- 大号尺寸时标签最小高度 -->
<Style Selector="atom|FormItem[SizeType=Large] /template/ Panel#PART_LabelLayout">
    <Setter Property="MinHeight" Value="48" />
</Style>

<!-- 小号尺寸时标签最小高度 -->
<Style Selector="atom|FormItem[SizeType=Small] /template/ Panel#PART_LabelLayout">
    <Setter Property="MinHeight" Value="28" />
</Style>

---

3. 自定义必填标记

使用 Tag 作为自定义标记

<atom:Form RequiredMark="Customize">
    <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>
    
    <!-- FormItems... -->
</atom:Form>

使用 DataTemplate 自定义标记

<atom:Form RequiredMark="Customize">
    <atom:Form.CustomRequireMarkTemplate>
        <DataTemplate>
            <TextBlock Text="★" Foreground="Red" FontSize="12" />
        </DataTemplate>
    </atom:Form.CustomRequireMarkTemplate>
    
    <!-- FormItems... -->
</atom:Form>

---

4. 自定义验证反馈图标

Form 的验证反馈图标可以通过 FeedbackTemplate 及各状态的模板属性进行替换：

<atom:Form IsValidateFeedbackEnabled="True">
    <!-- 替换成功图标 -->
    <atom:Form.SuccessFeedbackTemplate>
        <DataTemplate>
            <antdicons:CheckCircleFilled
                FillBrush="{atom:SharedTokenResource ColorSuccess}"
                Width="{atom:SharedTokenResource IconSize}"
                Height="{atom:SharedTokenResource IconSize}"/>
        </DataTemplate>
    </atom:Form.SuccessFeedbackTemplate>
    
    <!-- 替换错误图标 -->
    <atom:Form.ErrorFeedbackTemplate>
        <DataTemplate>
            <antdicons:CloseCircleFilled
                FillBrush="{atom:SharedTokenResource ColorError}"
                Width="{atom:SharedTokenResource IconSize}"
                Height="{atom:SharedTokenResource IconSize}"/>
        </DataTemplate>
    </atom:Form.ErrorFeedbackTemplate>
    
    <!-- 替换警告图标 -->
    <atom:Form.WarningFeedbackTemplate>
        <DataTemplate>
            <antdicons:ExclamationCircleFilled
                FillBrush="{atom:SharedTokenResource ColorWarning}"/>
        </DataTemplate>
    </atom:Form.WarningFeedbackTemplate>
    
    <!-- 替换验证中图标（旋转加载） -->
    <atom:Form.ValidatingFeedbackTemplate>
        <DataTemplate>
            <antdicons:LoadingOutlined
                LoadingAnimation="Spin"
                StrokeBrush="{atom:SharedTokenResource ColorIcon}"/>
        </DataTemplate>
    </atom:Form.ValidatingFeedbackTemplate>
    
    <!-- FormItems... -->
</atom:Form>

---

5. 自定义错误/警告消息颜色

<atom:Form ErrorMessageForeground="DarkRed"
           WarningMessageForeground="DarkOrange">
    <!-- FormItems... -->
</atom:Form>

提示：默认情况下这些颜色由 Design Token 控制（ColorErrorText / ColorWarningText），仅在需要覆盖全局主题时才手动设置。

---

6. 自定义删除按钮图标

动态表单中的删除按钮图标可以替换：

<atom:Form IsShowItemDeleteButton="True"
           MinItemCount="1">
    <atom:Form.ItemDeleteButtonIcon>
        <atom:IconTemplate>
            <antdicons:DeleteOutlined/>
        </atom:IconTemplate>
    </atom:Form.ItemDeleteButtonIcon>
    
    <!-- FormItems... -->
</atom:Form>

---

7. 通过 ControlTheme 完全替换主题

如果需要彻底替换 FormItem 的模板，可以定义自定义 ControlTheme：

<ControlTheme x:Key="MyCustomFormItem" TargetType="atom:FormItem">
    <Setter Property="Template">
        <ControlTemplate>
            <!-- 自定义模板... -->
        </ControlTemplate>
    </Setter>
</ControlTheme>

<!-- 使用 -->
<atom:FormItem Theme="{StaticResource MyCustomFormItem}" LabelText="Custom" FieldName="custom">
    <atom:LineEdit />
</atom:FormItem>

⚠️ 注意：完全替换 ControlTheme 将丢失内置的验证状态展示、必填标记、响应式布局等功能。建议优先使用 Style 覆盖或属性控制。

---

样式选择器速查

说明：Avalonia 样式选择器中使用 atom|Form 语法引用 atom XML 命名空间下的控件类型，其中 | 是命名空间分隔符。

Form 选择器

选择器	说明
atom|Form	匹配所有 Form 实例
atom|Form[FormLayout=Horizontal]	匹配水平布局的表单
atom|Form[FormLayout=Vertical]	匹配垂直布局的表单
atom|Form[FormLayout=Inline]	匹配内联布局的表单
atom|Form[SizeType=Large]	匹配大号尺寸的表单
atom|Form[SizeType=Small]	匹配小号尺寸的表单
atom|Form:disabled	匹配禁用状态的表单

FormItem 选择器

选择器	说明
atom|FormItem	匹配所有 FormItem 实例
atom|FormItem[Layout=Horizontal]	匹配水平布局的字段项
atom|FormItem[Layout=Vertical]	匹配垂直布局的字段项
atom|FormItem[IsRequired=True]	匹配必填的字段项
atom|FormItem[ValidateStatus=Error]	匹配验证错误状态的字段项
atom|FormItem[ValidateStatus=Warning]	匹配验证警告状态的字段项
atom|FormItem[ValidateStatus=Success]	匹配验证成功状态的字段项
atom|FormItem[ValidateStatus=Validating]	匹配验证中状态的字段项
atom|FormItem[ValidateStatus=Default]	匹配未验证状态的字段项
atom|FormItem[SizeType=Large]	匹配大号尺寸的字段项
atom|FormItem[SizeType=Middle]	匹配中号尺寸的字段项
atom|FormItem[SizeType=Small]	匹配小号尺寸的字段项
atom|FormItem[RequiredMark=Default]	匹配使用默认必填标记的字段项
atom|FormItem[RequiredMark=Optional]	匹配使用可选标记模式的字段项
atom|FormItem[RequiredMark=Customize]	匹配使用自定义标记的字段项
atom|FormItem[HasErrorOrWarningMsg=True]	匹配有错误/警告消息的字段项
atom|FormItem[HasErrorOrWarningMsg=False]	匹配无错误/警告消息的字段项
atom|FormItem[IsValueItem=True]	匹配数据项（非 FormActionsItem）
atom|FormItem[IsShowItemDeleteButton=True]	匹配显示删除按钮的字段项

FormItem 模板部件

选择器	部件说明
atom|FormItem /template/ DockPanel#PART_RootLayout	根布局面板
atom|FormItem /template/ Panel#PART_LabelLayout	标签区域容器
atom|FormItem /template/ TextBlock#PART_Label	标签文本
atom|FormItem /template/ TextBlock#PART_Colon	冒号文本
atom|FormItem /template/ TextBlock#PART_DefaultRequireMark	红色星号（*）必填标记
atom|FormItem /template/ Grid#PART_BodyLayout	主体布局（标签 + 内容）
atom|FormItem /template/ StackPanel#PART_ContentLayout	内容区域
atom|FormItem /template/ TextBlock#PART_ErrorMsg	错误/警告消息文本
atom|FormItem /template/ TextBlock#HelpText	帮助文本
atom|FormItem /template/ ContentPresenter#ContentPresenter	内容控件展示器
atom|FormItem /template/ ContentPresenter#ExtraPresenter	额外内容展示器
atom|FormItem /template/ ContentPresenter#CustomRequiredMarkPresenter	自定义必填标记展示器
atom|FormItem /template/ ContentPresenter#CustomOptionalMarkPresenter	自定义可选标记展示器
atom|FormItem /template/ TextBlock#OptionalMark	"(optional)" 文本标记
atom|FormItem /template/ atom|IconPresenter#TooltipIconPresenter	提示图标
atom|FormItem /template/ Panel#ItemDeleteButtonLayout	删除按钮布局容器
atom|FormItem /template/ atom|IconButton#ItemDeleteButton	删除按钮

SubmitButton / ResetButton 选择器

选择器	说明
atom|SubmitButton	匹配所有提交按钮（继承自 Button，支持所有 Button 选择器）
atom|ResetButton	匹配所有重置按钮（继承自 Button，支持所有 Button 选择器）
atom|SubmitButton:disabled	匹配禁用状态的提交按钮（如 IsWatchValidateResult 时验证未通过）

FormActionsItem 选择器

选择器	说明
atom|FormActionsItem	匹配所有操作区域项（继承自 FormItem）

组合选择器示例

选择器	说明
atom|FormItem[ValidateStatus=Error] /template/ TextBlock#PART_ErrorMsg	错误状态下的错误消息
atom|FormItem[ValidateStatus=Warning] /template/ TextBlock#HelpText	警告状态下的帮助文本
atom|FormItem[SizeType=Large] /template/ Panel#PART_LabelLayout	大号尺寸的标签区域
atom|FormItem[RequiredMark=Default][IsRequired=True][IsValueItem=True] /template/ TextBlock#PART_DefaultRequireMark	默认模式下必填项的星号标记
atom|FormItem[IsValueItem=True][IsEffectiveShowItemDeleteButton=True] /template/ atom|IconButton#ItemDeleteButton	可删除的数据项的删除按钮