mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 23:30:44 +08:00
chinboy
115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# Rate API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
// 桌面端控件
|
||
namespace AtomUI.Desktop.Controls;
|
||
|
||
// 跨平台基类（AbstractRate）
|
||
namespace AtomUI.Controls.Commons;
|
||
|
||
// 数据类型（RateValueChangedEventArgs）
|
||
namespace AtomUI.Controls;
|
||
```
|
||
|
||
AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
|
||
|
||
---
|
||
|
||
## Rate 公共属性（StyledProperty）
|
||
|
||
以下属性定义在 `AbstractRate` 基类中，`Rate` 直接继承：
|
||
|
||
| 属性名 | 类型 | 默认值 | 来源 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `IsAllowClear` | `bool` | `true` | `AbstractRate` | 是否允许再次点击后清除评分 |
|
||
| `IsAllowHalf` | `bool` | `false` | `AbstractRate` | 是否允许半星评分（0.5 步长） |
|
||
| `Character` | `object?` | `StarFilled` 图标 | `AbstractRate` | 自定义评分字符，支持 `Icon`、`char`、`string` 三种类型 |
|
||
| `StarColor` | `IBrush?` | 由 Token 控制（`RateToken.StarColor`） | `AbstractRate` | 星星选中颜色 |
|
||
| `StarBgColor` | `IBrush?` | 由 Token 控制（`RateToken.StarBg`） | `AbstractRate` | 星星未选中背景色 |
|
||
| `Count` | `int` | `5` | `AbstractRate` | 星星总数 |
|
||
| `Value` | `double` | `NaN`（初始化后取 `DefaultValue`） | `AbstractRate` | 当前评分值 |
|
||
| `DefaultValue` | `double` | `0` | `AbstractRate` | 默认评分值（`Value` 未设置时的初始值） |
|
||
| `IsKeyboardEnabled` | `bool` | `true` | `AbstractRate` | 是否启用键盘操作（方向键调整评分） |
|
||
| `ToolTips` | `IList<string>?` | `null` | `AbstractRate` | 每颗星的提示文案列表，长度应等于 `Count` |
|
||
| `SizeType` | `SizeType` | `SizeType.Middle` | `AbstractRate`（共享属性） | 尺寸类型（`Large` / `Middle` / `Small`） |
|
||
| `IsMotionEnabled` | `bool` | 跟随全局 Token `EnableMotion` | `AbstractRate`（共享属性） | 是否启用过渡动画（悬浮缩放） |
|
||
|
||
### 继承自 Avalonia.Controls.Primitives.TemplatedControl 的常用属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `IsEnabled` | `bool` | `true` | 是否启用，`false` 为只读模式 |
|
||
| `Focusable` | `bool` | `true` | 是否可获得焦点（由主题设置） |
|
||
| `FontSize` | `double` | 由主题控制 | 影响文字字符的大小 |
|
||
| `ClipToBounds` | `bool` | `false` | 裁剪超出边界内容（设为 false 以支持悬浮缩放溢出） |
|
||
|
||
---
|
||
|
||
## Rate 事件
|
||
|
||
| 事件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `ValueChanged` | `EventHandler<RateValueChangedEventArgs>` | 评分值变化事件（点击确认或键盘调整后触发） |
|
||
| `HoverValueChanged` | `EventHandler<RateValueChangedEventArgs>` | 悬浮值变化事件（鼠标在星星上移动时触发） |
|
||
|
||
### RateValueChangedEventArgs
|
||
|
||
选中变化事件参数，继承自 `EventArgs`。
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `OldValue` | `double` | 变化前的值 |
|
||
| `NewValue` | `double` | 变化后的值 |
|
||
|
||
---
|
||
|
||
## 键盘操作
|
||
|
||
当 `IsKeyboardEnabled = true`（默认）且 Rate 获得焦点时，支持以下键盘操作：
|
||
|
||
| 按键 | 整星模式 | 半星模式 |
|
||
|---|---|---|
|
||
| `←` 左方向键 | 减 1 | 减 0.5 |
|
||
| `→` 右方向键 | 加 1 | 加 0.5 |
|
||
|
||
评分值会被自动限制在 `[0, Count]` 范围内。
|
||
|
||
---
|
||
|
||
## Character 属性支持的类型
|
||
|
||
| 类型 | 示例 | 渲染方式 |
|
||
|---|---|---|
|
||
| `Icon`（`PathIcon` 子类） | `StarFilled`、`HeartOutlined` | 通过 `FillBrush` / `StrokeBrush` 着色 |
|
||
| `char` | `'A'`、`'秦'` | 通过内部 `RateCharacter` 控件自绘制 |
|
||
| `string` | `"A"`、`"秦"` | 取首字符，通过 `RateCharacter` 渲染 |
|
||
| `null` | — | 自动使用默认 `StarFilled` 图标 |
|
||
|
||
---
|
||
|
||
## Value 属性行为说明
|
||
|
||
- `Value` 的初始值为 `double.NaN`，控件初始化时自动设置为 `DefaultValue`
|
||
- `Value` 的有效范围为 `[0, Count]`
|
||
- 当 `IsAllowHalf = true` 时，`Value` 可以是 0.5 的倍数（如 0.5、1、1.5、2...）
|
||
- 当 `IsAllowHalf = false` 时，`Value` 始终为整数
|
||
- 将 `Value` 设为 0 表示清除评分
|
||
|
||
---
|
||
|
||
## 实现的接口
|
||
|
||
| 接口 | 定义位置 | 作用 |
|
||
|---|---|---|
|
||
| `IMotionAwareControl` | `AtomUI.Controls.Shared` | 过渡动画开关，控制悬浮缩放过渡效果 |
|
||
| `ISizeTypeAware` | `AtomUI.Controls.Shared` | 三种尺寸切换（Small / Middle / Large），映射到不同的星星大小 |
|
||
| `IFormItemAware` | `AtomUI.Controls.Shared` | 可参与表单验证 |
|
||
|
||
**IFormItemAware 在 Rate 中的行为：**
|
||
- `GetFormValue()` → 返回 `Value`（`double?` 类型）
|
||
- `SetFormValue(value)` → 设置 `Value`（接受 `double?`）
|
||
- `ClearFormValue()` → 将 `Value` 设为 `0.0`
|
||
- `ValueChanged` → 当 `Value` 变化时触发
|