AtomUI/docs/Desktop.Controls/ListBox/ListBoxAPI.md

ListBox API 参考

命名空间

namespace AtomUI.Desktop.Controls;

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

---

枚举类型

TextBlockHighlightStrategy（Flags 枚举）

过滤高亮策略，可组合使用。

值	十六进制	说明
HighlightedMatch	0x01	高亮匹配的文本片段
HighlightedWhole	0x02	高亮整个文本
BoldedMatch	0x04	加粗匹配的文本片段
HideUnMatched	0x08	隐藏未匹配的列表项
All	0x0D	HighlightedMatch | BoldedMatch | HideUnMatched

SizeType（来自 AtomUI.Controls）

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

---

ListBox

AtomUI.Desktop.Controls.ListBox 继承自 Avalonia.Controls.ListBox，通过 using AvaloniaListBox = Avalonia.Controls.ListBox; 别名引用。

公共属性（StyledProperty）

属性名	类型	默认值	说明
IsSelectable	bool	true	是否允许选择项目（false 时禁用选择，纯展示模式）
SizeType	SizeType	Middle	列表尺寸（共享属性，通过 AddOwner 注册）
IsBorderless	bool	false	是否无边框模式（嵌入其他控件时使用）
ItemHoverBg	IBrush?	由 Token 控制	列表项悬浮态背景色
ItemSelectedBg	IBrush?	由 Token 控制	列表项选中态背景色
IsShowSelectedIndicator	bool	false	是否显示选中指示器（勾选图标）
SelectedIndicator	IconTemplate?	CheckOutlined	选中指示器图标模板
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画
EmptyIndicatorPadding	Thickness	由 Token 控制	空状态指示器内边距
EmptyIndicator	object?	null	空状态指示器内容
EmptyIndicatorTemplate	IDataTemplate?	Empty(Simple)	空状态指示器数据模板（默认为 Simple Empty 控件）
IsShowEmptyIndicator	bool	true	是否在列表为空时显示空状态指示器
ItemFilter	IListBoxItemFilter?	DefaultListBoxItemFilter	项目过滤器（默认为字符串包含匹配）
ItemFilterValue	object?	null	过滤关键字（设置后触发过滤）
ItemFilterHighlightStrategy	TextBlockHighlightStrategy	All	过滤高亮策略
FilterHighlightForeground	IBrush?	由 Token 控制	过滤高亮文本前景色

只读属性（DirectProperty）

属性名	类型	说明
FilterResultCount	int	过滤匹配结果数量（只读）
IsFiltering	bool	是否正在过滤（当 ItemFilter 和 ItemFilterValue 都非空时为 true，只读）

继承自 Avalonia ListBox 的常用属性

属性名	类型	默认值	说明
Items	ItemCollection	空集合	项目集合（直接添加）
ItemsSource	IEnumerable?	null	数据源绑定
ItemTemplate	IDataTemplate?	自定义（见主题）	项目数据模板
ItemsPanel	ITemplate<Panel>?	StackPanel	项目面板模板
SelectedItem	object?	null	当前选中的项目
SelectedIndex	int	-1	当前选中的索引
SelectedItems	IList?	null	多选时的选中项集合
SelectionMode	SelectionMode	Single	选择模式（Single / Multiple / Toggle / AlwaysSelected）
ItemCount	int	0	项目总数（只读）
WrapSelection	bool	false	键盘导航到末尾时是否循环
Background	IBrush?	—	背景色
BorderBrush	IBrush?	由 Token 控制	边框颜色
BorderThickness	Thickness	由 Token 控制	边框粗细
CornerRadius	CornerRadius	由 Token 控制	圆角半径
Padding	Thickness	由 Token 控制	内边距

事件

事件名	类型	说明
ItemClicked	EventHandler<ListBoxItemClickedEventArgs>	列表项被点击时触发（CLR 事件）
ItemCountChanged	EventHandler<ItemCountChangedEventArgs>	列表项目数量变化时触发（CLR 事件）
SelectionChanged	EventHandler<SelectionChangedEventArgs>	选择变化时触发（继承自 Avalonia）

实现的接口

接口	说明
ISizeTypeAware	支持三种尺寸切换
IMotionAwareControl	支持动画开关
IListVirtualizingContextAware	虚拟化上下文管理

---

ListBoxItem

AtomUI.Desktop.Controls.ListBoxItem 继承自 Avalonia.Controls.ListBoxItem，是 ListBox 中每个选项的容器控件。

⚠️ ListBoxItem 的大部分扩展属性为 internal，由 ListBox 在 PrepareContainerForItemOverride 中自动传递。通常不需要手动设置。

公共事件

事件名	类型	路由策略	说明
Clicked	EventHandler<RoutedEventArgs>	Bubble	列表项左键点击时触发

继承自 Avalonia ListBoxItem 的常用属性

属性名	类型	默认值	说明
Content	object?	null	列表项内容
ContentTemplate	IDataTemplate?	null	内容数据模板
IsSelected	bool	false	是否选中
IsEnabled	bool	true	是否启用
Foreground	IBrush?	由 Token 控制	文本前景色
Background	IBrush?	由 Token 控制	背景色
Padding	Thickness	由 Token 控制	内边距
CornerRadius	CornerRadius	由 Token 控制	圆角半径

伪类（Pseudo-Classes）

伪类	触发条件
:selected	IsSelected == true
:pointerover	鼠标悬浮
:disabled	IsEnabled == false

---

辅助类型

ListBoxItemClickedEventArgs

public class ListBoxItemClickedEventArgs : EventArgs
{
    public ListBoxItem Item { get; }
}

IListBoxItemFilter

过滤器接口，允许自定义过滤逻辑。

public interface IListBoxItemFilter
{
    bool Filter(ListBox listBox, ListBoxItem listBoxItem, object? filterValue);
}

DefaultListBoxItemFilter

默认过滤器实现，基于字符串包含匹配。

public class DefaultListBoxItemFilter : IListBoxItemFilter
{
    public DefaultListBoxItemFilter(ValueFilterMode filterMode = ValueFilterMode.Contains);
    public bool Filter(ListBox listBox, ListBoxItem listBoxItem, object? filterValue);
}

IListItemData（来自 AtomUI.Controls.Shared）

列表数据项的标准接口。当 ItemsSource 中的数据实现此接口时，ListBox 能自动提取内容文本用于过滤和高亮。

ItemCountChangedEventArgs（来自 AtomUI.Controls.Shared）

public class ItemCountChangedEventArgs : EventArgs
{
    public int ItemCount { get; }
}