AtomUI/docs/Desktop.Controls/ComboBox/ComboBoxAPI.md

ComboBox API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

InputControlStyleVariant

样式变体枚举，定义控件的视觉风格。

值	说明
Outline	描边样式（默认），白色背景 + 实线边框
Filled	填充样式，灰色填充背景
Borderless	无边框样式，无背景无边框

InputControlStatus

输入控件验证状态枚举。

值	说明
Default	默认状态（无验证反馈）
Error	错误状态，红色系视觉反馈
Warning	警告状态，橙色系视觉反馈

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	小号（24px）
Middle	中号（默认，32px）
Large	大号（40px）

---

公共属性（StyledProperty）

AddOn 扩展区域属性

属性名	类型	默认值	说明
LeftAddOn	object?	null	前置标签内容（选择器外部左侧），支持文本或控件
LeftAddOnTemplate	IDataTemplate?	null	前置标签的数据模板
RightAddOn	object?	null	后置标签内容（选择器外部右侧），支持文本或控件
RightAddOnTemplate	IDataTemplate?	null	后置标签的数据模板
ContentLeftAddOn	object?	null	内部前缀内容（内容区域左侧），常用于图标
ContentLeftAddOnTemplate	IDataTemplate?	null	内部前缀的数据模板
ContentRightAddOn	object?	null	内部后缀内容（内容区域右侧，手柄左侧）
ContentRightAddOnTemplate	IDataTemplate?	null	内部后缀的数据模板

外观与行为属性

属性名	类型	默认值	说明
SizeType	SizeType	SizeType.Middle	控件尺寸（共享属性，通过 AddOwner 注册）
StyleVariant	InputControlStyleVariant	InputControlStyleVariant.Outline	样式变体（共享属性）
Status	InputControlStatus	InputControlStatus.Default	验证状态（共享属性）
IsAllowClear	bool	false	是否允许清除已选值
OptionFontSize	double	由 Token 控制	下拉选项列表的字体大小
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性）
DropDownDisplayPageSize	int	10	下拉面板最多可见选项数量，超出部分滚动显示

继承自 Avalonia.Controls.ComboBox 的常用属性

属性名	类型	默认值	说明
ItemsSource	IEnumerable?	null	数据源集合，支持绑定任意集合
ItemTemplate	IDataTemplate?	null	项目数据模板，定义每个选项的呈现方式
SelectedItem	object?	null	当前选中项，支持双向绑定
SelectedIndex	int	-1	当前选中项索引
PlaceholderText	string?	null	未选中时显示的占位提示文本
IsDropDownOpen	bool	false	下拉面板是否打开
MaxDropDownHeight	double	自动计算	下拉面板最大高度（由 DropDownDisplayPageSize 自动派生）
ItemsPanel	ItemsPanelTemplate	VirtualizingStackPanel	项目面板模板
IsEnabled	bool	true	是否启用
Width	double	NaN	控件宽度

---

事件

事件名	类型	说明
SelectionChanged	EventHandler<SelectionChangedEventArgs>	选中项变更事件（继承自 SelectingItemsControl）

---

伪类（Pseudo-Classes）

ComboBox 支持以下伪类，可在样式选择器中使用：

伪类	触发条件
:error	Status == InputControlStatus.Error
:warning	Status == InputControlStatus.Warning

继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮
:pressed	控件被按下（非下拉打开状态下）
:disabled	IsEnabled == false
:focus	获得焦点
:focus-visible	通过键盘获得焦点（显示焦点框）

---

实现的接口

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制下拉面板展开/收起动画、ComboBoxItem 背景色过渡动画的开关。

ISizeTypeAware

public SizeType SizeType { get; set; }

支持 Small（24px）、Middle（32px，默认）、Large（40px）三种尺寸。尺寸会同步传递给内部的 AddOnDecoratedBox 和 ComboBoxItem。

IInputControlStatusAware

public InputControlStatus Status { get; set; }

支持 Default、Error、Warning 三种验证状态。状态变更时自动更新对应伪类（:error、:warning）。

IInputControlStyleVariantAware

public InputControlStyleVariant StyleVariant { get; set; }

支持 Outline、Filled、Borderless 三种样式变体。变体会传递给内部的 AddOnDecoratedBox。

IFormItemAware

可作为 FormItem 的子控件参与表单验证流程。ComboBox 提供以下行为：

• 选中项变更时通过 ValueChanged 事件通知 FormItem
• FormItem 验证状态（FormValidateStatus）自动映射为 Status 属性

IFormItemFeedbackAware

可接收并显示表单验证反馈控件（FormValidateFeedback），反馈图标显示在下拉手柄左侧。

---

辅助控件

ComboBoxItem

下拉选项容器，继承自 Avalonia.Controls.ComboBoxItem。

伪类	说明
:pointerover	鼠标悬浮在选项上
:selected	选项被选中
:disabled	选项被禁用

ComboBoxHandle（内部控件）

下拉手柄组件，包含一个 IconButton（DownOutlined 图标）。

属性名	类型	说明
IsMotionEnabled	bool	是否启用动画

事件名	类型	说明
HandleClick	EventHandler<RoutedEventArgs>	手柄被点击