syncfusion-winui-rating

实现评分控件（SfRating）

Syncfusion WinUI 评分控件（SfRating）为用户提供直观的界面，可在数值范围内提交或查看评分。它非常适用于评论、反馈系统和评分展示，支持多种精度模式、自定义模板和丰富的样式选项。

何时使用此技能

在以下情况下使用评分控件：

• 收集用户反馈 - 收集用户对产品、服务、电影或应用的评分
• 显示现有评分 - 以只读模式显示平均评分或用户分数
• 创建评论系统 - 构建全面的评论和评分界面
• 实现反馈表单 - 在调查问卷和反馈表单中添加评分输入项
• 显示满意度 - 展示基于表情符号或星级的满意度量表
• 支持精确评分 - 支持整数、半星或精确的小数评分

触发关键词： 评分、星星、星级评分、SfRating、评论、反馈、分数、用户评分、半星、精度、表情符号评分、满意度、产品评分

组件概览

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

主要功能

• 灵活初始化 - 使用 Items 集合或 ItemsCount 属性
• 精度模式 - Full（整数）、Half（以 0.5 为增量）或 Exact（任意小数）
• 自定义模板 - 星星、爱心、表情符号、图像或自定义形状
• 样式选项 - 自定义已评分和未评分状态的外观、大小和方向
• 只读模式 - 展示评分但不允许用户交互
• 工具提示支持 - 悬停时显示评分值，并支持自定义格式
• 清除功能 - 允许用户重置评分
• 占位值 - 在用户输入前显示平均评分
• 无障碍支持 - 完整支持键盘导航和屏幕阅读器

文档与导航指南

入门与基本用法

📄 阅读： references/getting-started.md

• 安装 Syncfusion.Editors.WinUI NuGet 包
• 创建 WinUI 3 桌面应用程序
• 导入 Syncfusion.UI.Xaml.Editors 命名空间
• 在 XAML 和 C# 中初始化 SfRating 控件
• 使用 SfRatingItem 的 Items 集合方式
• 使用 ItemsCount 方式（更简单的方法）
• 以编程方式设置评分值
• 首个完整评分实现

精度模式

📄 阅读： references/precision.md

• 了解 Precision 属性
• Full 精度模式（仅整数：1、2、3 等）
• Half 精度模式（以半分递增：1.5、2.5、3.5 等）
• Exact 精度模式（任意小数值：2.7、3.2 等）
• 各模式下的用户交互行为
• 为使用场景选择合适的精度
• 演示各类精度的示例

自定义选项

📄 阅读： references/customization.md references/customization-advanced.md

• 设置已评分和未评分项的样式（RatedItemStyle、UnratedItemStyle）
• 控制项大小（ItemSize 属性）
• 更改方向（水平或垂直）
• 用于展示的只读模式（IsReadOnly）
• 清除评分功能（IsClearEnabled）
• 显示占位值（PlaceholderValue）
• 组合多个自定义选项
• 完整的真实场景样式示例

模板与自定义视觉效果

📄 阅读： references/templates.md

• ItemTemplateSelector 概览
• 创建基于路径的模板（爱心、自定义形状）
• 实现基于图像的模板（表情符号评分）
• 使用字体图标作为评分项
• 构建自定义 DataTemplateSelector 类
• 管理已选中与未选中状态
• 完整的表情符号评分实现
• 完整的爱心评分实现

工具提示功能

📄 阅读： references/tooltip-features.md references/tooltip-customization.md

• 启用悬停时显示工具提示（EnableToolTip 属性）
• 设置工具提示内容的格式（ToolTipFormat 属性）
• 使用标准数字格式字符串
• 创建自定义格式模式
• 使用工具提示增强用户反馈
• 工具提示的无障碍优势
• 适配主题的工具提示样式

快速入门示例

基本的 5 星评分

XAML：

<Page
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:syncfusion="using:Syncfusion.UI.Xaml.Editors">
    
    <Grid>
        <syncfusion:SfRating Value="3" ItemsCount="5"/>
    </Grid>
</Page>

C#：

using Syncfusion.UI.Xaml.Editors;

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

常见模式

1. 标准的 5 星评分

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

2. 半星评分系统

<syncfusion:SfRating 
    Value="3.5" 
    ItemsCount="5" 
    Precision="Half"/>

3. 只读评分显示

<StackPanel>
    <TextBlock Text="Average Rating:"/>
    <syncfusion:SfRating 
        Value="4.2" 
        ItemsCount="5" 
        Precision="Exact"
        IsReadOnly="True"/>
</StackPanel>

4. 带工具提示的评分

<syncfusion:SfRating 
    Value="3" 
    ItemsCount="5"
    EnableToolTip="True"
    ToolTipFormat="0.0"/>

5. 更大的评分项

<syncfusion:SfRating 
    Value="4" 
    ItemsCount="5"
    ItemSize="40"/>

6. 垂直评分

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

7. 带占位值的评分

<syncfusion:SfRating 
    ItemsCount="5"
    PlaceholderValue="3.5"/>

8. 可清除的评分

<syncfusion:SfRating 
    Value="4" 
    ItemsCount="5"
    IsClearEnabled="True"/>

关键属性

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

属性使用提示

Value 与 PlaceholderValue：

• Value：用户的实际评分
• PlaceholderValue：用户交互前显示的平均分/建议评分

精度模式：

• Full：评论、简单评分（1、2、3、4、5）
• Half：产品评分、更细致的反馈（3.5、4.0、4.5）
• Exact：分析数据展示、精确平均分（4.23、3.87）

IsReadOnly：

• 显示评分时使用 true（产品列表、评论摘要）
• 收集评分时使用 false（评论表单、反馈）

IsClearEnabled：

• true：用户再次点击第一颗星即可清除评分
• false：评分设置后不可清除（只能更改）

常见用例

产品评论系统

<StackPanel>
    <TextBlock Text="Rate this product:" FontWeight="Bold"/>
    <syncfusion:SfRating 
        x:Name="ProductRating"
        Value="0" 
        ItemsCount="5"
        Precision="Half"
        EnableToolTip="True"
        ToolTipFormat="0.0"
        ValueChanged="ProductRating_ValueChanged"/>
</StackPanel>

private void ProductRating_ValueChanged(object sender, ValueChangedEventArgs e)
{
    // Save rating to database
    SaveProductRating(e.NewValue);
}

平均评分显示

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="Auto"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>
    
    <syncfusion:SfRating 
        Grid.Column="0"
        Value="{Binding AverageRating}" 
        ItemsCount="5"
        Precision="Exact"
        IsReadOnly="True"
        ItemSize="20"/>
    
    <TextBlock 
        Grid.Column="1"
        Text="{Binding AverageRating, StringFormat='({0:0.0})'}"
        VerticalAlignment="Center"
        Margin="10,0,0,0"/>
</Grid>

满意度调查

<StackPanel Spacing="15">
    <TextBlock Text="How satisfied are you with our service?"/>
    <syncfusion:SfRating 
        Value="3" 
        ItemsCount="5"
        ItemSize="50"
        EnableToolTip="True"/>
</StackPanel>

电影评分界面

<StackPanel>
    <TextBlock Text="Rate this movie:" FontSize="16"/>
    <syncfusion:SfRating 
        Value="0" 
        ItemsCount="5"
        Precision="Half"
        ItemSize="35"
        EnableToolTip="True"
        ToolTipFormat="0.0 stars"/>
</StackPanel>

最佳实践

用户体验

• 精度选择：简单评分使用 Full，产品评分使用 Half，仅用于显示时使用 Exact
• 清晰反馈：启用工具提示以显示精确数值
• 合适的尺寸：标准表单使用 24-32px，醒目评分使用 40-50px
• 占位值：显示平均评分，帮助用户形成预期
• 允许清除：除非评分为必填项，否则启用 IsClearEnabled

视觉设计

• 样式一致：在整个应用中使用相同的样式
• 留出足够间距：确保评分项不会重叠或显得拥挤
• 主题适配：在浅色和深色主题下进行测试
• 颜色对比度：确保已填充项与空白项清晰可辨
• 自定义模板：使用易于识别的图标（星星、爱心、点赞）

无障碍

• 启用工具提示：帮助所有用户了解精确数值
• 键盘支持：评分控件支持使用方向键导航
• 只读状态提示：明确说明评分仅供显示
• 标签关联：始终包含描述性文本标签
• 屏幕阅读器：控件会播报当前值和范围

性能

• ItemsCount：标准评分使用 5，性能评分最多使用 10
• 模板：简单模板的性能优于复杂图像
• 数据绑定：绑定到 ViewModel 属性，以实现响应式更新

常见错误

• ❌ 对用户输入使用 Exact 精度（难以精确控制）
• ❌ 对显示评分忘记设置 IsReadOnly="True"
• ❌ 未提供评分的标签或上下文
• ❌ 使用过多项（超过 10 项会难以使用）
• ❌ 使用 Half/Exact 精度的评分时未添加工具提示
• ❌ 未导入 Syncfusion.UI.Xaml.Editors 命名空间

故障排除

评分值未更新：

• 确认 IsReadOnly 为 false
• 检查 Value 是否正确绑定（TwoWay 绑定）
• 确保已挂接 ValueChanged 事件

星星未显示：

• 确认已安装 NuGet 包
• 确认已导入命名空间：xmlns:syncfusion="using:Syncfusion.UI.Xaml.Editors"
• 检查是否已注册 Syncfusion 许可证

半星未显示：

• 设置 Precision="Half"
• 确保 Value 使用 0.5 的增量（3.5、4.0、4.5）

自定义模板未显示：

• 确认已正确实现 DataTemplateSelector
• 检查 Resources 中是否定义了模板
• 确保已设置 ItemTemplateSelector 属性

工具提示不可见：

• 设置 EnableToolTip="True"
• 检查鼠标悬停是否触发（尝试使用不同的元素进行测试）

事件

ValueChanged：

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

---

需要更多详细信息？ 请阅读上方导航指南中链接的参考文件，获取全面的文档和示例。