# ListBox 使用指南
本文档展示 `AtomUI.Desktop.Controls.ListBox` 控件的常见使用方式，所有示例均可在 Gallery 应用中找到对应演示。
> 📁 Gallery 演示位置：`controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/ListShowCase.axaml`
---
## 1. 基础用法 — 直接添加项目
最简单的方式是直接在 AXAML 中添加 `ListBoxItem` 子元素：
```xml
Racing car sprays burning fuel into crowd.
Japanese princess to wed commoner.
Australian walks 100km after outback crash.
Man charged over missing wedding girl.
Los Angeles battles huge wildfires.
```
> 参考：`ListShowCase.axaml` 第 89–100 行
---
## 2. 数据绑定 — 使用 ItemsSource
通过 `ItemsSource` 绑定数据集合，配合 `IListItemData` 接口：
```xml
```
**ViewModel 侧数据准备：**
```csharp
using AtomUI.Controls.Data;
// 使用 ListItemData（实现 IListItemData 接口）
viewModel.BasicListBoxItems = [
new ListItemData { Content = "Racing car sprays burning fuel into crowd." },
new ListItemData { Content = "Japanese princess to wed commoner." },
new ListItemData { Content = "Australian walks 100km after outback crash." },
new ListItemData { Content = "Man charged over missing wedding girl." },
new ListItemData { Content = "Los Angeles battles huge wildfires." },
];
```
> 参考：`ListShowCase.axaml` 第 102–108 行，`ListShowCase.axaml.cs` 第 242–266 行
---
## 3. 选中指示器
设置 `IsShowSelectedIndicator="True"` 可在已选中项右侧显示勾选图标：
```xml
```
默认图标为 `CheckOutlined`。
---
## 4. 搜索过滤
通过 `ItemFilterValue` 属性触发过滤，配合 `SearchEdit` 实现搜索功能：
```xml
Racing car sprays burning fuel into crowd.
Japanese princess to wed commoner.
Australian walks 100km after outback crash.
Man charged over missing wedding girl.
Los Angeles battles huge wildfires.
```
**Code-behind：**
```csharp
private void HandleFilterListBoxClicked(object? sender, RoutedEventArgs e)
{
if (sender is SearchEdit searchEdit)
{
SearchListBox.ItemFilterValue = searchEdit.Text?.Trim();
}
}
```
> 参考：`ListShowCase.axaml` 第 110–124 行，`ListShowCase.axaml.cs` 第 305–311 行
### 过滤行为说明
- 当 `ItemFilterValue` 非空时，自动进入过滤模式（`IsFiltering == true`）。
- 默认使用 `DefaultListBoxItemFilter`，基于字符串包含匹配。
- 匹配的文本会根据 `ItemFilterHighlightStrategy` 进行高亮（默认红色）。
- 未匹配的项会被隐藏（当策略包含 `HideUnMatched`）。
- 设置 `ItemFilterValue = null` 可退出过滤模式。
### 自定义过滤器
实现 `IListBoxItemFilter` 接口可自定义过滤逻辑：
```csharp
public class MyCustomFilter : IListBoxItemFilter
{
public bool Filter(ListBox listBox, ListBoxItem listBoxItem, object? filterValue)
{
// 自定义过滤逻辑
var text = listBoxItem.Content?.ToString();
var keyword = filterValue?.ToString();
if (text == null || keyword == null) return false;
return text.StartsWith(keyword, StringComparison.OrdinalIgnoreCase);
}
}
```
```xml
```
---
## 5. 选择模式
ListBox 继承 Avalonia 的 `SelectionMode`，支持多种选择模式：
```xml
```
### 禁用选择
```xml
```
当 `IsSelectable="False"` 时，键盘导航和鼠标点击都不会触发选择。
---
## 6. 尺寸切换
```xml
```
尺寸影响列表项的高度、内边距和圆角。
---
## 7. 无边框模式
在嵌入其他控件内部时，可去除边框：
```xml
```
---
## 8. 空状态指示器
当列表无内容时自动显示空状态（默认开启）：
```xml
```
自定义空状态内容：
```xml
```
---
## 9. 自定义 ItemTemplate
```xml
```
---
## 10. 响应项目点击
```csharp
myListBox.ItemClicked += (sender, args) =>
{
var clickedItem = args.Item;
// 处理点击逻辑
};
```
---
## 11. 监听选择变化
```csharp
myListBox.SelectionChanged += (sender, args) =>
{
var selectedItem = myListBox.SelectedItem;
var selectedIndex = myListBox.SelectedIndex;
// 处理选择变化
};
```
---
## 12. 自定义悬浮/选中背景色
```xml
```
---
## 常见场景
### 作为下拉选项容器
ListBox 可作为 Popup 内的选项列表（多用于自定义下拉组件）：
```xml
```
### 带搜索的选项列表
```xml
```