AtomUI/docs/Desktop.Controls/Select/SelectAPI.md

Select API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

SelectMode

选择模式枚举，定义 Select 的选择行为。

值	说明
Single	单选模式，选中后下拉自动关闭
Multiple	多选模式，已选项以标签形式展示
Tags	标签模式，在多选基础上允许自由输入创建新标签

SelectPopupPlacement

下拉弹出面板的位置枚举。

值	说明
TopEdgeAlignedLeft	上方弹出，左对齐
TopEdgeAlignedRight	上方弹出，右对齐
BottomEdgeAlignedLeft	下方弹出，左对齐（默认）
BottomEdgeAlignedRight	下方弹出，右对齐

InputControlStyleVariant（来自 AtomUI.Controls）

输入控件样式变体枚举。

值	说明
Outline	有边框轮廓（默认）
Filled	填充背景
Borderless	无边框

InputControlStatus（来自 AtomUI.Controls）

输入控件验证状态枚举。

值	说明
Default	默认状态
Error	错误状态（红色边框）
Warning	警告状态（橙色边框）

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	小号
Middle	中号（默认）
Large	大号

---

核心数据类型

ISelectOption 接口

选项数据接口，继承自 IListItemData。

public interface ISelectOption : IListItemData
{
    object? Header { get; }        // 选项显示文本
    bool IsDynamicAdded { get; }   // 是否为 Tags 模式动态添加的选项
}

SelectOption 记录类

内置的 ISelectOption 实现，支持分组。

public record SelectOption : ListItemData, ISelectOption, IGroupListItemData
{
    public object? Header { get; init; }
    public bool IsDynamicAdded { get; init; } = false;
}

ListItemData 基类提供的关键属性：

属性	类型	说明
Content	object?	选项的值（用于匹配和提交）
IsEnabled	bool	是否可选
Group	string?	分组名称（配合 IsGroupEnabled 使用）

ISelectOptionsAsyncLoader 接口

异步选项加载器接口。

public interface ISelectOptionsAsyncLoader
{
    Task<SelectOptionsLoadResult> LoadAsync(object? context, CancellationToken token);
}

SelectOptionsLoadResult

异步加载结果。

属性	类型	说明
IsSuccess	bool	加载是否成功
StatusCode	RpcStatusCode	状态码
UserFriendlyMessage	string?	用户友好的错误信息
Data	IReadOnlyList<ISelectOption>?	加载到的选项数据

SelectSelectionChangedEventArgs

选择变更事件参数。

属性	类型	说明
Mode	SelectMode	当前选择模式
OldValue	object?	变更前的值
NewValue	object?	变更后的值

ISelectTagTextProvider 接口

自定义标签文本提供器接口。

public interface ISelectTagTextProvider
{
    string? TagText { get; }
}

---

AbstractSelect 公共属性

以下属性定义在 AbstractSelect 基类中，Select 自动继承。

基础行为属性

属性名	类型	默认值	说明
IsAllowClear	bool	false	是否显示清除按钮，允许一键清空已选值
IsAutoClearSearchValue	bool	false	选中选项后是否自动清除搜索文本
IsDefaultOpen	bool	false	初始渲染时是否默认展开下拉
IsDropDownOpen	bool	false	控制下拉面板的展开/关闭状态
IsFilterEnabled	bool	false	是否启用搜索过滤功能
IsPopupMatchSelectWidth	bool	true	下拉面板宽度是否与 Select 控件等宽
DisplayPageSize	int	10	下拉面板最多可见的选项条数（控制最大高度）
Placement	SelectPopupPlacement	BottomEdgeAlignedLeft	下拉面板弹出位置
FilterValue	object?	null	当前搜索过滤值

占位文本属性

属性名	类型	默认值	说明
PlaceholderText	string?	null	未选中时显示的占位提示文本
PlaceholderForeground	IBrush?	由 Token 控制	占位文本颜色

多选标签属性

属性名	类型	默认值	说明
MaxCount	int	int.MaxValue	最大可选数量限制
IsShowMaxCountIndicator	bool	false	是否显示最大选择数指示器（如 2/5）
MaxTagCount	int?	null	最多显示的标签数量，超出折叠为 +N
IsResponsiveTagMode	bool	false	根据控件宽度自动计算可见标签数
MaxTagPlaceholder	string?	null	标签折叠后的自定义占位文本

图标属性

属性名	类型	默认值	说明
ClearIcon	PathIcon?	null	自定义清除图标
SuffixIcon	PathIcon?	DownOutlined	下拉箭头图标
SuffixLoadingIcon	PathIcon?	LoadingOutlined（旋转）	加载中图标

样式与状态属性

属性名	类型	默认值	说明
StyleVariant	InputControlStyleVariant	Outline	样式变体（Outlined/Filled/Borderless）
Status	InputControlStatus	Default	验证状态（Default/Error/Warning）
SizeType	SizeType	Middle	控件尺寸
IsMotionEnabled	bool	跟随全局 Token	是否启用动画效果

AddOn 装饰属性

属性名	类型	默认值	说明
LeftAddOn	object?	null	左侧外部附加内容
LeftAddOnTemplate	IDataTemplate?	null	左侧外部附加内容模板
RightAddOn	object?	null	右侧外部附加内容
RightAddOnTemplate	IDataTemplate?	null	右侧外部附加内容模板
ContentLeftAddOn	object?	null	左侧内部前缀内容（如文本 "User"）
ContentLeftAddOnTemplate	IDataTemplate?	null	左侧内部前缀内容模板
ContentRightAddOn	object?	null	右侧内部后缀内容
ContentRightAddOnTemplate	IDataTemplate?	null	右侧内部后缀内容模板

空状态指示属性

属性名	类型	默认值	说明
EmptyIndicator	object?	null	空状态指示器内容
EmptyIndicatorTemplate	IDataTemplate?	null	空状态指示器模板
IsShowEmptyIndicator	bool	true	是否在选项为空时显示空状态指示器
EmptyIndicatorPadding	Thickness	默认值	空状态指示器内边距

只读属性

属性名	类型	说明
IsLoading	bool	是否正在异步加载选项（只读）

---

Select 公共属性

以下属性定义在 Select 类中（继承 AbstractSelect）。

核心属性

属性名	类型	默认值	说明
Mode	SelectMode	Single	选择模式：Single / Multiple / Tags
OptionsSource	IEnumerable<ISelectOption>?	null	绑定的选项数据源
OptionTemplate	IDataTemplate?	默认显示 Header	自定义选项渲染模板
OptionFontSize	double	由 Token 控制	选项字体大小
IsDefaultActiveFirstOption	bool	false	是否默认激活第一个选项
IsGroupEnabled	bool	false	是否启用选项分组
GroupPropertySelector	DefaultFilterValueSelector?	null	分组属性提取函数
IsHideSelectedOptions	bool	false	多选时是否隐藏已选选项
AutoScrollToSelectedOptions	bool	false	展开时是否自动滚动到已选选项

选中值属性

属性名	类型	说明
SelectedOption	ISelectOption?	单选模式下的已选选项（DirectProperty，支持双向绑定）
SelectedOptions	IList<ISelectOption>?	多选/标签模式下的已选选项列表（DirectProperty）
Options	ItemCollection	选项集合（[Content] 属性，支持 AXAML 直接声明子元素）

搜索过滤属性

属性名	类型	默认值	说明
Filter	IValueFilter?	null	自定义过滤器实现
FilterValueSelector	DefaultFilterValueSelector?	HeaderFilterPropertySelector	过滤值提取函数

异步加载属性

属性名	类型	默认值	说明
OptionsLoader	ISelectOptionsAsyncLoader?	null	异步选项加载器
OptionsAsyncLoadContext	object?	null	传递给加载器的上下文对象

默认值属性

属性名	类型	说明
DefaultValues	IList<object>?	默认选中值列表（通过 Content 值匹配）
DefaultValueCompareFn	Func<object, ISelectOption, bool>?	自定义默认值比较函数

---

事件

AbstractSelect 事件

事件名	类型	说明
DropDownOpening	EventHandler<CancelEventArgs>	下拉即将展开（可取消）
DropDownOpened	EventHandler	下拉已展开
DropDownClosing	EventHandler<CancelEventArgs>	下拉即将关闭（可取消）
DropDownClosed	EventHandler	下拉已关闭

Select 事件

事件名	类型	说明
SelectionChanged	EventHandler<SelectSelectionChangedEventArgs>	选中值变更
OptionsLoading	EventHandler<SelectOptionsLoadingEventArgs>	异步加载开始（可取消）
OptionsLoaded	EventHandler<SelectOptionsLoadedEventArgs>	异步加载完成

---

公共方法

方法名	返回值	说明
ClearValue()	void	清空所有已选值（SelectedOption 和 SelectedOptions）

---

伪类（Pseudo-Classes）

伪类	常量	触发条件
:dropdownopen	SelectPseudoClass.DropdownOpen	下拉面板处于打开状态
:error	StdPseudoClass.Error	Status == InputControlStatus.Error
:warning	StdPseudoClass.Warning	Status == InputControlStatus.Warning
:outline	AddOnDecoratedBoxPseudoClass.Outline	StyleVariant == Outline
:filled	AddOnDecoratedBoxPseudoClass.Filled	StyleVariant == Filled
:borderless	AddOnDecoratedBoxPseudoClass.Borderless	StyleVariant == Borderless

继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮
:pressed	控件按下
:disabled	IsEnabled == false
:focus	获得焦点

---

实现的接口

ISizeTypeAware

public SizeType SizeType { get; set; }

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

IInputControlStatusAware

public InputControlStatus Status { get; set; }

IInputControlStyleVariantAware

public InputControlStyleVariant StyleVariant { get; set; }

ICompactSpaceAware

在 Space.Compact 容器中使用时自动调整圆角和边框。根据在紧凑空间中的位置自动裁剪圆角。

IFormItemAware

可作为 FormItem 的子控件参与表单验证流程。支持 SetFormValue / GetFormValue / ClearFormValue / NotifyValidateStatus。

IFormItemFeedbackAware

接收表单验证反馈控件（如错误图标、警告图标），并在 SelectHandle 区域展示。

---

静态字段

字段名	类型	说明
HeaderFilterPropertySelector	DefaultFilterValueSelector	按 Header 属性过滤的默认提取函数
ValueFilterPropertySelector	DefaultFilterValueSelector	按 Content 属性过滤的提取函数