Rating (評価)

Ignite UI for Blazor Rating は、ユーザーが星またはカスタム シンボルのスケールでスコアを表示および選択できるフォーム関連のコンポーネントです。

Rating は、半星などの小数値、ホバー プレビュー、個別シンボルの単一選択、およびキーボードによる完全な入力をサポートします。

ライブ デモ

構造

Rating はラベルと値で構成されます。値は評価スケールの数値です。ラベルは label を設定すると表示されます。max を設定すると、シンボルの数を変更できます (既定値は 5)。

igc-rating 要素は、ラベルと、シンボルを保持するスライダーをレンダリングします。シンボルが投影されていない場合は、max の各ポイントに対して 1 つの星をレンダリングします。

igc-rating
└─ #shadow-root
   ├─ label[part="label"]                    // hidden when label isn't set
   └─ div[part="base"][role="slider"]
      ├─ div[part="symbols"]                 // aria-hidden="true"
      │  └─ slot[name="symbol"]              // projected igc-rating-symbol elements
      │     └─ igc-rating-symbol × max       // default stars when nothing is projected
      │        └─ #shadow-root
      │           ├─ div[part="symbol full"]   // star_filled icon, clipped to the value
      │           └─ div[part="symbol empty"]  // star_outlined icon, clipped to the rest
      └─ label[part="value-label"]
         └─ slot[name="value-label"]         // hidden when the slot is empty

各 igc-rating-symbol は、既定のスロットを full パートに、empty スロットを empty パートにレンダリングします。

はじめに

Blazor Rating を使用するには、基本的なプロジェクト設定について Ignite UI for Blazor はじめに トピックに従い、対象プラットフォーム用のコンポーネントを追加します。

Ignite UI for Blazor のサービスを登録します。

// in Program.cs file

builder.Services.AddIgniteUIBlazor();

IgbRating のクライアント リソース モジュールである IgbRatingModule の登録は任意です。コンポーネントは初めてレンダリングされるときにリソースを読み込みます。ただし、builder.Services.AddIgniteUIBlazor(typeof(IgbRatingModule)) のように指定すると、リソースを事前に読み込んだり、クライアント側でのみ作成される要素に対応したりできます (コンポーネント モジュールを参照)。

次に、ホスト ページにテーマ スタイルシートを追加します。

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />

登録後、ラベル付きで IgbRating をレンダリングします。

<IgbRating Label="Rate this product" />

Rating は 5 つの星をレンダリングし、値 0 から開始します。

使用方法

Blazor Rating は、製品、サービス、または体験のスコアを収集する場合や、ユーザーが変更できない平均スコアを表示する場合に使用します。

ホバー プレビュー

hoverPreview を設定すると、ユーザーがクリックする前に、ポインターの下の値までシンボルが塗りつぶされます。ポインターがシンボルから離れると、Blazor Rating は元の値を表示します。読み取り専用または無効な Rating では、プレビューは表示されません。

プレビューがオンの間、Rating はポインターの下の値とともに Hover を発生させます。

<IgbRating HoverPreview="true" Label="Rate this article" Hover="OnHover" />

@code {
    private string Hint { get; set; }

    private void OnHover(IgbNumberEventArgs e)
    {
        Hint = $"{e.Detail} stars";
    }
}

リセット

既定では、現在の値をクリックしても値は保持されます。allowReset を設定すると、ユーザーが現在の値を再度クリックしたときに Blazor Rating が 0 にリセットされます。

<IgbRating AllowReset="true" Label="Rate this song" />

読み取り専用

readOnly を設定すると、すべてのレビューの平均など、ユーザーが変更できないスコアを表示します。値は範囲内の任意の数値にでき、たとえば 4.3 の場合は 4 つのシンボルと 5 つ目の 30% が塗りつぶされます。読み取り専用の Blazor Rating はタブ順序に残ります。

<IgbRating ReadOnly="true" Value="4.3" Label="Average rating" />

レイアウト

label プロパティは、シンボルの上に表示ラベルをレンダリングし、支援技術に対して Blazor Rating に名前を付けます。現在のスコアなど、シンボルの横にカスタム コンテンツを表示するには、value-label スロットに配置します。

<IgbRating @bind-Value="Score" Label="Rate this product">
    <span slot="value-label">@Score of 5</span>
</IgbRating>

すべての Blazor Rating にアクセシブルな名前を付け、スケールに合った言葉で値を説明してください。

支援技術は、既定で値を “3 of 5” として読み上げます。このテキストを置き換えるには ValueFormat を設定します。Rating は {0} を値に、{1} を Max に置き換えるため、テキストのローカライズも可能です。

<IgbRating Label="Delivery speed" ValueFormat="{0} out of {1} stars" />

label を未設定のままにするとラベルが非表示になります。または、value-label スロットを使用してスコアを表示します。

操作状態

Blazor Rating は既定で有効です。無効にするには disabled を設定します。

<IgbRating Disabled="true" Value="3" Label="Rate this product" />

空/満たされた状態

Blazor Rating の value は、シンボルがどの程度満たされるかを設定します。既定値の 0 ではすべてのシンボルが空になり、max と等しい値ではすべてのシンボルが満たされます。

@bind-Value で値をバインドします。

<IgbRating @bind-Value="Score" Max="10" Label="Rate this movie" />

@code {
    private double Score { get; set; } = 3;
}

step を 0.5 に設定すると、ユーザーは半星を選択できます。

<IgbRating Step="0.5" Value="3.5" Label="Rate your stay" />

サイズ

Rating には、小、中、大の 3 つのサイズがあります。小、中、大のサイズでは、それぞれ 18px、24px、36px のシンボルがレンダリングされ、Blazor Rating は既定で中サイズを使用します。サイズを選択するには、CSS 変数 --ig-size を --ig-size-small、--ig-size-medium、または --ig-size-large に設定します。これらのプリセット以外のサイズにするには、--ig-rating-symbol-size を設定します。

.rating-small {
  --ig-size: var(--ig-size-small);
}

.rating-large {
  --ig-size: var(--ig-size-large);
}

.rating-custom {
  --ig-rating-symbol-size: 3rem;
}

<IgbRating Class="rating-large" Label="Rate this product" />

シンボル

既定では、Blazor Rating は星のアイコンをレンダリングします。他のシンボルを使用するには、スケールの各ポイントに対して IgbRatingSymbol を 1 つずつ Rating の内側に配置します。各評価シンボルは、値が覆う部分に既定のスロット コンテンツを、残りの部分に empty スロット コンテンツを表示します。そのため、同じコンテンツであっても両方のスロットを埋めてください。評価シンボルの数が max を設定し、Rating は設定した max を無視します。

次の Rating は、登録済みのハート アイコンを使用します。最初に、Icon トピックで説明されているようにアイコンを登録します。

<IgbRating Label="Rate this recipe">
    @for (var i = 0; i < 5; i++)
    {
        <IgbRatingSymbol>
            <IgbIcon IconName="favorite" Collection="material" />
            <IgbIcon IconName="favorite_border" Collection="material" slot="empty" />
        </IgbRatingSymbol>
    }
</IgbRating>

Rating は、テーマの満たされたシンボルと空のシンボルの色で、アイコンとテキストに色を付けます。empty スロット内のアイコン以外のコンテンツはグレースケールでレンダリングされるため、両方のスロットに同じ絵文字を入れると、選択済みまたは空のように見えます。

単一選択

single を設定すると、選択されたシンボルのみが満たされて表示されます。単一選択は、表情のスケールなど、各シンボルが 1 つの個別の値を表す場合に使用します。単一選択では、Blazor Rating は step を 1 とし、小数値を切り上げます。

<IgbRating Single="true" Label="How was your experience?">
    @foreach (var face in Faces)
    {
        <IgbRatingSymbol>
            <span>@face</span>
            <span slot="empty">@face</span>
        </IgbRatingSymbol>
    }
</IgbRating>

@code {
    private readonly string[] Faces = { "😣", "😔", "😐", "🙂", "😆" };
}

フォーム

Blazor の EditForm コンポーネントを使用し、Rating の値を @bind-Value でモデルのプロパティにバインドします。このバインディングは、ユーザーが値を変更したときに ValueChanged イベントを通じてモデルを更新します。

<EditForm Model="Review" OnSubmit="Submit">
    <IgbRating @bind-Value="Review.Score" Label="Rate your stay" />
    <button type="submit">Send</button>
</EditForm>

@code {
    private ReviewModel Review { get; set; } = new();

    private void Submit()
    {
        // Review.Score holds the value that the user selected.
    }

    public class ReviewModel
    {
        public double Score { get; set; }
    }
}

Rating には required 検証がありません。スコアを必須にするには、データを送信する前に値が 0 より大きいことを確認してください。

使用すべき場合と使用すべきでない場合

星は非常によく知られたランキング シンボルであり、他のシンボルは評価スケールとして認識されない場合があります。星をカスタム シンボルに置き換える場合は、その目的が明確であることを確認してください。同じ色の似た色合いや、色収差を生じる組み合わせなど、コントラストの低い色は避けてください。アイコンの選択は強調され、視覚的に明確に区別できる外観である必要があります。

プロパティ

Blazor Rating は、次のプロパティを公開します。完全な型定義については、API リファレンスを参照してください。

メソッド

Blazor Rating は、次のメソッドを公開します。ステップ メソッドは、変更イベントを発行せずに値を変更します。

イベント

Blazor Rating は、次のイベントを発行します。値を設定したりメソッドを呼び出したりしたときには、イベントを発行しません。

スタイル設定

Blazor Rating は、色とシンボル サイズをテーマから取得します。次の CSS 変数で変更できます。

igc-rating 要素は、次の CSS パートを公開します。

igc-rating 要素がエクスポートするのは、既定の星の symbol、full、empty パートのみです。投影された評価シンボルにスタイルを設定するには、igc-rating-symbol 要素の symbol、full、empty パートを使用します。

Sass テーマ

rating-theme 関数でテーマを作成し、tokens() ミックスインで含めます。この関数は $symbol-full-color、$symbol-empty-color、$label-color、$symbol-size などのパラメーターを受け取り、ミックスインは、含めたスコープに対応する --ig-rating-* 変数を出力します。

Sass 関数は igniteui-theming パッケージから提供されます。Sass のセットアップについては、テーマトピックを参照してください。

@use "igniteui-theming" as *;

$custom-rating-theme: rating-theme(
  $symbol-full-color: #e41c77,
  $symbol-empty-color: #a9b8cc,
  $label-color: #344b65
);

:root {
  @include tokens($custom-rating-theme);
}

CSS 変数

Sass ビルド ステップなしでローカルにスタイルを設定する必要がある場合は、Rating またはコンテナーに CSS 変数を設定し、その他のスタイルには CSS パートを使用します。

igc-rating {
  --ig-rating-symbol-full-color: #e41c77;
  --ig-rating-symbol-empty-color: #a9b8cc;
}

igc-rating::part(label) {
  font-weight: 600;
}

igc-rating-symbol::part(empty) {
  opacity: 0.6;
}

Tailwind によるスタイル設定

CSS 変数を設定する Tailwind の任意プロパティを使用して、Blazor Rating にスタイルを設定できます。最初に、Tailwind をセットアップしてください。

<IgbRating Label="Rate this product" Class="[--ig-rating-symbol-full-color:#7B9E89] [--ig-rating-symbol-size:2rem]" />

アクセシビリティ

Blazor Rating はスライダーです。ユーザーは Tab キーで移動し、矢印キーで値を変更し、ARIA 属性を通じて値を聞き取ります。

キーボード操作

Blazor Rating は、内部のスライダー要素 (base パート) のみがフォーカスを受け取るため、タブ ストップは 1 つです。無効な Rating はタブ順序から外れます。読み取り専用の Rating はタブ順序に残りますが、次のキーを無視するため、ページのスクロールなど、ブラウザーの既定の動作がそのまま維持されます。

Blazor Rating は、keydown でこれらのキーを次のように処理します。

• 既定の動作を防止するため、Rating にフォーカスがある間、矢印キー、Home、End でページはスクロールしません。
• キーを押し続けると、その動作が繰り返されます。
• Shift、Ctrl、Alt、Meta と同時に押したキーは何も行いません。
• 値は 0 から最大値の間に保たれます。値が境界を超えるキーは、値を保持し、イベントを発行しません。
• 値を変更する各キーは、変更イベントを発行します。

ポインターでは、クリックすると、ポインターの下の値が次のステップに切り上げられて選択されます。読み取り専用または無効な Rating は、クリックを無視します。

スクリーン リーダー / ARIA

Blazor Rating は、slider ロールを持つフォーカス可能な要素 (base パート) を 1 つレンダリングします。その tabindex は 0 で、Rating が無効な場合は -1 になり、次の値の属性を持ちます。

Label プロパティは、スライダーが aria-labelledby で参照する表示ラベルをレンダリングし、これによりスライダーにアクセシブルな名前が付きます。

Blazor Rating は、支援技術に対して次のようにも動作します。

• symbols パートは aria-hidden="true" を設定するため、投影されたアイコンや絵文字を含むシンボルは非表示になり、代替テキストは不要です。値は、aria-valuenow と aria-valuetext を通じてのみ支援技術に伝わります。
• value-label スロットはスライダーの内部にレンダリングされます。スクリーン リーダーは aria-valuetext から値を読み上げるため、スロットのコンテンツではなく valueFormat で値を説明してください。
• Rating はライブ リージョンを使用しません。変更された値は、スライダーの属性を通じてのみ支援技術に伝わります。
• Rating は aria-invalid を設定しないため、カスタム検証メッセージは無効状態として公開されません。

アクセシビリティ準拠

Infragistics は、Ignite UI for Blazor のアクセシビリティ サポートについて、Section 508 と WCAG 2.1 ガイドライン領域をアクセシビリティ準拠トピックで説明しています。

ユーザー側の責任:

• すべての Rating に名前を付けます (label プロパティ)。レイアウトを参照してください。
• “3 of 5” がスケールを説明していない場合や、ページが別の言語を使用する場合は、valueFormat を設定します。
• カスタム シンボルでは、満たされたシンボルと空のシンボルを、色だけでなく形や塗りつぶしでも区別できるようにし、1.4.11 Non-text Contrast の要件に従って、背景に対して 3:1 以上のコントラスト比を維持します。
• base パートのスタイルを変更する場合は、表示されるフォーカス インジケーターを維持します。
• ポインターのターゲットを十分な大きさに保ちます。各値は、1 つのシンボルの幅、またはステップが 0.5 の場合はシンボルの半分の幅のターゲットです。小サイズは 18px のシンボルをレンダリングし、2.5.8 Target Size (Minimum) の 24 x 24 CSS ピクセルを下回るため、ポインターおよびタッチ入力には中サイズまたは大サイズを推奨します。
• キーボード ユーザーには見えないため、ホバー プレビューだけに情報を載せないでください。
• カスタム検証メッセージで Rating を検証する場合は、Rating は aria-invalid を設定しないため、3.3.1 Error Identification の要件に従って、Rating の横にメッセージをテキストとして表示してください。

WAI-ARIA スライダー パターンとの相違点:

• Home は、値を aria-valuemin (0) ではなく 1 ステップに設定します。0 にするには Arrow Down を使用します。
• Rating は、パターンでオプションのキーとされている Page Up と Page Down をサポートしません。

トラブルシューティング

Blazor Rating が期待どおりに動作しない場合は、次の回答を参照してください。

値を設定しても change イベントが発生しないのはなぜですか?

Blazor Rating は、ユーザー入力 (クリックまたはキー) に対してのみ change イベントを発行します。コードで値を設定したり、ステップ メソッドを呼び出したりすると、イベントなしで値が変更されるため、値を設定する場所で独自の状態を更新してください。

現在の値をクリックしても Rating がリセットされないのはなぜですか?

Blazor Rating は、allowReset を設定しない限り、現在の値をクリックしても値を保持します。igniteui-webcomponents 4.7.0 より前は、現在の値をクリックすると常に Rating がリセットされました。アップグレード後もその動作を維持するには、allowReset を設定します。

hover イベントが発生しないのはなぜですか?

Blazor Rating は、hoverPreview がオンの間のみ hover イベントを発行し、Rating が読み取り専用または無効な場合は発行しません。イベントを受け取るには hoverPreview を設定します。

API リファレンス

Blazor Rating の API リファレンスには、対象プラットフォームの完全な API サーフェスが記載されています。

• IgbRating
• IgbRatingSymbol

依存関係

Blazor Rating には、色とシンボル サイズを適用するテーマが必要です。フレームワーク固有のセットアップについては、はじめにを参照してください。

評価シンボルに IgbIcon 要素を配置する場合は、IgbIconModule も登録してください。

その他のリソース

次のリソースでは、Blazor Rating に関するその他のガイダンスとプロジェクト サポートを提供しています。

• Rating - Design System Component
• Ignite UI for Blazor フォーラム
• Ignite UI for Blazor GitHub

関連コンポーネント

Blazor Rating は、シンボルのスケールでスコアを収集します。入力に別の形式が必要な場合は、次のコンポーネントを使用します。

• Slider - 価格や音量など、連続した範囲から正確な数値を選択する場合に Slider を使用します。
• Radio Group - Poor、Fair、Good など、各オプションにテキスト ラベルが必要な場合に Radio Group を使用します。
• Icon - Rating のカスタム シンボルを描画するには Icon を使用します。

FAQ

ここでは、Blazor Rating のセットアップ、アクセシビリティ、使用シナリオに関するよくある質問に回答します。