syncfusion-winforms-rating
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion WinForms Rating Control
实现Syncfusion WinForms Rating控件
The Rating Control provides an intuitive visual rating experience that allows users to select a number of stars (or other shapes) to represent a rating value. This control is ideal for user feedback, product reviews, quality ratings, and any scenario requiring visual rating input.
Rating控件提供直观的可视化评分体验，允许用户选择若干星形（或其他形状）来代表评分值。该控件非常适合用户反馈、产品评价、质量评分以及所有需要可视化评分输入的场景。
When to Use This Skill
何时使用该技能
Use this skill when the user needs to:
- Star Rating Systems: Product ratings, reviews, user feedback with 1-5 stars
- Custom Rating Shapes: Hearts for favorites, diamonds for quality, circles for simplicity
- Half-Star Ratings: Fine-grained precision (3.5 stars, 4.5 stars) for detailed feedback
- Feedback Forms: Customer satisfaction, service quality, experience ratings
- Review Interfaces: Movie ratings, book reviews, app store ratings
- Rating Display: Show read-only ratings or interactive rating input
- Themed Rating Controls: Office 2007/2010/2016 styles with consistent UI appearance
- Vertical/Horizontal Layouts: Adapt rating orientation to form design
当用户需要实现以下功能时可以使用本技能：
- 星级评分系统： 产品评分、评价、1-5星的用户反馈
- 自定义评分形状： 心形代表收藏、菱形代表质量、圆形代表简洁风格
- 半星评分： 细粒度精度（3.5星、4.5星）的详细反馈
- 反馈表单： 客户满意度、服务质量、体验评分
- 评价界面： 电影评分、书评、应用商店评分
- 评分展示： 展示只读评分或者可交互的评分输入框
- 主题化评分控件： 保持UI外观统一的Office 2007/2010/2016样式
- 垂直/水平布局： 适配表单设计调整评分控件的布局方向
Component Overview
组件概述
RatingControl () is a versatile rating input control supporting:
Syncfusion.Windows.Forms.Tools.RatingControl- 6 Built-in Shapes: Star, Circle, Triangle, Heart, Diamond, Kite
- Custom Images: Use your own image assets for unique rating indicators
- Precision Modes: Standard (full shapes) or Half (half-shape granularity)
- Office Themes: Office2007, Office2010, Office2016 (Colorful, DarkGray, White, Black), Metro
- Flexible Orientation: Horizontal or Vertical layout
- Tooltip Support: Display additional information on hover
- Custom Styling: Gradient colors, highlight/selection colors, border customization
Key Namespace:
Syncfusion.Windows.Forms.ToolsAssembly: (and dependencies)
Syncfusion.Tools.Windows.dllRatingControl（）是一款多功能的评分输入控件，支持：
Syncfusion.Windows.Forms.Tools.RatingControl- 6种内置形状： 星形、圆形、三角形、心形、菱形、风筝形
- 自定义图片： 使用你自己的图片资源作为独特的评分指示器
- 精度模式： 标准（完整形状）或半星（半形状粒度）
- Office主题： Office2007、Office2010、Office2016（多彩、深灰、白色、黑色）、Metro
- 灵活的布局方向： 水平或垂直布局
- 工具提示支持： 鼠标悬停时展示额外信息
- 自定义样式： 渐变颜色、高亮/选中颜色、边框自定义
核心命名空间：
Syncfusion.Windows.Forms.Tools程序集： （及相关依赖）
Syncfusion.Tools.Windows.dllDocumentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
When to read: User needs to install, configure, or create their first Rating control.
Topics covered:
- Assembly deployment and NuGet package installation
- Adding Rating control via designer (toolbox)
- Adding Rating control via code
- Setting rating values with the Value property
- Built-in shapes quick overview
- Basic implementation examples
📄 阅读： references/getting-started.md
适用场景： 用户需要安装、配置或者创建第一个Rating控件时。
涵盖主题：
- 程序集部署和NuGet包安装
- 通过设计器（工具箱）添加Rating控件
- 通过代码添加Rating控件
- 使用Value属性设置评分值
- 内置形状快速概览
- 基础实现示例
Shapes and Customization
形状与自定义
📄 Read: references/shapes-and-customization.md
When to read: User wants built-in shapes (star, heart, circle) or needs custom image-based rating indicators.
Topics covered:
- 6 Built-in shapes: Star, Circle, Triangle, Heart, Diamond, Kite
- Changing shapes with the Shape property
- Custom image shapes using CustomImageCollection
- NormalImage, HoverImage, SelectedImage configuration
- Custom image fallback behavior
- Half-image support for precision modes
📄 阅读： references/shapes-and-customization.md
适用场景： 用户想要使用内置形状（星形、心形、圆形）或者需要基于自定义图片的评分指示器时。
涵盖主题：
- 6种内置形状：星形、圆形、三角形、心形、菱形、风筝形
- 使用Shape属性修改形状
- 使用CustomImageCollection实现自定义图片形状
- NormalImage、HoverImage、SelectedImage配置
- 自定义图片降级逻辑
- 精度模式的半图支持
Precision and Values
精度与数值
📄 Read: references/precision-and-values.md
When to read: User needs half-star ratings (3.5 stars) or wants to control rating granularity.
Topics covered:
- Precision modes: Standard vs Half
- Half-star/half-shape rating configuration
- Value property for setting and retrieving ratings
- Precision with built-in shapes
- Precision with custom images (requires half-images)
- Rating value ranges and increments
📄 阅读： references/precision-and-values.md
适用场景： 用户需要半星评分（3.5星）或者想要控制评分粒度时。
涵盖主题：
- 精度模式：标准 vs 半星
- 半星/半形评分配置
- 用于设置和获取评分的Value属性
- 内置形状的精度适配
- 自定义图片的精度适配（需要半图资源）
- 评分值范围和步长
Styling and Appearance
样式与外观
📄 Read: references/styling-and-appearance.md
When to read: User wants Office themes, custom colors, gradient effects, or visual style customization.
Topics covered:
- Visual styles: Default, Office2007, Office2010, Metro
- Office2016 variants: Colorful, DarkGray, White, Black
- OfficeColorScheme property (Blue, Silver, Black)
- Custom gradient coloring with ApplyGradientColors
- ItemHighlight and ItemSelection color properties
- BackColor and BorderColor customization
📄 阅读： references/styling-and-appearance.md
适用场景： 用户想要使用Office主题、自定义颜色、渐变效果或者自定义视觉样式时。
涵盖主题：
- 视觉样式：默认、Office2007、Office2010、Metro
- Office2016变体：多彩、深灰、白色、黑色
- OfficeColorScheme属性（蓝色、银色、黑色）
- 通过ApplyGradientColors实现自定义渐变配色
- ItemHighlight和ItemSelection颜色属性
- 背景色和边框色自定义
Orientation and Tooltips
布局方向与工具提示
📄 Read: references/orientation-and-tooltips.md
When to read: User needs vertical rating layout or wants tooltips on rating items.
Topics covered:
- Horizontal and Vertical orientation modes
- Orientation property configuration
- Tooltip enablement with ShowTooltip
- Tooltip appearance customization
- Layout considerations for vertical ratings
📄 阅读： references/orientation-and-tooltips.md
适用场景： 用户需要垂直评分布局或者想要给评分项添加工具提示时。
涵盖主题：
- 水平和垂直布局模式
- Orientation属性配置
- 通过ShowTooltip启用工具提示
- 工具提示外观自定义
- 垂直评分的布局注意事项
Quick Start Example
快速入门示例
Basic Star Rating (5 Stars)
基础星级评分（5星）
csharp
using Syncfusion.Windows.Forms.Tools;
// Create rating control
RatingControl productRating = new RatingControl();
productRating.Location = new Point(20, 20);
productRating.Size = new Size(150, 30);
// Set initial value (3 out of 5 stars)
productRating.Value = 3;
// Add to form
this.Controls.Add(productRating);csharp
using Syncfusion.Windows.Forms.Tools;
// 创建评分控件
RatingControl productRating = new RatingControl();
productRating.Location = new Point(20, 20);
productRating.Size = new Size(150, 30);
// 设置初始值（5星中的3星）
productRating.Value = 3;
// 添加到表单
this.Controls.Add(productRating);Half-Star Precision Rating
半星精度评分
csharp
// Enable half-star precision
RatingControl preciseRating = new RatingControl();
preciseRating.Precision = PrecisionMode.Half;
preciseRating.Value = 3.5f; // 3.5 starscsharp
// 启用半星精度
RatingControl preciseRating = new RatingControl();
preciseRating.Precision = PrecisionMode.Half;
preciseRating.Value = 3.5f; // 3.5星Custom Shape (Hearts for Favorites)
自定义形状（心形收藏）
csharp
// Use heart shapes instead of stars
RatingControl favoriteRating = new RatingControl();
favoriteRating.Shape = Shapes.Heart;
favoriteRating.Value = 4;csharp
// 用心形代替星形
RatingControl favoriteRating = new RatingControl();
favoriteRating.Shape = Shapes.Heart;
favoriteRating.Value = 4;Office 2016 Themed Rating
Office 2016主题评分
csharp
// Apply Office 2016 Colorful theme
RatingControl themedRating = new RatingControl();
themedRating.Style = RatingControl.Style.Office2016Colorful;
themedRating.Value = 5;csharp
// 应用Office 2016多彩主题
RatingControl themedRating = new RatingControl();
themedRating.Style = RatingControl.Style.Office2016Colorful;
themedRating.Value = 5;Common Patterns
常见实现模式
Product Review Rating (Read-Only Display)
产品评价评分（只读展示）
csharp
// Display average rating (read-only)
RatingControl avgRating = new RatingControl();
avgRating.Value = 4.5f;
avgRating.Precision = PrecisionMode.Half;
avgRating.Enabled = false; // Read-onlyWhen to use: Displaying aggregated ratings on product listings.
csharp
// 展示平均评分（只读）
RatingControl avgRating = new RatingControl();
avgRating.Value = 4.5f;
avgRating.Precision = PrecisionMode.Half;
avgRating.Enabled = false; // 只读适用场景： 在产品列表页展示聚合评分。
Interactive Feedback Form
可交互反馈表单
csharp
// User can select rating
RatingControl feedbackRating = new RatingControl();
feedbackRating.Value = 0; // No initial selection
feedbackRating.Precision = PrecisionMode.Half;
// Handle rating changes
feedbackRating.RatingChanged += (s, e) => {
float rating = feedbackRating.Value;
MessageBox.Show($"User rated: {rating} stars");
};When to use: Customer feedback forms, surveys, review submission.
csharp
// 用户可以选择评分
RatingControl feedbackRating = new RatingControl();
feedbackRating.Value = 0; // 无初始选择
feedbackRating.Precision = PrecisionMode.Half;
// 处理评分变化
feedbackRating.RatingChanged += (s, e) => {
float rating = feedbackRating.Value;
MessageBox.Show($"用户评分: {rating} 星");
};适用场景： 客户反馈表单、调研、评价提交。
Vertical Rating Layout
垂直评分布局
csharp
// Vertical orientation for sidebar layouts
RatingControl verticalRating = new RatingControl();
verticalRating.Orientation = Orientationmode.Vertical;
verticalRating.Size = new Size(50, 200);
verticalRating.Value = 3;When to use: Sidebar designs, narrow column layouts.
csharp
// 侧边栏布局使用垂直方向
RatingControl verticalRating = new RatingControl();
verticalRating.Orientation = Orientationmode.Vertical;
verticalRating.Size = new Size(50, 200);
verticalRating.Value = 3;适用场景： 侧边栏设计、窄列布局。
Custom Color Gradient Rating
自定义渐变色评分
csharp
// Custom gradient colors (green to yellow)
RatingControl customRating = new RatingControl();
customRating.ApplyGradientColors = true;
customRating.ItemHighlightStartColor = Color.Green;
customRating.ItemHighlightEndColor = Color.YellowGreen;
customRating.ItemSelectionStartColor = Color.Gold;
customRating.ItemSelectionEndColor = Color.Orange;
customRating.Value = 4;When to use: Branded color schemes, matching application themes.
csharp
// 自定义渐变颜色（绿到黄）
RatingControl customRating = new RatingControl();
customRating.ApplyGradientColors = true;
customRating.ItemHighlightStartColor = Color.Green;
customRating.ItemHighlightEndColor = Color.YellowGreen;
customRating.ItemSelectionStartColor = Color.Gold;
customRating.ItemSelectionEndColor = Color.Orange;
customRating.Value = 4;适用场景： 品牌配色方案、适配应用主题。
Custom Image Rating
自定义图片评分
csharp
// Use custom images for rating
RatingControl customImageRating = new RatingControl();
customImageRating.Shape = Shapes.CustomImages;
CustomImageCollection images = new CustomImageCollection();
images.NormalImage = Properties.Resources.rating_normal;
images.HoverImage = Properties.Resources.rating_hover;
images.SelectedImage = Properties.Resources.rating_selected;
customImageRating.Images = images;
customImageRating.Value = 3;When to use: Unique branding, custom icons, non-standard rating indicators.
csharp
// 使用自定义图片作为评分图标
RatingControl customImageRating = new RatingControl();
customImageRating.Shape = Shapes.CustomImages;
CustomImageCollection images = new CustomImageCollection();
images.NormalImage = Properties.Resources.rating_normal;
images.HoverImage = Properties.Resources.rating_hover;
images.SelectedImage = Properties.Resources.rating_selected;
customImageRating.Images = images;
customImageRating.Value = 3;适用场景： 独特品牌风格、自定义图标、非标准评分指示器。
Key Properties
核心属性
Core Properties
基础属性
| Property | Type | Description | When to Use |
|---|---|---|---|
| Value | | Current rating value (0 to number of items) | Set/get rating selection |
| Precision | | Standard or Half precision | Enable half-star ratings |
| Shape | | Star, Circle, Triangle, Heart, Diamond, Kite, CustomImages | Change rating indicator shape |
| Orientation | | Horizontal or Vertical | Vertical layout for sidebars |
| ShowTooltip | | Enable tooltips on rating items | Show rating values on hover |
| 属性 | 类型 | 描述 | 适用场景 |
|---|---|---|---|
| Value | | 当前评分值（0到评分项总数） | 设置/获取评分选择结果 |
| Precision | | 标准或半星精度 | 启用半星评分 |
| Shape | | 星形、圆形、三角形、心形、菱形、风筝形、自定义图片 | 修改评分指示器形状 |
| Orientation | | 水平或垂直 | 侧边栏使用垂直布局 |
| ShowTooltip | | 启用评分项的工具提示 | 悬停时展示评分数值 |
Styling Properties
样式属性
| Property | Type | Description | When to Use |
|---|---|---|---|
| Style | | Visual style (Office2007/2010/2016, Metro) | Apply Office themes |
| OfficeColorScheme | | Blue, Silver, Black color scheme | Office theme color variants |
| ApplyGradientColors | | Enable gradient color properties | Custom gradient effects |
| ItemHighlightColor | | Hover state color | Custom hover appearance |
| ItemSelectionColor | | Selected state color | Custom selection appearance |
| 属性 | 类型 | 描述 | 适用场景 |
|---|---|---|---|
| Style | | 视觉样式（Office2007/2010/2016、Metro） | 应用Office主题 |
| OfficeColorScheme | | 蓝色、银色、黑色配色方案 | Office主题颜色变体 |
| ApplyGradientColors | | 启用渐变颜色属性 | 自定义渐变效果 |
| ItemHighlightColor | | 悬停状态颜色 | 自定义悬停外观 |
| ItemSelectionColor | | 选中状态颜色 | 自定义选中外观 |
Custom Image Properties
自定义图片属性
| Property | Type | Description | When to Use |
|---|---|---|---|
| Images | | Custom image collection | Use custom rating images |
| Images.NormalImage | | Unselected state image | Custom default appearance |
| Images.HoverImage | | Hover state image | Custom hover appearance |
| Images.SelectedImage | | Selected state image | Custom selected appearance |
| 属性 | 类型 | 描述 | 适用场景 |
|---|---|---|---|
| Images | | 自定义图片集合 | 使用自定义评分图片 |
| Images.NormalImage | | 未选中状态图片 | 自定义默认外观 |
| Images.HoverImage | | 悬停状态图片 | 自定义悬停外观 |
| Images.SelectedImage | | 选中状态图片 | 自定义选中外观 |
Common Use Cases
常见使用场景
1. Product Rating Display
1. 产品评分展示
Scenario: E-commerce product listing with average ratings.
- Use to display average (e.g., 4.3 stars)
Value - Set for accurate display
Precision = PrecisionMode.Half - Set for read-only
Enabled = false - Read: precision-and-values.md
场景： 电商产品列表页展示平均评分。
- 使用展示平均值（例如4.3星）
Value - 设置实现精准展示
Precision = PrecisionMode.Half - 设置实现只读效果
Enabled = false - 阅读：precision-and-values.md
2. Customer Feedback Form
2. 客户反馈表单
Scenario: Service quality rating in feedback form.
- Use for no initial selection
Value = 0 - Handle event to capture user input
RatingChanged - Apply Office2016 theme for professional appearance
- Read: getting-started.md, styling-and-appearance.md
场景： 反馈表单中的服务质量评分。
- 设置无初始选择
Value = 0 - 监听事件捕获用户输入
RatingChanged - 应用Office2016主题实现专业外观
- 阅读：getting-started.md、styling-and-appearance.md
3. Multi-Criteria Rating
3. 多维度评分
Scenario: Rate multiple aspects (Quality, Service, Value).
- Create multiple RatingControl instances
- Use descriptive labels for each rating
- Consistent shape and style across all ratings
- Read: shapes-and-customization.md
场景： 对多个维度评分（质量、服务、性价比）。
- 创建多个RatingControl实例
- 为每个评分项添加描述标签
- 所有评分控件保持形状和样式统一
- 阅读：shapes-and-customization.md
4. Favorite/Like System
4. 收藏/点赞系统
Scenario: Heart-based favorites (1-5 hearts).
- Set
Shape = Shapes.Heart - Use custom colors for romantic/favorite themes
- Read: shapes-and-customization.md
场景： 基于心形的收藏功能（1-5颗心）。
- 设置
Shape = Shapes.Heart - 使用自定义颜色适配浪漫/收藏主题
- 阅读：shapes-and-customization.md
5. Branded Rating UI
5. 品牌化评分UI
Scenario: Custom images matching brand identity.
- Use
Shape = Shapes.CustomImages - Provide NormalImage, HoverImage, SelectedImage
- Include HalfImages for precision support
- Read: shapes-and-customization.md
场景： 匹配品牌标识的自定义图片。
- 使用
Shape = Shapes.CustomImages - 提供NormalImage、HoverImage、SelectedImage资源
- 包含半图资源支持精度模式
- 阅读：shapes-and-customization.md
6. Vertical Rating Sidebar
6. 垂直评分侧边栏
Scenario: Sidebar with vertical rating display.
- Set
Orientation = Orientationmode.Vertical - Adjust Size for vertical layout
- Use tooltips for value display
- Read: orientation-and-tooltips.md
场景： 侧边栏展示垂直排列的评分。
- 设置
Orientation = Orientationmode.Vertical - 调整Size适配垂直布局
- 使用工具提示展示数值
- 阅读：orientation-and-tooltips.md
Events
事件
RatingChanged: Raised when the rating value changes (user interaction).
csharp
ratingControl1.RatingChanged += (sender, e) => {
float newRating = ratingControl1.Value;
// Process rating change
};RatingChanged： 评分值发生变化时触发（用户交互导致）。
csharp
ratingControl1.RatingChanged += (sender, e) => {
float newRating = ratingControl1.Value;
// 处理评分变化
};Best Practices
最佳实践
- Precision for Averages: Use when displaying aggregated ratings (4.5 stars)
PrecisionMode.Half - Read-Only Display: Set for non-interactive rating displays
Enabled = false - Consistent Shapes: Use the same shape across related rating controls
- Tooltips for Clarity: Enable to show numeric values
ShowTooltip - Custom Images: Provide all image states (Normal, Hover, Selected, HalfNormal, HalfSelected) for complete custom experience
- Theme Consistency: Match rating style to application theme (Office2016 variants)
- Value Initialization: Set for new ratings, specific value for defaults
Value = 0
- 平均值使用半星精度： 展示聚合评分（4.5星）时使用
PrecisionMode.Half - 只读展示设置： 非交互的评分展示设置
Enabled = false - 形状保持统一： 相关的评分控件使用相同的形状
- 工具提示提升清晰度： 启用展示数值
ShowTooltip - 自定义图片规范： 提供所有状态的图片资源（正常、悬停、选中、半正常、半选中）实现完整的自定义体验
- 主题一致性： 评分样式与应用主题保持匹配（Office2016变体）
- 值初始化： 新建评分设置，有默认值的场景设置对应数值
Value = 0
Related Skills
相关技能
- NumericUpDown: Alternative numeric input for precise values
- TrackBar: Slider-based rating alternative
- CheckBox/RadioButton: Binary or single-choice rating alternatives
- NumericUpDown： 精准数值输入的替代方案
- TrackBar： 滑动条形式的评分替代方案
- CheckBox/RadioButton： 二选一或单选形式的评分替代方案