AtomUI/docs/Desktop.Controls/Cascader/CascaderAPI.md

Cascader API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

CascaderViewExpandTrigger

级联菜单展开触发方式枚举。

值	说明
Click	点击选项展开子级（默认）
Hover	鼠标悬浮在选项上时自动展开子级

TreeSelectCheckedStrategy

多选模式下的选中策略枚举（来自 AtomUI.Controls）。

值	说明
All	显示所有选中的节点（默认）
ShowParent	当所有子节点都被选中时，只显示父节点
ShowChild	只显示叶子节点

TextBlockHighlightStrategy

搜索高亮策略枚举（来自 AtomUI.Controls）。

值	说明
All	高亮所有匹配文本（默认）

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

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

InputControlStatus（来自 AtomUI.Controls）

输入控件状态枚举。

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

InputControlStyleVariant（来自 AtomUI.Controls）

输入控件样式变体枚举。

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

---

Cascader 公共属性（StyledProperty）

Cascader 自身属性

属性名	类型	默认值	说明
IsMultiple	bool	false	是否启用多选模式
ShowCheckedStrategy	TreeSelectCheckedStrategy	All	多选模式下的标签展示策略
OptionsSource	IEnumerable<ICascaderOption>?	null	选项数据源（绑定用）
OptionTemplate	IDataTemplate?	内置 TreeDataTemplate	选项渲染模板
SelectedOption	ICascaderOption?	null	当前选中的单选选项（DirectProperty）
SelectedOptions	IList<ICascaderOption>?	null	当前选中的多选选项列表（DirectProperty）
ExpandIcon	IconTemplate?	RightOutlined	选项展开箭头图标
LoadingIcon	IconTemplate?	LoadingOutlined (Spin)	异步加载时的旋转图标
ExpandTrigger	CascaderViewExpandTrigger	Click	子级菜单展开触发方式
DataLoader	ICascaderItemDataLoader?	null	异步数据加载器
Filter	ICascaderItemFilter?	DefaultCascaderItemFilter	自定义过滤器
FilterHighlightStrategy	TextBlockHighlightStrategy	All	搜索关键词高亮策略
FilterHighlightForeground	IBrush?	CascaderToken.FilterHighlightColor	搜索关键词高亮前景色
DefaultSelectOptionPath	TreeNodePath?	null	默认选中路径（通过 ItemKey 或 Value 匹配）
IsAllowSelectParent	bool	false	是否允许选择非叶子（父）节点
Options	ItemCollection	空集合	直接在 AXAML 中声明的选项集合（[Content] 属性）

继承自 AbstractSelect 的常用属性

属性名	类型	默认值	说明
IsAllowClear	bool	false	是否显示清除按钮
IsDropDownOpen	bool	false	下拉面板是否打开
PlaceholderText	string?	null	占位文本
PlaceholderForeground	IBrush?	ColorTextPlaceholder	占位文本颜色
IsFilterEnabled	bool	false	是否启用搜索过滤
IsPopupMatchSelectWidth	bool	true	弹出面板是否匹配选择框宽度
MaxCount	int	int.MaxValue	多选模式下最大选择数量
IsShowMaxCountIndicator	bool	false	是否显示最大数量指示器
MaxTagCount	int?	null	多选标签最大显示数量
IsResponsiveTagMode	bool	false	是否启用响应式标签模式
SizeType	SizeType	Middle	控件尺寸
StyleVariant	InputControlStyleVariant	Outline	样式变体
Status	InputControlStatus	Default	输入控件状态
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画
LeftAddOn	object?	null	左侧附加内容
RightAddOn	object?	null	右侧附加内容
ContentLeftAddOn	object?	null	内容区左侧附加内容（前缀图标）
ContentRightAddOn	object?	null	内容区右侧附加内容
SuffixIcon	PathIcon?	内置下拉箭头	后缀图标
PopupPlacement	SelectPopupPlacement	BottomEdgeAlignedLeft	弹出面板位置
MaxPopupHeight	double	CascaderToken.DropdownHeight	弹出面板最大高度
IsEnabled	bool	true	是否启用

---

公共方法

方法名	返回类型	说明
Clear()	void	清除所有选中值（SelectedOption、SelectedOptions、SelectedOptionPath）

---

事件

Cascader 本身不直接公开自定义事件，但其内部 CascaderView 提供以下事件：

事件名	事件参数类型	说明
SelectedOptionsChanged	CascaderOptionsSelectedChangedEventArgs	多选选中项发生变化
ItemClicked	CascaderItemClickedEventArgs	选项项被点击
ItemDoubleClicked	CascaderItemDoubleClickedEventArgs	选项项被双击
OptionSelected	CascaderOptionSelectedEventArgs	选项被选中
ItemExpanded	CascaderItemExpandedEventArgs	选项项被展开
ItemCollapsed	CascaderItemCollapsedEventArgs	选项项被折叠
ItemAsyncLoaded	CascaderViewItemLoadedEventArgs	异步加载完成

通常通过属性变化回调（SelectedOptionProperty.Changed、SelectedOptionsProperty.Changed）监听选中值的变化。

---

伪类（Pseudo-Classes）

CascaderViewItem 伪类

伪类	常量	触发条件
:checked	CascaderViewPseudoClass.NodeToggleTypeCheckBox	多选模式下，选项的复选框类型激活
:pressed	StdPseudoClass.Pressed	选项项被按下
:expanded	StdPseudoClass.Expanded	选项项已展开（有子级可见）
:selected	StdPseudoClass.Selected	选项项被选中

Cascader 继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮
:pressed	控件被按下
:disabled	IsEnabled == false
:focus	获得焦点
:dropdown-open	下拉面板打开

---

接口定义

ICascaderOption

级联选项数据接口，继承自 ITreeNode<ICascaderOption>。

public interface ICascaderOption : ITreeNode<ICascaderOption>
{
    object? Header { get; set; }       // 显示文本
    bool? IsChecked { get; set; }      // 复选状态（多选模式）
    bool IsCheckBoxEnabled { get; set; } // 复选框是否可用
    bool IsExpanded { get; set; }      // 是否展开
    bool IsLeaf { get; set; }         // 是否为叶子节点
    object? Value { get; set; }        // 选项值
}

CascaderOption

ICascaderOption 的默认实现（record 类），可直接在 AXAML 中使用。

属性	类型	默认值	说明
Header	object?	null	显示文本
Value	object?	null	选项值
ItemKey	EntityKey?	null	选项唯一标识（用于路径匹配）
Icon	PathIcon?	null	选项图标
IsEnabled	bool	true	是否可用
IsChecked	bool?	false	复选状态
IsLeaf	bool	false	是否为叶子节点
IsExpanded	bool	false	是否展开
IsCheckBoxEnabled	bool	true	复选框是否可用
Children	IList<ICascaderOption>	空列表	子选项列表

ICascaderItemFilter

自定义过滤接口。

public interface ICascaderItemFilter
{
    bool Filter(CascaderView cascaderView, ICascaderItemInfo cascaderItemInfo, object? filterValue);
}

ICascaderItemDataLoader

异步数据加载接口。

public interface ICascaderItemDataLoader
{
    Task<CascaderItemLoadResult> LoadAsync(ICascaderOption targetNode, CancellationToken token);
}

---

实现的接口

ISizeTypeAware（通过 AbstractSelect）

public SizeType SizeType { get; set; }

IMotionAwareControl（通过 AbstractSelect）

public bool IsMotionEnabled { get; set; }

ICompactSpaceAware（通过 AbstractSelect）

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

IInputControlStatusAware（通过 AbstractSelect）

public InputControlStatus Status { get; set; }

IInputControlStyleVariantAware（通过 AbstractSelect）

public InputControlStyleVariant StyleVariant { get; set; }

IFormItemAware（通过 AbstractSelect）

可作为 FormItem 的子控件参与表单验证流程。支持通过 NotifySetFormValue / NotifyGetFormValue / NotifyClearFormValue 进行表单值的读写和清除。