syncfusion-winui-rating

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Rating Control (SfRating)

实现评分控件（SfRating）

The Syncfusion WinUI Rating control (

SfRating

) provides an intuitive interface for users to provide or view ratings on a numeric scale. Perfect for reviews, feedback systems, and rating displays, it supports various precision modes, custom templates, and extensive styling options.

Syncfusion WinUI 评分控件（

SfRating

）为用户提供了直观的界面，用于提交或查看数字刻度的评分。它非常适合用于评论、反馈系统和评分展示场景，支持多种精度模式、自定义模板以及丰富的样式选项。

When to Use This Skill

何时使用本指南

Use the Rating control when you need to:

Collect user feedback - Gather ratings for products, services, movies, or applications
Display existing ratings - Show average ratings or user scores in read-only mode
Create review systems - Build comprehensive review and rating interfaces
Implement feedback forms - Add rating inputs to surveys and feedback forms
Show satisfaction levels - Display emoji-based or star-based satisfaction scales
Support precision ratings - Allow whole, half, or exact decimal ratings

Trigger keywords: rating, stars, star rating, SfRating, review, feedback, score, user rating, half star, precision, emoji rating, satisfaction, product rating

当你需要实现以下功能时可使用该评分控件：

收集用户反馈 - 收集产品、服务、电影或应用的评分
展示现有评分 - 以只读模式展示平均评分或用户得分
搭建评论系统 - 构建完整的评论与评分界面
实现反馈表单 - 为调研和反馈表单添加评分输入项
展示满意度水平 - 展示基于emoji或星级的满意度量表
支持精度评分 - 允许整星、半星或精确小数评分

触发关键词： rating, stars, star rating, SfRating, review, feedback, score, user rating, half star, precision, emoji rating, satisfaction, product rating

Component Overview

组件概览

Control:

SfRating

Namespace:

Syncfusion.UI.Xaml.Editors

NuGet Package:

Syncfusion.Editors.WinUI

Platform: WinUI 3 Desktop (.NET 5+)

控件：

SfRating

命名空间：

Syncfusion.UI.Xaml.Editors

NuGet包：

Syncfusion.Editors.WinUI

平台： WinUI 3 桌面端 (.NET 5+)

Key Capabilities

核心能力

Flexible initialization - Use Items collection or ItemsCount property
Precision modes - Full (whole), Half (0.5 increments), or Exact (any decimal)
Custom templates - Stars, hearts, emojis, images, or custom shapes
Styling options - Customize rated/unrated appearance, size, and orientation
Read-only mode - Display ratings without allowing user interaction
Tooltip support - Show rating values on hover with custom formatting
Clear functionality - Allow users to reset their ratings
Placeholder values - Display average ratings before user input
Accessibility - Full keyboard navigation and screen reader support

灵活初始化 - 可使用Items集合或ItemsCount属性初始化
精度模式 - 整星（整数）、半星（0.5步长）、精确值（任意小数）
自定义模板 - 支持星级、心形、emoji、图片或自定义形状
样式选项 - 自定义已评分/未评分元素的外观、尺寸和排列方向
只读模式 - 仅展示评分，不允许用户交互
工具提示支持 - 鼠标悬停时展示格式化后的评分值
清空功能 - 允许用户重置已提交的评分
占位值 - 用户输入前展示平均评分
无障碍支持 - 完整的键盘导航与屏幕阅读器支持

Documentation and Navigation Guide

文档与导航指南

Getting Started and Basic Usage

入门与基础使用

📄 Read: references/getting-started.md

Installing Syncfusion.Editors.WinUI NuGet package
Creating WinUI 3 desktop application
Importing Syncfusion.UI.Xaml.Editors namespace
Initializing SfRating control in XAML and C#
Using Items collection approach with SfRatingItem
Using ItemsCount approach (simpler method)
Setting rating values programmatically
First complete rating implementation

📄 阅读： references/getting-started.md

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

Precision Modes

精度模式

📄 Read: references/precision.md

Understanding Precision property
Full precision mode (whole numbers only: 1, 2, 3, etc.)
Half precision mode (half increments: 1.5, 2.5, 3.5, etc.)
Exact precision mode (any decimal value: 2.7, 3.2, etc.)
User interaction behavior for each mode
Choosing the right precision for your use case
Examples demonstrating each precision type

📄 阅读： references/precision.md

理解Precision属性
整星精度模式（仅支持整数：1、2、3等）
半星精度模式（0.5步长：1.5、2.5、3.5等）
精确值精度模式（任意小数：2.7、3.2等）
各模式下的用户交互行为
为你的使用场景选择合适的精度
各精度类型的演示示例

Customization Options

自定义选项

📄 Read: references/customization.md

Styling rated and unrated items (RatedItemStyle, UnratedItemStyle)
Controlling item size (ItemSize property)
Changing orientation (horizontal or vertical)
Read-only mode for display purposes (IsReadOnly)
Clearing ratings functionality (IsClearEnabled)
Showing placeholder values (PlaceholderValue)
Combining multiple customization options
Complete real-world styling examples

📄 阅读： references/customization.md

为已评分和未评分元素设置样式（RatedItemStyle、UnratedItemStyle）
控制元素尺寸（ItemSize属性）
变更排列方向（水平或垂直）
用于展示场景的只读模式（IsReadOnly）
评分清空功能（IsClearEnabled）
展示占位值（PlaceholderValue）
组合使用多种自定义选项
完整的实际场景样式示例

Templates and Custom Visuals

模板与自定义视觉效果

📄 Read: references/templates.md

ItemTemplateSelector overview
Creating path-based templates (hearts, custom shapes)
Implementing image-based templates (emoji ratings)
Using font icons as rating items
Building custom DataTemplateSelector classes
Managing selected vs unselected states
Complete emoji rating implementation
Complete heart rating implementation

📄 阅读： references/templates.md

ItemTemplateSelector概览
创建基于路径的模板（心形、自定义形状）
实现基于图片的模板（emoji评分）
使用字体图标作为评分元素
构建自定义DataTemplateSelector类
管理选中与未选中状态
完整的emoji评分实现
完整的心形评分实现

Tooltip Features

工具提示功能

📄 Read: references/tooltip-features.md

Enabling tooltips on hover (EnableToolTip property)
Formatting tooltip content (ToolTipFormat property)
Using standard numeric format strings
Creating custom format patterns
Enhancing user feedback with tooltips
Accessibility benefits of tooltips
Theme-adaptive tooltip styling

📄 阅读： references/tooltip-features.md

开启悬停工具提示（EnableToolTip属性）
格式化工具提示内容（ToolTipFormat属性）
使用标准数字格式字符串
创建自定义格式规则
通过工具提示优化用户反馈
工具提示的无障碍优势
适配主题的工具提示样式

Quick Start Example

快速入门示例

Basic 5-Star Rating

基础5星评分

XAML:

xml

<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#:

csharp

using Syncfusion.UI.Xaml.Editors;

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

XAML:

xml

<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#:

csharp

using Syncfusion.UI.Xaml.Editors;

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

Common Patterns

常用模式

1. Standard 5-Star Rating

1. 标准5星评分

xml

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

xml

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

2. Half-Star Rating System

2. 半星评分系统

xml

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

xml

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

3. Read-Only Rating Display

3. 只读评分展示

xml

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

xml

<StackPanel>
    <TextBlock Text="平均评分:"/>
    <syncfusion:SfRating 
        Value="4.2" 
        ItemsCount="5" 
        Precision="Exact"
        IsReadOnly="True"/>
</StackPanel>

4. Rating with Tooltip

4. 带工具提示的评分

xml

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

xml

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

5. Larger Rating Items

5. 大尺寸评分元素

xml

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

xml

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

6. Vertical Rating

6. 垂直排列评分

xml

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

xml

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

7. Rating with Placeholder

7. 带占位值的评分

xml

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

xml

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

8. Clearable Rating

8. 可清空的评分

xml

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

xml

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

Key Properties

核心属性

Property	Type	Default	Description
`Value`	double	0	Current rating value
`ItemsCount`	int	5	Number of rating items to display
`Precision`	RatingPrecision	Full	Rating accuracy (Full/Half/Exact)
`ItemSize`	double	24	Size of each rating item
`Orientation`	Orientation	Horizontal	Layout direction (Horizontal/Vertical)
`IsReadOnly`	bool	false	Prevents user interaction
`IsClearEnabled`	bool	true	Allows clearing the rating
`PlaceholderValue`	double	0	Initial display value before user rating
`EnableToolTip`	bool	false	Show value on hover
`ToolTipFormat`	string	null	Format string for tooltip content
`RatedItemStyle`	Style	null	Style for filled/selected items
`UnratedItemStyle`	Style	null	Style for empty/unselected items
`ItemTemplateSelector`	DataTemplateSelector	null	Custom visual templates

属性	类型	默认值	描述
`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	自定义视觉模板

Property Usage Tips

属性使用提示

Value vs PlaceholderValue:

```
Value
```
: User's actual rating
```
PlaceholderValue
```
: Shows average/suggested rating before user interaction

Precision Modes:

Full: Reviews, simple ratings (1, 2, 3, 4, 5)
Half: Product ratings, more granular feedback (3.5, 4.0, 4.5)
Exact: Analytics displays, precise averages (4.23, 3.87)

IsReadOnly:

Use
```
true
```
for displaying ratings (product listings, reviews summary)
Use
```
false
```
for collecting ratings (review forms, feedback)

IsClearEnabled:

```
true
```
: User can remove their rating by clicking first star again
```
false
```
: Once set, rating cannot be cleared (only changed)

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
```
: 评分设置后无法清空，仅可修改

Common Use Cases

常见使用场景

Product Review System

产品评论系统

xml

<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>

csharp

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

xml

<StackPanel>
    <TextBlock Text="为该产品打分:" FontWeight="Bold"/>
    <syncfusion:SfRating 
        x:Name="ProductRating"
        Value="0" 
        ItemsCount="5"
        Precision="Half"
        EnableToolTip="True"
        ToolTipFormat="0.0"
        ValueChanged="ProductRating_ValueChanged"/>
</StackPanel>

csharp

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

Average Rating Display

平均评分展示

xml

<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>

xml

<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>

Satisfaction Survey

满意度调研

xml

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

xml

<StackPanel Spacing="15">
    <TextBlock Text="你对我们的服务满意度如何？"/>
    <syncfusion:SfRating 
        Value="3" 
        ItemsCount="5"
        ItemSize="50"
        EnableToolTip="True"/>
</StackPanel>

Movie Rating Interface

电影评分界面

xml

<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>

xml

<StackPanel>
    <TextBlock Text="为该电影打分:" FontSize="16"/>
    <syncfusion:SfRating 
        Value="0" 
        ItemsCount="5"
        Precision="Half"
        ItemSize="35"
        EnableToolTip="True"
        ToolTipFormat="0.0 stars"/>
</StackPanel>

Best Practices

最佳实践

User Experience

用户体验

Precision selection: Use Full for simple ratings, Half for products, Exact for display only
Clear feedback: Enable tooltips to show exact values
Appropriate sizing: Use 24-32px for standard forms, 40-50px for prominent ratings
Placeholder values: Show average ratings to guide user expectations
Allow clearing: Enable
```
IsClearEnabled
```
unless rating is mandatory

精度选择: 简单评分用整星模式，产品评分为半星模式，仅展示场景用精确值模式
清晰反馈: 开启工具提示展示精确值
尺寸适配: 标准表单使用24-32px尺寸，突出展示的评分使用40-50px尺寸
占位值: 展示平均评分引导用户预期
允许清空: 除非评分是必填项，否则开启
```
IsClearEnabled
```

Visual Design

视觉设计

Consistent styling: Use the same style across your application
Adequate spacing: Ensure items don't overlap or feel cramped
Theme adaptation: Test in both light and dark themes
Color contrast: Ensure filled items are clearly distinguishable from empty
Custom templates: Use recognizable icons (stars, hearts, thumbs)

样式统一: 全应用使用一致的评分样式
充足间距: 确保元素不会重叠或过于拥挤
主题适配: 在亮色和暗色主题下都进行测试
色彩对比度: 确保已填充元素和未填充元素有清晰的视觉区分
自定义模板: 使用用户熟悉的图标（星级、心形、点赞）

Accessibility

无障碍

Enable tooltips: Helps all users understand exact values
Keyboard support: Rating control supports arrow key navigation
Read-only indication: Make it clear when ratings are display-only
Label association: Always include descriptive text labels
Screen readers: Control announces current value and range

开启工具提示: 帮助所有用户理解精确值
键盘支持: 评分控件支持方向键导航
只读标识: 明确标识只读状态的评分
标签关联: 始终为评分添加描述性文本标签
屏幕阅读器: 控件会播报当前值和范围

Performance

性能

ItemsCount: Use 5 for standard ratings, 10 maximum for performance
Templates: Simple templates perform better than complex images
Data binding: Bind to ViewModel properties for reactive updates

ItemsCount: 标准评分使用5个元素，为保证性能最多不超过10个
模板: 简单模板比复杂图片性能更好
数据绑定: 绑定到ViewModel属性实现响应式更新

Common Mistakes to Avoid

需要避免的常见错误

❌ Using Exact precision with user input (difficult to control precisely)
❌ Forgetting to set
```
IsReadOnly="True"
```
for display ratings
❌ Not providing labels or context for the rating
❌ Using too many items (>10 becomes hard to use)
❌ Omitting tooltips on Half/Exact precision ratings
❌ Not importing Syncfusion.UI.Xaml.Editors namespace

❌ 对用户输入场景使用精确值精度（用户很难精准控制）
❌ 展示评分时忘记设置
```
IsReadOnly="True"
```
❌ 没有为评分提供标签或上下文说明
❌ 使用过多评分元素（超过10个会很难操作）
❌ 半星/精确值精度的评分没有添加工具提示
❌ 未导入Syncfusion.UI.Xaml.Editors命名空间

Troubleshooting

故障排查

Rating value not updating:

Verify
```
IsReadOnly
```
is
```
false
```
Check if
```
Value
```
is bound correctly (TwoWay binding)
Ensure ValueChanged event is hooked up

Stars not displaying:

Confirm NuGet package is installed

Verify namespace import:

xmlns:syncfusion="using:Syncfusion.UI.Xaml.Editors"

Check if Syncfusion license is registered

Half-star not showing:

Set
```
Precision="Half"
```
Ensure Value uses .5 increments (3.5, 4.0, 4.5)

Custom template not appearing:

Verify DataTemplateSelector is properly implemented
Check if templates are defined in Resources
Ensure ItemTemplateSelector property is set

Tooltip not visible:

Set
```
EnableToolTip="True"
```
Check if mouse hover is triggering (test with different elements)

评分值不更新：

确认
```
IsReadOnly
```
设置为
```
false
```
检查
```
Value
```
是否正确绑定（双向绑定）
确认已绑定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"
```
检查鼠标悬停是否触发（用其他元素测试）

Events

事件

ValueChanged:

csharp

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}");
}

ValueChanged：

csharp

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}");
}

syncfusion-winui-rating

Original

Translation

Implementing Rating Control (SfRating)

实现评分控件（SfRating）

When to Use This Skill

何时使用本指南

Component Overview

组件概览

Key Capabilities

核心能力

Documentation and Navigation Guide

文档与导航指南

Getting Started and Basic Usage

入门与基础使用

Precision Modes

精度模式

Customization Options

自定义选项

Templates and Custom Visuals

模板与自定义视觉效果

Tooltip Features

工具提示功能

Quick Start Example

快速入门示例

Basic 5-Star Rating

基础5星评分

Common Patterns

常用模式

1. Standard 5-Star Rating

1. 标准5星评分

2. Half-Star Rating System

2. 半星评分系统

3. Read-Only Rating Display

3. 只读评分展示

4. Rating with Tooltip

4. 带工具提示的评分

5. Larger Rating Items

5. 大尺寸评分元素

6. Vertical Rating

6. 垂直排列评分

7. Rating with Placeholder

7. 带占位值的评分

8. Clearable Rating

8. 可清空的评分

Key Properties

核心属性

Property Usage Tips

属性使用提示

Common Use Cases

常见使用场景

Product Review System

产品评论系统

Average Rating Display

平均评分展示

Satisfaction Survey

满意度调研

Movie Rating Interface

电影评分界面

Best Practices

最佳实践

User Experience

用户体验

Visual Design

视觉设计

Accessibility

无障碍

Performance

性能

Common Mistakes to Avoid

需要避免的常见错误

Troubleshooting

故障排查

Events

事件

Related Components

相关组件