syncfusion-winui-rating

用途

Syncfusion WinUI Rating 控件（SfRating）用于在 WinUI 3 桌面应用中提供直观的数值刻度评分界面，帮助用户提交或查看评分。适合产品/服务/电影/应用的评价收集、已有评分展示、评论系统、反馈表单与满意度评分等场景。

基本信息

• 控件：SfRating
• 命名空间：Syncfusion.UI.Xaml.Editors
• NuGet 包：Syncfusion.Editors.WinUI
• 平台：WinUI 3 Desktop（.NET 5+）

主要能力

• 初始化方式：可使用 Items 集合（配合 SfRatingItem）或更简单的 ItemsCount 属性。
• 精度模式：Full（整数）、Half（0.5 递增）、Exact（任意小数）。
• 自定义外观：通过 RatedItemStyle、UnratedItemStyle 设置已评分/未评分项样式，通过 ItemSize 控制项大小，通过 Orientation 设置水平或垂直排列。
• 自定义模板：使用 ItemTemplateSelector 与 DataTemplateSelector，可渲染星形、心形、表情、图片或字体图标等自定义视觉。
• 只读展示：IsReadOnly 为 true 时仅展示评分，不响应用户交互。
• 悬停提示：EnableToolTip 开启提示，ToolTipFormat 使用标准数值格式字符串或自定义格式。
• 清除评分：IsClearEnabled 控制是否允许用户重置评分。
• 占位值：PlaceholderValue 可在用户评分前展示平均分或建议分。
• 无障碍：支持键盘导航（方向键）与屏幕阅读器朗读当前值与范围。

使用方式

在 XAML 中引入命名空间 xmlns:syncfusion="using:Syncfusion.UI.Xaml.Editors"，然后声明控件：

<syncfusion:SfRating Value="3" ItemsCount="5"/>

代码方式：

using Syncfusion.UI.Xaml.Editors;

SfRating rating = new SfRating();
rating.Value = 3;
rating.ItemsCount = 5;

常见组合：半星评分（Value="3.5" Precision="Half"）、只读平均分（Value="4.2" Precision="Exact" IsReadOnly="True"）、带提示（EnableToolTip="True" ToolTipFormat="0.0"）、大尺寸项（ItemSize="40"）、垂直布局（Orientation="Vertical"）、占位值（PlaceholderValue="3.5"）、可清除（IsClearEnabled="True"）。可通过 ValueChanged 事件处理评分变化：

private void Rating_ValueChanged(object sender, ValueChangedEventArgs e)
{
    double oldValue = e.OldValue;
    double newValue = e.NewValue;
    Debug.WriteLine($"Rating changed from {oldValue} to {newValue}");
}

关键属性（资料提供的默认值）

属性	类型	默认值	说明
Value	double	0	当前评分值
ItemsCount	int	5	显示的评分项数量
Precision	RatingPrecision	Full	精度（Full/Half/Exact）
ItemSize	double	24	每个评分项大小
Orientation	Orientation	Horizontal	排列方向
IsReadOnly	bool	false	禁止用户交互
IsClearEnabled	bool	true	允许清除评分
PlaceholderValue	double	0	用户评分前的占位显示值
EnableToolTip	bool	false	悬停显示值
ToolTipFormat	string	null	提示内容格式字符串
RatedItemStyle	Style	null	已选中项样式
UnratedItemStyle	Style	null	未选中项样式
ItemTemplateSelector	DataTemplateSelector	null	自定义视觉模板

适用场景

• 产品评价表单：半星精度、启用提示、在 ValueChanged 中保存评分。
• 平均分展示：只读、Exact 精度、较小尺寸，旁边配文本显示分值。
• 满意度调查：较大尺寸、启用提示。
• 电影评分：半星精度、启用提示并格式化（如 "0.0 stars"）。

最佳实践与限制（资料说明）

• 简单评分用 Full，产品评分用 Half，Exact 一般用于展示。
• 启用提示有助于用户理解精确值；半星/精确精度建议开启提示。
• 表单常用 24–32px，突出展示可用 40–50px；ItemsCount 建议不超过 10。
• 展示型评分应设置 IsReadOnly="True"；始终提供文字标签说明。
• 避免在有用户输入时使用 Exact 精度；模板越简单性能越好；建议绑定 ViewModel 属性以便响应式更新。
• 使用前需安装 NuGet 包并注册 Syncfusion 许可证；需正确导入 Syncfusion.UI.Xaml.Editors 命名空间。

暂未提供

资料未提供收费与价格信息、授权方式细节、平台以外的兼容性说明、性能基准数据及具体版本的更新记录。