syncfusion-winui-rating

評価コントロールの実装（SfRating）

Syncfusion WinUI 評価コントロール（SfRating）は、数値スケールでユーザーが評価を入力または表示できる直感的なインターフェイスを提供します。レビュー、フィードバックシステム、評価の表示に最適で、さまざまな精度モード、カスタムテンプレート、豊富なスタイル設定に対応しています。

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

次のような場合に評価コントロールを使用します。

• ユーザーフィードバックを収集する - 商品、サービス、映画、アプリケーションの評価を収集する
• 既存の評価を表示する - 読み取り専用モードで平均評価やユーザーのスコアを表示する
• レビューシステムを作成する - 包括的なレビューおよび評価インターフェイスを構築する
• フィードバックフォームを実装する - アンケートやフィードバックフォームに評価入力を追加する
• 満足度を表示する - 絵文字や星を使った満足度スケールを表示する
• 精度の高い評価に対応する - 整数、半分単位、または任意の小数の評価を可能にする

トリガーキーワード: 評価、星、星評価、SfRating、レビュー、フィードバック、スコア、ユーザー評価、半分の星、精度、絵文字評価、満足度、商品評価

コンポーネントの概要

コントロール: SfRating
名前空間: Syncfusion.UI.Xaml.Editors
NuGet パッケージ: Syncfusion.Editors.WinUI
プラットフォーム: WinUI 3 デスクトップ（.NET 5 以降）

主な機能

• 柔軟な初期化 - Items コレクションまたは ItemsCount プロパティを使用
• 精度モード - Full（整数）、Half（0.5 刻み）、Exact（任意の小数）
• カスタムテンプレート - 星、ハート、絵文字、画像、またはカスタム図形
• スタイル設定 - 評価済み／未評価の外観、サイズ、向きをカスタマイズ
• 読み取り専用モード - ユーザーの操作を許可せずに評価を表示
• ツールチップ対応 - カスタム書式でホバー時に評価値を表示
• クリア機能 - ユーザーが評価をリセットできるようにする
• プレースホルダー値 - ユーザー入力前に平均評価を表示
• アクセシビリティ - キーボードによる完全なナビゲーションとスクリーンリーダーに対応

ドキュメントとナビゲーションガイド

はじめにと基本的な使用方法

📄 参照: references/getting-started.md

• Syncfusion.Editors.WinUI NuGet パッケージのインストール
• WinUI 3 デスクトップアプリケーションの作成
• Syncfusion.UI.Xaml.Editors 名前空間のインポート
• XAML と C# での SfRating コントロールの初期化
• SfRatingItem を使った Items コレクション方式の使用
• ItemsCount 方式（より簡単な方法）の使用
• プログラムによる評価値の設定
• 評価機能の完全な実装例

精度モード

📄 参照: references/precision.md

• Precision プロパティについて
• Full 精度モード（整数のみ：1、2、3 など）
• Half 精度モード（半分刻み：1.5、2.5、3.5 など）
• Exact 精度モード（任意の小数値：2.7、3.2 など）
• 各モードでのユーザー操作の動作
• ユースケースに適した精度の選択
• 各精度タイプを示す例

カスタマイズオプション

📄 参照: references/customization.md references/customization-advanced.md

• 評価済み項目と未評価項目のスタイル設定（RatedItemStyle、UnratedItemStyle）
• 項目サイズの調整（ItemSize プロパティ）
• 向きの変更（横または縦）
• 表示用の読み取り専用モード（IsReadOnly）
• 評価をクリアする機能（IsClearEnabled）
• プレースホルダー値の表示（PlaceholderValue）
• 複数のカスタマイズオプションの組み合わせ
• 実際の使用例を示すスタイル設定の完全な例

テンプレートとカスタムビジュアル

📄 参照: references/templates.md

• ItemTemplateSelector の概要
• パスベースのテンプレートの作成（ハート、カスタム図形）
• 画像ベースのテンプレートの実装（絵文字評価）
• 評価項目としてのフォントアイコンの使用
• カスタム DataTemplateSelector クラスの作成
• 選択状態と未選択状態の管理
• 絵文字評価の完全な実装
• ハート評価の完全な実装

ツールチップの機能

📄 参照: references/tooltip-features.md references/tooltip-customization.md

• ホバー時にツールチップを有効にする（EnableToolTip プロパティ）
• ツールチップの内容をフォーマットする（ToolTipFormat プロパティ）
• 標準の数値書式文字列を使用する
• カスタム書式パターンを作成する
• ツールチップでユーザーへのフィードバックを強化する
• ツールチップによるアクセシビリティ上のメリット
• テーマに合わせてツールチップのスタイルを調整する

クイックスタートの例

基本的な5つ星評価

XAML:

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

using Syncfusion.UI.Xaml.Editors;

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

よく使われるパターン

1. 標準的な5つ星評価

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

2. 半星評価システム

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

3. 読み取り専用の評価表示

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

4. ツールチップ付き評価

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

5. 大きな評価項目

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

6. 垂直方向の評価

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

7. プレースホルダー付き評価

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

8. クリア可能な評価

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

主なプロパティ

プロパティ	型	デフォルト	説明
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	カスタムのビジュアルテンプレート

プロパティの使用上のヒント

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: 一度設定した評価はクリアできず、変更のみ可能です

よくあるユースケース

商品レビューシステム

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

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

平均評価の表示

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

満足度アンケート

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

映画評価インターフェース

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

ベストプラクティス

ユーザーエクスペリエンス

• 精度の選択: シンプルな評価には Full、商品評価には Half、表示専用には Exact を使用します
• 明確なフィードバック: ツールチップを有効にして正確な値を表示します
• 適切なサイズ: 標準的なフォームでは24～32px、目立たせる評価には40～50pxを使用します
• プレースホルダー値: 平均評価を表示して、ユーザーの期待を導きます
• クリアを許可する: 評価が必須でない限り、IsClearEnabled を有効にします

ビジュアルデザイン

• 一貫したスタイル: アプリケーション全体で同じスタイルを使用します
• 十分な間隔: 項目が重なったり、窮屈に感じられたりしないようにします
• テーマへの適応: ライトテーマとダークテーマの両方でテストします
• 色のコントラスト: 塗りつぶし済みの項目と空の項目を明確に見分けられるようにします
• カスタムテンプレート: 認識しやすいアイコン（星、ハート、親指）を使用します

アクセシビリティ

• ツールチップを有効にする: すべてのユーザーが正確な値を理解しやすくなります
• キーボード操作: 評価コントロールは矢印キーによる操作に対応しています
• 読み取り専用の表示: 評価が表示専用の場合は、そのことが明確にわかるようにします
• ラベルとの関連付け: 説明的なテキストラベルを必ず含めます
• スクリーンリーダー: コントロールは現在の値と範囲を読み上げます

パフォーマンス

• ItemsCount：標準的な評価では 5、パフォーマンス評価では最大 10 を使用します
• テンプレート：複雑な画像よりもシンプルなテンプレートのほうがパフォーマンスに優れています
• データバインディング：リアクティブな更新を行うには、ViewModel のプロパティにバインドします

よくある間違いとその回避方法

• ❌ ユーザー入力に Exact 精度を使用する（精密な制御が難しいため）
• ❌ 表示専用の評価で IsReadOnly="True" を設定し忘れる
• ❌ 評価のラベルやコンテキストを提供しない
• ❌ 項目数を増やしすぎる（10 を超えると使いにくくなります）
• ❌ Half／Exact 精度の評価でツールチップを省略する
• ❌ Syncfusion.UI.Xaml.Editors 名前空間をインポートしない

トラブルシューティング

評価値が更新されない：

• IsReadOnly が false であることを確認します
• Value が正しくバインドされていることを確認します（TwoWay バインディング）
• 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" を設定します
• マウスオーバーが検出されていることを確認します（別の要素でもテストしてください）

イベント

ValueChanged：

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

---

詳細が必要ですか？ 詳細なドキュメントと例については、上記のナビゲーションガイドにリンクされているリファレンスファイルをお読みください。