AtomUI/docs/Desktop.Controls/TreeSelect/TreeSelectAPI.md

TreeSelect API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

TreeSelectCheckedStrategy

勾选策略枚举（[Flags]），控制勾选模式下选中项的展示策略。

值	说明
ShowParent (0x1)	当所有子节点都被勾选时，仅展示父节点
ShowChild (0x2)	仅展示被勾选的叶子节点
All (ShowParent | ShowChild)	展示所有被勾选的节点（默认值）

InputControlStyleVariant（来自 AtomUI.Controls）

输入控件样式变体枚举。

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

InputControlStatus（来自 AtomUI.Controls）

输入控件状态枚举。

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

SelectPopupPlacement

弹窗位置枚举。

值	说明
BottomEdgeAlignedLeft	底部左对齐（默认）
BottomEdgeAlignedRight	底部右对齐
TopEdgeAlignedLeft	顶部左对齐
TopEdgeAlignedRight	顶部右对齐

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

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

TreeFilterHighlightStrategy（来自 AtomUI.Controls）

树筛选高亮策略枚举（[Flags]）。

值	说明
HighlightedWhole	高亮匹配项整行
BoldedMatch	加粗匹配文字
ExpandPath	展开匹配项的路径
HideUnMatched	隐藏不匹配的节点

---

公共属性（TreeSelect 自有）

属性名	类型	默认值	说明
ShowCheckedStrategy	TreeSelectCheckedStrategy	All	勾选模式下，控制选中项在选择框中的展示策略
AutoScrollToSelectedItem	bool	true	打开下拉时是否自动滚动到选中项
IsShowIcon	bool	false	是否显示节点图标
IsShowLeafIcon	bool	false	是否显示叶子节点图标
IsShowLine	bool	false	是否在 TreeView 中显示连接线
IsTreeCheckable	bool	false	是否启用 Checkbox 勾选模式（设为 true 会自动将 IsMultiple 设为 true）
IsMultiple	bool	false	是否启用多选模式
IsDefaultExpandAll	bool	false	是否默认展开所有节点
IsShowTreeLine	bool	false	是否显示树形连接线
IsSwitcherRotation	bool	false	展开/折叠按钮是否使用旋转动画（而非切换图标）
IsTreeCheckStrictly	bool	false	严格勾选模式，父子节点勾选互不关联
TreeDefaultExpandedPaths	IList<TreeNodePath>?	null	默认展开的节点路径列表
ItemsSource	IEnumerable<ITreeItemNode>?	null	树形数据源
ItemTemplate	IDataTemplate?	内置 TreeDataTemplate	自定义节点渲染模板
DataLoader	ITreeItemNodeLoader?	null	异步加载器，用于按需加载子节点
Filter	ITreeItemFilter?	DefaultTreeItemFilter	搜索筛选器
FilterHighlightStrategy	TreeFilterHighlightStrategy	HighlightedWhole | BoldedMatch | ExpandPath | HideUnMatched	筛选高亮策略
FilterHighlightForeground	IBrush?	ColorPrimary	筛选匹配文字高亮颜色
SelectedItem	ITreeItemNode?	null	当前选中项（单选模式）
SelectedItems	IList<ITreeItemNode>?	null	当前选中项列表（多选/勾选模式）
Items	ItemCollection	空集合	直接操作的树节点集合（[Content] 属性）

---

继承自 AbstractSelect 的公共属性

属性名	类型	默认值	说明
IsAllowClear	bool	false	是否显示清除按钮
IsAutoClearSearchValue	bool	false	选中后是否自动清空搜索框
IsDefaultOpen	bool	false	是否默认展开下拉弹窗
IsDropDownOpen	bool	false	下拉弹窗是否打开
PlaceholderText	string?	null	未选择时的占位提示文本
PlaceholderForeground	IBrush?	ColorTextPlaceholder	占位文本颜色
IsPopupMatchSelectWidth	bool	true	弹窗宽度是否匹配选择框宽度
IsFilterEnabled	bool	false	是否启用搜索筛选
DisplayPageSize	int	10	弹窗中可见的选项数量（影响弹窗最大高度）
MaxCount	int	int.MaxValue	最大可选数量（多选模式）
IsShowMaxCountIndicator	bool	false	是否显示已选/最大数量指示器
MaxTagCount	int?	null	多选模式下最大显示的 Tag 数量
IsResponsiveTagMode	bool	false	是否启用响应式 Tag 模式
MaxTagPlaceholder	string?	null	响应式模式下 Tag 被隐藏后显示的替代文本
LeftAddOn	object?	null	左侧附加内容（AddOn 区域）
LeftAddOnTemplate	IDataTemplate?	null	左侧附加内容模板
RightAddOn	object?	null	右侧附加内容
RightAddOnTemplate	IDataTemplate?	null	右侧附加内容模板
ContentLeftAddOn	object?	null	内容区域左侧附加内容（前缀）
ContentLeftAddOnTemplate	IDataTemplate?	null	内容区域左侧附加内容模板
ContentRightAddOn	object?	null	内容区域右侧附加内容
ContentRightAddOnTemplate	IDataTemplate?	null	内容区域右侧附加内容模板
StyleVariant	InputControlStyleVariant	Outline	样式变体（Outline / Filled / Borderless / Underlined）
Status	InputControlStatus	Default	验证状态（Default / Error / Warning）
Placement	SelectPopupPlacement	BottomEdgeAlignedLeft	弹窗弹出位置
FilterValue	object?	null	当前搜索筛选值
ClearIcon	PathIcon?	null	自定义清除按钮图标
SuffixIcon	PathIcon?	DownOutlined	下拉箭头图标
SuffixLoadingIcon	PathIcon?	LoadingOutlined（旋转）	加载状态图标
IsMotionEnabled	bool	跟随全局 Token	是否启用弹窗展开/收起动画
SizeType	SizeType	SizeType.Middle	控件尺寸
EmptyIndicator	object?	null	空状态指示器内容
EmptyIndicatorTemplate	IDataTemplate?	null	空状态指示器模板
IsShowEmptyIndicator	bool	true	是否显示空状态指示器
EmptyIndicatorPadding	Thickness	default	空状态指示器内边距
IsLoading	bool	false	是否处于加载状态（只读）

---

公共方法

方法名	返回类型	说明
Clear()	void	清空所有选中项（同时清空 SelectedItem 和 SelectedItems）

---

事件

事件名	类型	说明
DropDownOpening	EventHandler<CancelEventArgs>	下拉弹窗即将打开时触发，可通过 Cancel = true 阻止打开
DropDownOpened	EventHandler	下拉弹窗已打开后触发
DropDownClosing	EventHandler<CancelEventArgs>	下拉弹窗即将关闭时触发，可通过 Cancel = true 阻止关闭
DropDownClosed	EventHandler	下拉弹窗已关闭后触发

---

伪类（Pseudo-Classes）

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

Select 共享伪类

伪类	常量	触发条件
:dropdownopen	SelectPseudoClass.DropdownOpen	下拉弹窗处于打开状态

从 AddOnDecoratedBox 继承的样式变体伪类

伪类	触发条件
:outline	StyleVariant == Outline
:filled	StyleVariant == Filled
:borderless	StyleVariant == Borderless

标准伪类

伪类	触发条件
:pressed	控件被按下（鼠标按住未释放）
:disabled	IsEnabled == false
:focus-within	控件或其子控件获得焦点
:error	Status == Error
:warning	Status == Warning

---

实现的接口

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制弹窗展开/收起动画是否启用。

ISizeTypeAware

public SizeType SizeType { get; set; }

支持 Small / Middle / Large 三种尺寸。

IInputControlStatusAware

public InputControlStatus Status { get; set; }

支持 Default / Error / Warning 三种验证状态。

IInputControlStyleVariantAware

public InputControlStyleVariant StyleVariant { get; set; }

支持 Outline / Filled / Borderless / Underlined 四种样式变体。

ICompactSpaceAware

在 Space.Compact 容器中使用时自动调整圆角和边框。

IFormItemAware

可作为 FormItem 的子控件参与表单验证流程。TreeSelect 实现了 SetFormValue / GetFormValue / ClearFormValue：

• 单选模式：表单值为 ITreeItemNode?
• 多选模式：表单值为 IList<ITreeItemNode>?

IFormItemFeedbackAware

支持表单验证反馈控件展示（如错误/警告图标）。