syncfusion-wpf-rating

Syncfusion WPF Rating の実装

WPF 用の SfRating コントロールは、ユーザーが項目を評価できる、星を使った視覚的な評価システムを提供します。精度モードの設定、幅広い外観のカスタマイズ、ツールチップ、読み取り専用表示に対応しています。映画、アプリケーション、製品、サービスの評価など、評価インターフェイスを通じてユーザーからフィードバックを得る必要があるあらゆる場面で、このコントロールを使用してください。

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

次のような場合に、このスキルを使用してください。

• WPF アプリケーションに星を使った評価コントロールを実装する
• 製品やサービスの評価インターフェイスを作成する
• 視覚的な評価フィードバックを備えたレビューシステムを構築する
• 読み取り専用の評価（平均評価、過去の評価など）を表示する
• 評価の精度（星全体、半分の星、または正確な値）を設定する
• 評価の外観（色、サイズ、間隔、ホバー効果）をカスタマイズする
• 評価値を表示するツールチップを追加する
• ValueChanged イベントで評価値の変更を処理する
• 評価コントロールをデータバインディングのシナリオに統合する

コンポーネントの概要

SfRating では、次の機能を利用できます。

• 評価項目の数を設定可能（通常は星 5 個）
• 3 種類の精度モード：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. Half 精度の評価

<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. 製品レビュー - E コマースアプリケーションで製品評価を表示・収集します
2. サービスへのフィードバック - サービスに対するユーザーの満足度評価を収集します
3. 映画／コンテンツの評価 - メディアコンテンツの評価を表示し、投稿できるようにします
4. パフォーマンス評価 - 評価用の視覚的な評価尺度として使用します
5. アンケートの回答 - アンケートで評価尺度の質問に使用します
6. ダッシュボードの指標 - KPI や品質スコアを視覚的な評価として表示します
7. ユーザープロフィール - ユーザーの評判やスキルレベルの評価を表示します
8. 比較ツール - 評価済み項目を視覚的に比較します

ベストプラクティス

• シンプルな星1～5個の評価には、Standard 精度を使用します
• より細かなフィードバックには、Half 精度（0.5刻み）を使用します
• 計算値へのバインドや正確な入力を可能にする場合は、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 - 範囲値の選択