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

Form API 参考

命名空间

namespace AtomUI.Desktop.Controls;  // Form, FormItem, FormActionsItem, SubmitButton, ResetButton, FormItemDecorator
namespace AtomUI.Controls;           // FormLayout, FormLabelAlign, FormRequiredMark 等枚举, IFormValidator 等接口

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

FormLayout

表单布局枚举。

值	说明
Horizontal	水平布局（默认）——标签在左、内容在右，一行一个字段
Vertical	垂直布局——标签在上、内容在下
Inline	内联布局——所有字段水平排列在同一行

FormLabelAlign

标签对齐方式枚举。

值	说明
Left	标签左对齐
Right	标签右对齐（默认）

FormRequiredMark

必填标记模式枚举。

值	说明
Default	显示红色星号（*）标记必填字段（默认）
Hidden	隐藏所有必填标记
Optional	在非必填字段旁显示"（optional）"文字
Customize	使用自定义模板（通过 CustomRequireMark / CustomOptionalMark 设置）

FormValidateTrigger

验证触发时机枚举。

值	说明
OnChanged	值变化时触发验证（默认）
OnBlur	控件失焦时触发验证
OnSubmit	仅在提交时触发验证

FormValidateStrategy

验证执行策略枚举。

值	说明
StopWhenFirstFailed	遇到第一个错误即停止（默认），但会收集已执行的警告
Sequential	顺序执行所有验证器，收集所有错误和警告
Parallel	并行执行所有验证器，收集所有错误和警告

FormValidateStatus

字段验证状态枚举。

值	说明
Default	初始状态（未验证）
Success	验证通过
Warning	验证警告（不阻止提交）
Error	验证错误（阻止提交）
Validating	验证进行中

FormValidateResult

验证结果枚举（验证器返回值）。

值	说明
Success	验证通过
Error	验证错误
Warning	验证警告

FormItemLayout

FormItem 内部布局枚举。

值	说明
Horizontal	标签在左、内容在右
Vertical	标签在上、内容在下

InputControlStyleVariant（来自 AtomUI.Controls）

输入控件样式变体枚举。

值	说明
Outline	有边框（默认）
Filled	填充背景
Borderless	无边框
Underlined	下划线

---

Form 公共属性（StyledProperty）

属性名	类型	默认值	说明
FormLayout	FormLayout	Horizontal	表单布局模式
LabelAlign	FormLabelAlign	Right	标签对齐方式
LabelWrapping	TextWrapping	NoWrap	标签文本换行方式
IsShowColon	bool	true	是否在标签后显示冒号
RequiredMark	FormRequiredMark	Default	必填标记模式
ValidateTrigger	FormValidateTrigger	OnChanged	全局验证触发时机
SizeType	SizeType	Middle	表单控件尺寸（共享属性）
StyleVariant	InputControlStyleVariant	Outline	表单控件样式变体（共享属性）
IsMotionEnabled	bool	跟随全局 Token	是否启用动画（共享属性）
IsValidateFeedbackEnabled	bool	false	是否在控件内显示验证状态图标
LabelColInfo	MediaBreakGridLength?	null	标签列宽度（支持响应式）
WrapperColInfo	MediaBreakGridLength?	null	内容列宽度（支持响应式）
ScrollToFirstError	bool	false	验证失败时是否滚动到第一个错误字段
CustomRequireMark	object?	null	自定义必填标记内容
CustomRequireMarkTemplate	IDataTemplate?	null	自定义必填标记模板
CustomOptionalMark	object?	null	自定义可选标记内容
CustomOptionalMarkTemplate	IDataTemplate?	null	自定义可选标记模板
FeedbackTemplate	IDataTemplate?	null	验证反馈图标模板
ErrorMessageForeground	IBrush?	null（由 Token 控制）	错误消息前景色
WarningMessageForeground	IBrush?	null（由 Token 控制）	警告消息前景色
MinItemCount	int	1	最少数据项数量（控制删除按钮可见性）
ItemDeleteButtonIcon	IIconTemplate?	null	删除按钮自定义图标
IsShowItemDeleteButton	bool	false	是否显示删除按钮
IsHideItemLabel	bool	false	是否隐藏 FormItem 的标签区域
SuccessFeedback	object?	null	成功状态反馈内容
SuccessFeedbackTemplate	IDataTemplate?	null	成功状态反馈模板
WarningFeedback	object?	null	警告状态反馈内容
WarningFeedbackTemplate	IDataTemplate?	null	警告状态反馈模板
ErrorFeedback	object?	null	错误状态反馈内容
ErrorFeedbackTemplate	IDataTemplate?	null	错误状态反馈模板
ValidatingFeedback	object?	null	验证中状态反馈内容
ValidatingFeedbackTemplate	IDataTemplate?	null	验证中状态反馈模板

Form 只读属性（DirectProperty）

属性名	类型	说明
Values	IFormValues?	当前表单值（只读，提交时收集）
InitialValues	IFormValues?	表单初始值（加载时自动填充）
IsFormValid	bool?	表单整体验证状态（只读）

---

FormItem 公共属性（StyledProperty）

属性名	类型	默认值	说明
LabelText	string?	null	标签文本
FieldName	string?	null	字段名称（表单值收集的 key）
Content	Control?	null	表单项内容控件（标记为 [Content]）
IsRequired	bool	false	是否必填（显示必填标记）
Validators	IList<IFormValidator>?	null	验证器列表
ValidateTrigger	FormValidateTrigger	继承自 Form	验证触发时机（可覆盖 Form 级设置）
ValidateDebounce	TimeSpan	TimeSpan.Zero	验证防抖延迟
ValidateStrategy	FormValidateStrategy	StopWhenFirstFailed	验证执行策略
Layout	FormItemLayout	Horizontal	FormItem 内部布局（可覆盖 Form 级设置）
LabelAlign	FormLabelAlign	继承自 Form	标签对齐方式
LabelWrapping	TextWrapping	继承自 Form	标签换行方式
LabelColInfo	MediaBreakGridLength?	继承自 Form	标签列宽度
WrapperColInfo	MediaBreakGridLength?	继承自 Form	内容列宽度
Tooltip	string?	null	标签旁的提示文字
TooltipIcon	PathIcon?	QuestionCircleOutlined	提示图标
Help	string?	null	固定帮助文本（始终显示在控件下方）
Extra	object?	null	额外内容（显示在控件右侧）
ExtraTemplate	IDataTemplate?	null	额外内容模板
InitialValue	object?	null	字段初始值
IsValidateFeedbackEnabled	bool	继承自 Form	是否显示验证反馈图标
IsValidateContentType	bool	true	是否验证内容控件类型（IFormItemAware）
ChildrenSpacing	double	0	子控件间距

FormItem 只读属性（DirectProperty）

属性名	类型	说明
ValidateStatus	FormValidateStatus	当前验证状态
ValidateResult	FormValidateResult	当前验证结果

---

SubmitButton 公共属性

属性名	类型	默认值	说明
IsWatchValidateResult	bool	false	是否监听表单验证结果自动启用/禁用按钮

SubmitButton 继承自 Button，拥有 Button 的所有属性（ButtonType、Content、SizeType 等）。

---

ResetButton

ResetButton 继承自 Button，无额外属性。点击时自动触发 Form 重置。

---

FormItemDecorator 公共属性

属性名	类型	默认值	说明
Child	Control?	null	包装的子控件（标记为 [Content]）
Extra	object?	null	额外内容（如单位文本）
ExtraTemplate	IDataTemplate?	null	额外内容模板
ItemSpacing	double	0	子控件与额外内容的间距
StyleVariant	InputControlStyleVariant	继承自 FormItem	样式变体
Status	InputControlStatus	Default	输入控件状态
SizeType	SizeType	继承自 FormItem	尺寸
IsMotionEnabled	bool	继承自 FormItem	动画开关

---

事件

Form 事件

事件名	类型	说明
AboutToValidate	EventHandler<EventArgs>	即将开始验证时触发
Validated	EventHandler<FormValidatedEventArgs>	验证完成后触发（包含验证结果和消息列表）
Submitted	EventHandler<FormSubmittedEventArgs>	表单提交时触发（验证通过后，包含表单值）
ItemValueChanged	EventHandler<FormItemValueChangedEventArgs>	任意字段值变化时触发
ResetCompleted	EventHandler	表单重置完成后触发

FormItem 事件

事件名	类型	说明
ValidateChanged	EventHandler<FormItemValidateChangedEventArgs>	字段验证状态变化时触发（路由事件）

SubmitButton 事件

事件名	类型	说明
Submit	EventHandler<RoutedEventArgs>	提交按钮点击时触发（路由事件，冒泡至 Form）

ResetButton 事件

事件名	类型	说明
Reset	EventHandler<RoutedEventArgs>	重置按钮点击时触发（路由事件，冒泡至 Form）

---

公共方法

Form 方法

方法	返回值	说明
Validate()	void	触发所有字段验证（异步执行）
ValidateAsync(CancellationToken)	Task<FormValidateResult>	异步验证所有字段，返回汇总结果
Submit()	void	先验证，验证通过后收集值并触发 Submitted 事件
Reset()	void	重置所有字段到初始状态，清除验证状态
SetFormValues(IFormValues)	void	批量设置表单字段值
DeleteFormItem(IFormItem)	void	从表单中删除指定字段项

---

内置验证器

验证器类	说明	关键属性
FormStringNotEmptyValidator	字符串不为空/空白验证	Message
FormStringLengthValidator	字符串长度范围验证	Message, MinimumLength, MaximumLength
FormUrlValidator	URL 格式验证	Message, WarningOnly
FormNotNullValidator	非 null 验证	Message
FormAssertValidator	断言验证（用于演示/测试）	Message, AssertResult, WarningOnly, Delay

所有验证器通过 FormValidatorProvider 容器在 AXAML 中声明：

<atom:FormItem.Validators>
    <atom:FormValidatorProvider>
        <atom:FormStringNotEmptyValidator Message="必填字段!" />
        <atom:FormStringLengthValidator Message="长度至少6位!" MinimumLength="6" />
    </atom:FormValidatorProvider>
</atom:FormItem.Validators>

---

实现的接口

Form

接口	作用
ISizeTypeAware	支持 SizeType（Small / Middle / Large）尺寸切换，自动传播到所有子控件
IMotionAwareControl	支持动画开关
IForm	表单核心接口（Validate / Submit / Reset / SetFormValues / DeleteFormItem）
IInputControlStyleVariantAware	支持样式变体（Outlined / Filled / Borderless / Underlined），自动传播到子控件

FormItem

接口	作用
IFormItem	表单字段项接口（FieldName、Content、GetItemValue / SetItemValue / ResetItemValue）

FormItemDecorator

接口	作用
IFormItemAware	代理子控件的表单值接口
IFormItemFeedbackAware	代理子控件的验证反馈接口
ISizeTypeAware	尺寸传播
IMotionAwareControl	动画传播
IInputControlStatusAware	输入状态传播
IInputControlStyleVariantAware	样式变体传播