# ComboBox 使用文档本文档介绍 AtomUI ComboBox 控件的各种使用方式，示例代码摘自 Gallery 演示程序。 > 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` --- ## 前置准备在 AXAML 中使用 ComboBox，需要引入以下命名空间： ```xml xmlns:atom="https://atomui.net" xmlns:antdicons="https://atomui.net/icons/antdesign" ``` 在 C# 代码中引入： ```csharp using AtomUI.Desktop.Controls; // ComboBox, ComboBoxItem 控件 using AtomUI.Controls; // SizeType, InputControlStyleVariant 等共享类型 ``` --- ## 1. 基本用法最简单的 ComboBox 使用方式——直接在 AXAML 中声明 `ComboBoxItem` 子项： ```xml 床前明月光疑是地上霜举头望明月低头思故乡 ``` --- ## 2. 通过 ItemsSource + ItemTemplate 绑定数据当选项来自 ViewModel 数据源时，使用 `ItemsSource` 绑定集合，`ItemTemplate` 定义选项模板： ```xml ``` ```csharp // ViewModel public class ComboBoxViewModel : ReactiveObject { private List? _comboBoxItems = []; public List? ComboBoxItems { get => _comboBoxItems; set => this.RaiseAndSetIfChanged(ref _comboBoxItems, value); } } public class ComboBoxItemData { public string Text { get; set; } = string.Empty; } ``` ```csharp // Code-behind：初始化数据 private void InitComboBoxItems(ComboBoxViewModel viewModel) { var items = new List { new() { Text = "床前明月光" }, new() { Text = "疑是地上霜" }, new() { Text = "举头望明月" }, new() { Text = "低头思故乡" }, }; viewModel.ComboBoxItems = items; } ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "Generate ComboBoxItem by ItemsSource" 示例。 --- ## 3. 禁用状态通过 `IsEnabled="False"` 禁用 ComboBox： ```xml 床前明月光疑是地上霜举头望明月低头思故乡 ``` --- ## 4. 三种尺寸通过 `SizeType` 属性设置尺寸，支持 `Large`（40px）、`Middle`（32px，默认）、`Small`（24px）三种。 ```xml 床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡 ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "Three sizes of Input" 示例。 --- ## 5. 样式变体通过 `StyleVariant` 属性切换视觉风格，支持 `Outline`（默认）、`Filled`、`Borderless` 三种。 ```xml 床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡 ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "Variants" 示例。 --- ## 6. 前置/后置标签（AddOn）通过 `LeftAddOn` 和 `RightAddOn` 在 ComboBox 外部添加附加区域，常用于协议前缀或域名后缀： ```xml 床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡 ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "Pre / Post tab" 示例。 --- ## 7. 内部前缀/后缀（Content AddOn）通过 `ContentLeftAddOn` 和 `ContentRightAddOn` 在内容区域内部添加图标或辅助文本： ```xml 床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡床前明月光疑是地上霜举头望明月低头思故乡 ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "prefix and suffix" 示例。 --- ## 8. 验证状态（Status）通过 `Status` 属性设置验证反馈，配合不同样式变体展示各种效果： ```xml 床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜床前明月光疑是地上霜 ``` > 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml` 中 "Status" 示例。 --- ## 9. MVVM 选中项绑定 ComboBox 继承自 Avalonia 的 `SelectingItemsControl`，完整支持 `SelectedItem` / `SelectedIndex` 双向绑定： ```xml ``` ```csharp // ViewModel（使用 ReactiveUI） public class MyViewModel : ReactiveObject { private CityData? _selectedCity; public CityData? SelectedCity { get => _selectedCity; set => this.RaiseAndSetIfChanged(ref _selectedCity, value); } public List Cities { get; } = [ new() { Name = "北京" }, new() { Name = "上海" }, new() { Name = "广州" }, new() { Name = "深圳" }, ]; } ``` --- ## 10. 控制动画行为 ```xml 选项一选项二 ``` --- ## 常见组合模式 ### 表单选择器 ```xml 北京上海广州 ``` ### 带前缀图标的选择器 ```xml 张三李四王五 ``` ### 协议/域名选择器 ```xml mysite example demo ``` ### 货币金额选择器 ```xml 100 500 1000 5000 ```