AtomUI/docs/Desktop.Controls/SplitButton/SplitButtonAPI.md

SplitButton API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

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

FlyoutTriggerType（来自 AtomUI.Controls）

弹出菜单触发方式枚举。

值	说明
Click	点击触发（默认）
Hover	鼠标悬浮触发

PlacementMode（来自 Avalonia.Controls.Primitives.PopupPositioning）

弹出层位置模式枚举。SplitButton 默认使用 BottomEdgeAlignedRight。

常用值	说明
Bottom	下方居中
BottomEdgeAlignedLeft	下方左对齐
BottomEdgeAlignedRight	下方右对齐（SplitButton 默认值）
Top	上方居中
TopEdgeAlignedLeft	上方左对齐
TopEdgeAlignedRight	上方右对齐

---

公共属性（StyledProperty）

SplitButton 自身属性

属性名	类型	默认值	说明
Flyout	Flyout?	null	下拉菜单弹出层（支持 MenuFlyout），由右侧按钮触发
TriggerType	FlyoutTriggerType	Click	Flyout 触发方式（Click / Hover）
IsShowArrow	bool	false	弹出菜单是否显示指示箭头
IsPointAtCenter	bool	false	箭头是否指向触发元素中心
Placement	PlacementMode	BottomEdgeAlignedRight	Flyout 弹出位置
PlacementAnchor	PopupAnchor	默认值	Flyout 弹出锚点
PlacementGravity	PopupGravity	默认值	Flyout 弹出重力方向
GutterToFlyout	double	由 Token 控制	弹出层与按钮之间的间距
MouseEnterDelay	int	默认值	悬浮触发延迟（毫秒），仅 TriggerType=Hover 时生效
MouseLeaveDelay	int	默认值	离开关闭延迟（毫秒），仅 TriggerType=Hover 时生效
IsPrimaryButtonType	bool	false	是否使用 Primary 按钮样式（蓝色背景），false 时使用 Default 样式（白色背景 + 边框）
IsDanger	bool	false	危险按钮样式，启用后两个内部按钮使用红色系
Icon	PathIcon?	null	主按钮图标，使用 Ant Design 图标集
OpenIndicator	PathIcon?	EllipsisOutlined	下拉按钮图标，默认为省略号图标
SizeType	SizeType	SizeType.Middle	按钮尺寸（共享属性，通过 AddOwner 注册）
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性）
IsWaveSpiritEnabled	bool	跟随全局 Token	是否启用点击波纹效果（共享属性）

ICommandSource 接口属性

属性名	类型	默认值	说明
Command	ICommand?	null	主按钮点击命令，CanExecute 为 false 时自动禁用整个 SplitButton
CommandParameter	object?	null	命令参数
HotKey	KeyGesture?	null	键盘快捷键，触发主按钮点击

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

属性名	类型	默认值	说明
Content	object?	null	主按钮文本内容
ContentTemplate	IDataTemplate?	null	内容模板
HorizontalAlignment	HorizontalAlignment	Left	水平对齐
VerticalAlignment	VerticalAlignment	Top	垂直对齐
IsEnabled	bool	true	是否启用（同时受 Command.CanExecute 控制）
Foreground	IBrush?	由主题控制	前景色
Background	IBrush?	由主题控制	背景色
BorderBrush	IBrush?	由 Token 控制	边框颜色（SharedToken.ColorBorder）
BorderThickness	Thickness	由 Token 控制	边框粗细（SharedToken.BorderThickness）
CornerRadius	CornerRadius	由 Token 控制	圆角半径（根据 SizeType 自动设置）

---

事件

事件名	类型	说明
Click	EventHandler<RoutedEventArgs>	主按钮（左侧）被点击时触发，路由策略为 Bubble

重要提示：Click 事件仅在点击左侧主按钮时触发。点击右侧下拉按钮会打开 Flyout，不会触发 Click 事件。内部主按钮的 Click 事件会被标记为 Handled，防止冒泡到外部。

---

伪类（Pseudo-Classes）

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

伪类	触发条件
:flyout-open	Flyout 处于打开状态
:pressed	主按钮被按下（键盘 Space/Enter 触发）
:checked	选中状态（用于 ToggleSplitButton 派生类）
:disabled	IsEnabled == false 或 Command.CanExecute == false
:pointerover	鼠标悬浮在控件上
:focus	获得焦点
:focus-visible	通过键盘（Tab 键）获得焦点

---

实现的接口

ICommandSource

public ICommand? Command { get; set; }
public object? CommandParameter { get; set; }

支持 MVVM 命令绑定。当 Command.CanExecute 返回 false 时，SplitButton 自动禁用（灰色调 + 不可点击）。

ISizeTypeAware

public SizeType SizeType { get; set; }

支持 Large / Middle / Small 三种尺寸，两个内部 Button 同步尺寸。

IWaveSpiritAwareControl

public bool IsWaveSpiritEnabled { get; set; }

控制内部 Button 的点击波纹效果开关。

ICompactSpaceAware

在 Space.Compact 容器中使用时自动调整圆角。SplitButton 提供以下行为：

• 根据在紧凑空间中的位置自动裁剪外部圆角
• 将裁剪后的圆角重新分配给左右两个内部 Button
• 返回边框厚度供容器计算相邻控件间距

---

键盘交互

按键	行为
Space / Enter	触发主按钮点击（Click 事件 + Command 执行）
Alt+Down	打开 Flyout（需非 XY 导航模式）
F4	打开 Flyout
Escape	关闭 Flyout（当 Flyout 无可聚焦内容时）

---

内部属性（Internal）

以下属性为内部使用，不作为公共 API：

属性名	类型	说明
SplitSeparatorBrush	IBrush?	Primary 模式下分隔线画刷
EffectiveButtonType	ButtonType	内部 Button 的实际类型（由 IsPrimaryButtonType 驱动）
CompactSpaceItemPosition	SpaceItemPosition?	紧凑空间中的位置
CompactSpaceOrientation	Orientation	紧凑空间方向
IsUsedInCompactSpace	bool	是否处于紧凑空间中