syncfusion-winforms-rating

Syncfusion WinForms Rating Control の実装

Rating Control は、ユーザーが星（またはその他の形状）の数を選択して評価値を表せる、直感的な視覚的評価エクスペリエンスを提供します。このコントロールは、ユーザーからのフィードバック、製品レビュー、品質評価など、視覚的な評価入力が必要なあらゆるシナリオに最適です。

このスキルを使用する場面

ユーザーが以下を必要としている場合に、このスキルを使用します。

• 星評価システム： 1～5 個の星による製品評価、レビュー、ユーザーフィードバック
• カスタム評価形状： お気に入りを表すハート、品質を表すダイヤモンド、シンプルさを表す円
• 半星評価： 詳細なフィードバックのための細かな精度（3.5 星、4.5 星）
• フィードバックフォーム： 顧客満足度、サービス品質、体験の評価
• レビューインターフェイス： 映画の評価、書籍のレビュー、アプリストアの評価
• 評価の表示： 読み取り専用の評価の表示、またはインタラクティブな評価入力
• テーマ付き評価コントロール： 一貫した UI 表示を実現する Office 2007／2010／2016 スタイル
• 垂直／水平レイアウト： フォームのデザインに合わせた評価の向き

コンポーネントの概要

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

参照するタイミング： ユーザーが Rating コントロールをインストール、構成、または初めて作成する場合。

掲載トピック：

• アセンブリの配置と NuGet パッケージのインストール
• デザイナー（ツールボックス）から Rating コントロールを追加する
• コードから Rating コントロールを追加する
• 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	Star、Circle、Triangle、Heart、Diamond、Kite、CustomImages	評価インジケーターの図形を変更する
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. 商品評価の表示

シナリオ： 平均評価を表示する EC 商品一覧。

• 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 のバリエーション）に合わせます
7. 値の初期化： 新しい評価には Value = 0 を、デフォルト値がある場合は特定の値を設定します

---

関連項目

• Syncfusion Rating Control のドキュメント
• RatingControl API リファレンス