mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 15:20:25 +08:00
chinboy
190 lines
6.0 KiB
Markdown
190 lines
6.0 KiB
Markdown
# ComboBox API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
namespace AtomUI.Desktop.Controls;
|
||
```
|
||
|
||
AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
|
||
|
||
---
|
||
|
||
## 枚举类型
|
||
|
||
### InputControlStyleVariant
|
||
|
||
样式变体枚举，定义控件的视觉风格。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Outline` | 描边样式（默认），白色背景 + 实线边框 |
|
||
| `Filled` | 填充样式，灰色填充背景 |
|
||
| `Borderless` | 无边框样式，无背景无边框 |
|
||
|
||
### InputControlStatus
|
||
|
||
输入控件验证状态枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Default` | 默认状态（无验证反馈） |
|
||
| `Error` | 错误状态，红色系视觉反馈 |
|
||
| `Warning` | 警告状态，橙色系视觉反馈 |
|
||
|
||
### SizeType（来自 `AtomUI.Controls`）
|
||
|
||
尺寸类型枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Small` | 小号（24px） |
|
||
| `Middle` | 中号（默认，32px） |
|
||
| `Large` | 大号（40px） |
|
||
|
||
---
|
||
|
||
## 公共属性（StyledProperty）
|
||
|
||
### AddOn 扩展区域属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `LeftAddOn` | `object?` | `null` | 前置标签内容（选择器外部左侧），支持文本或控件 |
|
||
| `LeftAddOnTemplate` | `IDataTemplate?` | `null` | 前置标签的数据模板 |
|
||
| `RightAddOn` | `object?` | `null` | 后置标签内容（选择器外部右侧），支持文本或控件 |
|
||
| `RightAddOnTemplate` | `IDataTemplate?` | `null` | 后置标签的数据模板 |
|
||
| `ContentLeftAddOn` | `object?` | `null` | 内部前缀内容（内容区域左侧），常用于图标 |
|
||
| `ContentLeftAddOnTemplate` | `IDataTemplate?` | `null` | 内部前缀的数据模板 |
|
||
| `ContentRightAddOn` | `object?` | `null` | 内部后缀内容（内容区域右侧，手柄左侧） |
|
||
| `ContentRightAddOnTemplate` | `IDataTemplate?` | `null` | 内部后缀的数据模板 |
|
||
|
||
### 外观与行为属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `SizeType` | `SizeType` | `SizeType.Middle` | 控件尺寸（共享属性，通过 `AddOwner` 注册） |
|
||
| `StyleVariant` | `InputControlStyleVariant` | `InputControlStyleVariant.Outline` | 样式变体（共享属性） |
|
||
| `Status` | `InputControlStatus` | `InputControlStatus.Default` | 验证状态（共享属性） |
|
||
| `IsAllowClear` | `bool` | `false` | 是否允许清除已选值 |
|
||
| `OptionFontSize` | `double` | 由 Token 控制 | 下拉选项列表的字体大小 |
|
||
| `IsMotionEnabled` | `bool` | 跟随全局 Token | 是否启用过渡动画（共享属性） |
|
||
| `DropDownDisplayPageSize` | `int` | `10` | 下拉面板最多可见选项数量，超出部分滚动显示 |
|
||
|
||
### 继承自 Avalonia.Controls.ComboBox 的常用属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemsSource` | `IEnumerable?` | `null` | 数据源集合，支持绑定任意集合 |
|
||
| `ItemTemplate` | `IDataTemplate?` | `null` | 项目数据模板，定义每个选项的呈现方式 |
|
||
| `SelectedItem` | `object?` | `null` | 当前选中项，支持双向绑定 |
|
||
| `SelectedIndex` | `int` | `-1` | 当前选中项索引 |
|
||
| `PlaceholderText` | `string?` | `null` | 未选中时显示的占位提示文本 |
|
||
| `IsDropDownOpen` | `bool` | `false` | 下拉面板是否打开 |
|
||
| `MaxDropDownHeight` | `double` | 自动计算 | 下拉面板最大高度（由 `DropDownDisplayPageSize` 自动派生） |
|
||
| `ItemsPanel` | `ItemsPanelTemplate` | `VirtualizingStackPanel` | 项目面板模板 |
|
||
| `IsEnabled` | `bool` | `true` | 是否启用 |
|
||
| `Width` | `double` | `NaN` | 控件宽度 |
|
||
|
||
---
|
||
|
||
## 事件
|
||
|
||
| 事件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `SelectionChanged` | `EventHandler<SelectionChangedEventArgs>` | 选中项变更事件（继承自 `SelectingItemsControl`） |
|
||
|
||
---
|
||
|
||
## 伪类（Pseudo-Classes）
|
||
|
||
ComboBox 支持以下伪类，可在样式选择器中使用：
|
||
|
||
| 伪类 | 触发条件 |
|
||
|---|---|
|
||
| `:error` | `Status == InputControlStatus.Error` |
|
||
| `:warning` | `Status == InputControlStatus.Warning` |
|
||
|
||
### 继承的标准伪类
|
||
|
||
| 伪类 | 触发条件 |
|
||
|---|---|
|
||
| `:pointerover` | 鼠标悬浮 |
|
||
| `:pressed` | 控件被按下（非下拉打开状态下） |
|
||
| `:disabled` | `IsEnabled == false` |
|
||
| `:focus` | 获得焦点 |
|
||
| `:focus-visible` | 通过键盘获得焦点（显示焦点框） |
|
||
|
||
---
|
||
|
||
## 实现的接口
|
||
|
||
### IMotionAwareControl
|
||
|
||
```csharp
|
||
public bool IsMotionEnabled { get; set; }
|
||
```
|
||
|
||
控制下拉面板展开/收起动画、ComboBoxItem 背景色过渡动画的开关。
|
||
|
||
### ISizeTypeAware
|
||
|
||
```csharp
|
||
public SizeType SizeType { get; set; }
|
||
```
|
||
|
||
支持 `Small`（24px）、`Middle`（32px，默认）、`Large`（40px）三种尺寸。尺寸会同步传递给内部的 `AddOnDecoratedBox` 和 `ComboBoxItem`。
|
||
|
||
### IInputControlStatusAware
|
||
|
||
```csharp
|
||
public InputControlStatus Status { get; set; }
|
||
```
|
||
|
||
支持 `Default`、`Error`、`Warning` 三种验证状态。状态变更时自动更新对应伪类（`:error`、`:warning`）。
|
||
|
||
### IInputControlStyleVariantAware
|
||
|
||
```csharp
|
||
public InputControlStyleVariant StyleVariant { get; set; }
|
||
```
|
||
|
||
支持 `Outline`、`Filled`、`Borderless` 三种样式变体。变体会传递给内部的 `AddOnDecoratedBox`。
|
||
|
||
### IFormItemAware
|
||
|
||
可作为 `FormItem` 的子控件参与表单验证流程。ComboBox 提供以下行为：
|
||
|
||
- 选中项变更时通过 `ValueChanged` 事件通知 FormItem
|
||
- FormItem 验证状态（`FormValidateStatus`）自动映射为 `Status` 属性
|
||
|
||
### IFormItemFeedbackAware
|
||
|
||
可接收并显示表单验证反馈控件（`FormValidateFeedback`），反馈图标显示在下拉手柄左侧。
|
||
|
||
---
|
||
|
||
## 辅助控件
|
||
|
||
### ComboBoxItem
|
||
|
||
下拉选项容器，继承自 `Avalonia.Controls.ComboBoxItem`。
|
||
|
||
| 伪类 | 说明 |
|
||
|---|---|
|
||
| `:pointerover` | 鼠标悬浮在选项上 |
|
||
| `:selected` | 选项被选中 |
|
||
| `:disabled` | 选项被禁用 |
|
||
|
||
### ComboBoxHandle（内部控件）
|
||
|
||
下拉手柄组件，包含一个 `IconButton`（`DownOutlined` 图标）。
|
||
|
||
| 属性名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `IsMotionEnabled` | `bool` | 是否启用动画 |
|
||
|
||
| 事件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `HandleClick` | `EventHandler<RoutedEventArgs>` | 手柄被点击 |
|