syncfusion-wpf-rating

实现 Syncfusion WPF 评分控件

WPF 的 SfRating 控件提供基于星形的可视化评分系统，允许用户为项目评分。它支持可配置的精度模式、丰富的外观自定义选项、工具提示和只读显示。可使用此控件为电影、应用程序、产品或服务评分，也可用于任何需要通过评分界面收集用户反馈的场景。

何时使用此技能

在以下情况下使用此技能：

• 在 WPF 应用程序中实现基于星形的评分控件
• 创建产品或服务评分界面
• 构建带可视化评分反馈的评价系统
• 显示只读评分（例如，平均评分、历史评分）
• 配置评分精度（整星、半星或精确值）
• 自定义评分外观（颜色、大小、间距、悬停效果）
• 添加工具提示以显示评分值
• 使用 ValueChanged 事件处理评分值更改
• 将评分控件集成到数据绑定场景中

组件概览

SfRating 提供：

• 可配置的评分项数量（通常为 5 颗星）
• 三种精度模式：Standard（整星）、Half（0.5 递增）和 Exact（任意值）
• 丰富的样式选项（填充颜色、描边颜色、大小、间距）
• 支持自定义精度和外观的工具提示
• 只读模式，用于显示不可编辑的评分
• 用于处理评分更新的 ValueChanged 事件
• 主题支持（通过 SfSkinManager）

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 包安装
• 通过设计器、XAML 或 C# 添加 SfRating 控件
• 设置 ItemsCount 和 Value 属性
• 基本配置和 ValueChanged 事件
• 方法概览（Dispose、模板方法、事件处理程序）
• 主题配置

精度模式

📄 阅读： references/precision.md

• 了解精度模式（Standard、Half、Exact）
• 配置评分精度级别
• 各种精度类型的适用场景
• 代码示例和视觉比较

外观和样式

📄 阅读： references/appearance-styling.md

• 自定义填充颜色（已评分/未评分项）
• 设置描边颜色和粗细
• 配置鼠标悬停效果
• 调整项目高度、大小和间距
• 设置评分项的圆角半径
• 使用 ItemContainerStyle 统一样式
• 用于悬停反馈的 PreviewValue 属性

工具提示配置

📄 阅读： references/tooltip.md

• 启用/禁用工具提示
• 配置工具提示精度（小数位数）
• 自定义工具提示前景色
• 工具提示行为和最佳实践

只读模式

📄 阅读： references/readonly-configuration.md

• 设置 IsReadOnly 属性
• 不可编辑评分的适用场景
• 将只读模式与样式选项结合使用

快速入门示例

基本评分控件（XAML）

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:SfRating ItemsCount="5" 
                             Value="3" 
                             Width="150"/>
    </Grid>
</Window>

基本评分控件（C#）

using Syncfusion.Windows.Controls.Input;

namespace RatingApp
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            
            SfRating rating = new SfRating()
            {
                ItemsCount = 5,
                Value = 3,
                Width = 150
            };
            
            this.Content = rating;
        }
    }
}

常见模式

1. 使用 ValueChanged 事件的评分控件

<syncfusion:SfRating ItemsCount="5" 
                     Value="3" 
                     Width="150"
                     ValueChanged="SfRating_ValueChanged"/>

private void SfRating_ValueChanged(object sender, ValueChangedEventArgs e)
{
    var oldValue = e.OldValue;
    var newValue = e.NewValue;
    MessageBox.Show($"Rating changed from {oldValue} to {newValue}");
}

2. 半星精度评分

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

3. 自定义样式评分控件

<syncfusion:SfRating ItemsCount="5" Value="4" Width="150">
    <syncfusion:SfRating.ItemContainerStyle>
        <Style TargetType="syncfusion:SfRatingItem">
            <Setter Property="RatedFill" Value="Gold"/>
            <Setter Property="UnratedFill" Value="LightGray"/>
            <Setter Property="RatedStroke" Value="Orange"/>
            <Setter Property="RatedStrokeThickness" Value="2"/>
        </Style>
    </syncfusion:SfRating.ItemContainerStyle>
</syncfusion:SfRating>

4. 只读评分显示

<syncfusion:SfRating ItemsCount="5" 
                     Value="4.5" 
                     Precision="Half"
                     IsReadOnly="True" 
                     Width="150"/>

5. 自定义大小和间距的评分控件

<syncfusion:SfRating ItemsCount="5" 
                     Value="3" 
                     ItemSize="30"
                     ItemsSpacing="10"
                     Width="200"/>

6. 配置工具提示的评分控件

<syncfusion:SfRating ItemsCount="5" 
                     Value="3" 
                     Precision="Exact"
                     ShowToolTip="True"
                     AutoToolTipPrecision="2"
                     ToolTipForeground="DarkBlue"
                     Width="150"/>

关键属性

属性	类型	说明
ItemsCount	int	要显示的评分项数量（例如，5 颗星）
Value	double	当前评分值（范围为 0 到 ItemsCount）
Precision	Precision	评分精度：Standard、Half 或 Exact
IsReadOnly	bool	为 true 时，评分不可编辑
ShowToolTip	bool	鼠标悬停时显示/隐藏工具提示（默认值：true）
AutoToolTipPrecision	int	工具提示中的小数位数（默认值：1）
ItemSize	double	每个评分项的大小（默认值：20）
ItemsSpacing	double	评分项之间的间距（默认值：4）
CornerRadius	CornerRadius	评分项的圆角半径
PreviewValue	double	鼠标悬停时显示的只读预览值

样式属性（通过 ItemContainerStyle 设置）

属性	说明
RatedFill	已选中/已评分项的填充颜色
UnratedFill	未选中项的填充颜色
RatedStroke	已评分项的描边颜色
UnratedStroke	未评分项的描边颜色
RatedStrokeThickness	已评分项的描边粗细
UnratedStrokeThickness	未评分项的描边粗细
PointerOverFill	鼠标悬停时的填充颜色
PointerOverStroke	鼠标悬停时的描边颜色
PointerOverStrokeThickness	鼠标悬停时的描边粗细
Height	单个评分项的高度

常见使用场景

1. 商品评价 - 在电子商务应用中显示并收集商品评分
2. 服务反馈 - 收集用户对服务的满意度评分
3. 电影/内容评分 - 显示媒体内容的评分并允许用户评分
4. 绩效评估 - 用于评估的可视化评分量表
5. 问卷回答 - 问卷中的评分量表问题
6. 仪表板指标 - 以可视化评分的形式显示 KPI 或质量分数
7. 用户资料 - 显示用户声誉或技能水平评分
8. 比较工具 - 直观比较已评分的项目

最佳实践

• 简单的 1-5 星评分使用 Standard 精度
• 更精细的反馈（以 0.5 为增量）使用 Half 精度
• 绑定计算值或允许精确输入时使用 Exact 精度
• 显示平均评分或历史评分时，将 IsReadOnly="True"
• 自定义 RatedFill，以匹配应用的品牌颜色
• 使用 ShowToolTip，在显示星级的同时提供数值反馈
• 根据 UI 布局设置合适的 ItemSize 和 ItemsSpacing
• 处理 ValueChanged 事件，以即时反馈或更新数据绑定
• 显示小数平均值时，可考虑同时使用 Precision="Half" 和 IsReadOnly="True"

程序集要求

所需程序集：

• Syncfusion.SfInput.WPF
• Syncfusion.SfShared.WPF

NuGet 包：Syncfusion.SfInput.WPF

相关组件

• TextBox - 文本输入控件
• Numeric TextBox - 带验证的数字输入
• Input Mask - 格式化文本输入
• Slider - 范围值选择