syncfusion-winforms-rating

实现 Syncfusion WinForms 评分控件

评分控件提供直观的可视化评分体验，允许用户选择一定数量的星形（或其他形状）来表示评分值。此控件非常适合用户反馈、产品评价、质量评分，以及任何需要可视化评分输入的场景。

何时使用此技能

在用户需要以下功能时使用此技能：

• 星级评分系统： 产品评分、评价、带 1-5 星评分的用户反馈
• 自定义评分形状： 用于收藏的爱心、用于质量评分的菱形、用于简洁显示的圆形
• 半星评分： 精细的评分精度（3.5 星、4.5 星），用于详细反馈
• 反馈表单： 客户满意度、服务质量、体验评分
• 评价界面： 电影评分、图书评价、应用商店评分
• 评分显示： 显示只读评分或交互式评分输入
• 主题化评分控件： Office 2007/2010/2016 样式，保持一致的 UI 外观
• 垂直/水平布局： 根据表单设计调整评分方向

组件概览

RatingControl（Syncfusion.Windows.Forms.Tools.RatingControl）是一款多功能评分输入控件，支持：

• 6 种内置形状： 星形、圆形、三角形、爱心、菱形、风筝形
• 自定义图像： 使用自己的图像资源创建独特的评分指示器
• 精度模式： 标准（完整形状）或半形（以半个形状为粒度）
• Office 主题： Office2007、Office2010、Office2016（Colorful、DarkGray、White、Black）、Metro
• 灵活的方向： 水平或垂直布局
• 工具提示支持： 悬停时显示其他信息
• 自定义样式： 渐变颜色、高亮/选中颜色、边框自定义

关键命名空间： Syncfusion.Windows.Forms.Tools

程序集： Syncfusion.Tools.Windows.dll（及其依赖项）

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 用户需要安装、配置或创建第一个评分控件。

涵盖主题：

• 程序集部署和 NuGet 包安装
• 通过设计器（工具箱）添加评分控件
• 通过代码添加评分控件
• 使用 Value 属性设置评分值
• 内置形状快速概览
• 基本实现示例

形状与自定义

📄 阅读： references/shapes-and-customization.md

阅读时机： 用户想使用内置形状（星形、爱心、圆形），或需要基于自定义图像的评分指示器。

涵盖主题：

• 6 种内置形状：星形、圆形、三角形、爱心、菱形、风筝形
• 使用 Shape 属性更改形状
• 使用 CustomImageCollection 设置自定义图像形状
• NormalImage、HoverImage、SelectedImage 配置
• 自定义图像回退行为
• 精度模式的半图像支持

精度与值

📄 阅读： references/precision-and-values.md

阅读时机： 用户需要半星评分（3.5 星），或想要控制评分粒度。

涵盖主题：

• 精度模式：标准与半形
• 半星/半形评分配置
• 用于设置和获取评分的 Value 属性
• 内置形状的精度设置
• 自定义图像的精度设置（需要半形图像）
• 评分值范围和增量

样式与外观

📄 阅读： references/styling-and-appearance.md

阅读时机： 用户想使用 Office 主题、自定义颜色、渐变效果或自定义视觉样式。

涵盖主题：

• 视觉样式：Default、Office2007、Office2010、Metro
• Office2016 变体：Colorful、DarkGray、White、Black
• OfficeColorScheme 属性（Blue、Silver、Black）
• 使用 ApplyGradientColors 自定义渐变颜色
• ItemHighlight 和 ItemSelection 颜色属性
• BackColor 和 BorderColor 自定义

布局方向和工具提示

📄 阅读： references/orientation-and-tooltips.md

阅读时机： 用户需要垂直评分布局，或希望在评分项上显示工具提示时。

涵盖主题：

• 水平和垂直布局方向模式
• 布局方向属性配置
• 使用 ShowTooltip 启用工具提示
• 自定义工具提示外观
• 垂直评分的布局注意事项

---

快速入门示例

基本星级评分（5 颗星）

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

半星精度评分

// Enable half-star precision
RatingControl preciseRating = new RatingControl();
preciseRating.Precision = PrecisionMode.Half;
preciseRating.Value = 3.5f; // 3.5 stars

自定义形状（收藏用心形）

// Use heart shapes instead of stars
RatingControl favoriteRating = new RatingControl();
favoriteRating.Shape = Shapes.Heart;
favoriteRating.Value = 4;

Office 2016 主题评分

// Apply Office 2016 Colorful theme
RatingControl themedRating = new RatingControl();
themedRating.VisualStyle  = RatingControl.Style.Office2016Colorful;
themedRating.Value = 5;

---

常见模式

产品评价评分（只读显示）

// Display average rating (read-only)
RatingControl avgRating = new RatingControl();
avgRating.Value = 4.5f;
avgRating.Precision = PrecisionMode.Half;
avgRating.Enabled = false; // Read-only

适用场景： 在商品列表中显示汇总评分。

交互式反馈表单

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

适用场景： 客户反馈表单、调查问卷、提交评价。

垂直评分布局

// Vertical orientation for sidebar layouts
RatingControl verticalRating = new RatingControl();
verticalRating.Orientation = Orientationmode.Vertical;
verticalRating.Size = new Size(50, 200);
verticalRating.Value = 3;

适用场景： 侧边栏设计、窄列布局。

自定义渐变色评分

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

适用场景： 品牌配色方案、与应用主题相匹配的配色。

自定义图像评分

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

适用场景： 独特品牌标识、自定义图标、非标准评分指示器。

---

关键属性

核心属性

属性	类型	描述	适用场景
Value	float	当前评分值（0 到项目数）	设置/获取评分选择
Precision	PrecisionMode	标准或半星精度	启用半星评分
Shape	Shapes	星形、圆形、三角形、心形、菱形、风筝形、自定义图像	更改评分指示器形状
Orientation	Orientationmode	水平或垂直	用于侧边栏的垂直布局
ShowTooltip	bool	在评分项上启用工具提示	悬停时显示评分值

样式属性

属性	类型	描述	适用场景
VisualStyle	RatingControl.Style	视觉样式（Office2007/2010/2016、Metro）	应用 Office 主题
OfficeColorScheme	OfficeColorSchemes	蓝色、银色、黑色配色方案	Office 主题配色变体
ApplyGradientColors	bool	启用渐变色属性	自定义渐变效果
ItemHighlightColor	Color	悬停状态颜色	自定义悬停外观
ItemSelectionColor	Color	选中状态颜色	自定义选中外观

自定义图像属性

属性	类型	描述	适用场景
Images	CustomImageCollection	自定义图像集合	使用自定义评分图像
Images.NormalImage	Image	未选中状态图像	自定义默认外观
Images.HoverImage	Image	悬停状态图像	自定义悬停外观
Images.SelectedImage	Image	选中状态图像	自定义选中外观

---

常见使用场景

1. 产品评分显示

场景： 显示平均评分的电商商品列表。

• 使用 Value 显示平均值（例如，4.3 颗星）
• 设置 Precision = PrecisionMode.Half 以准确显示
• 设置 Enabled = false 设为只读
• 阅读：precision-and-values.md

2. 客户反馈表单

场景： 在反馈表单中对服务质量进行评分。

• 使用 Value = 0，不设置初始选项
• 处理 ValueChanged 事件以捕获用户输入
• 应用 Office2016 主题，呈现专业外观
• 阅读：getting-started.md、styling-and-appearance.md

3. 多项指标评分

场景： 对多个方面（质量、服务、性价比）进行评分。

• 创建多个 RatingControl 实例
• 为每项评分使用描述性标签
• 所有评分使用一致的形状和样式
• 阅读：shapes-and-customization.md

4. 收藏/点赞系统

场景： 基于爱心的收藏（1 到 5 颗心）。

• 设置 Shape = Shapes.Heart
• 为浪漫或收藏主题使用自定义颜色
• 阅读：shapes-and-customization.md

5. 品牌化评分 UI

场景： 使用符合品牌形象的自定义图像。

• 使用 Shape = Shapes.CustomImages
• 提供 NormalImage、HoverImage、SelectedImage
• 添加 HalfImages 以支持精确评分
• 阅读：shapes-and-customization.md

6. 垂直评分侧边栏

场景： 在侧边栏中垂直显示评分。

• 设置 Orientation = Orientationmode.Vertical
• 调整 Size 以适应垂直布局
• 使用工具提示显示数值
• 阅读：orientation-and-tooltips.md

---

事件

RatingChanged： 评分值发生变化时触发（用户交互）。

ratingControl1.RatingChanged  += (sender, e) => {
    float newRating = ratingControl1.Value;
    // Process rating change
};

---

最佳实践

1. 平均分精度： 显示汇总评分（4.5 颗星）时，使用 PrecisionMode.Half
2. 只读显示： 对不可交互的评分显示设置 Enabled = false
3. 形状一致： 相关评分控件使用相同形状
4. 使用工具提示提升清晰度： 启用 ShowTooltip 以显示数值
5. 自定义图像： 提供所有图像状态（Normal、Hover、Selected、HalfNormal、HalfSelected），以实现完整的自定义体验
6. 主题一致性： 使评分样式与应用主题（Office2016 variants）相匹配
7. 初始化数值： 新评分设置 Value = 0，默认评分则设置为指定值

---

另请参阅

• Syncfusion Rating Control 文档
• RatingControl API 参考