AtomUI/docs/Desktop.Controls/Rate/RateAPI.md

Rate API 参考

命名空间

// 桌面端控件
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 变化时触发