Rating (評価)

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

Angular では、Rating は igniteui-webcomponents の igc-rating Web コンポーネントです。IgcFormControlDirective を使用して Angular フォームにバインドします。

ライブ デモ

構造

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 パートにレンダリングします。

はじめに

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

プロジェクトで Ignite UI for Angular をまだ使用していない場合は、ng add igniteui-angular を実行します。次に、Rating を提供する igniteui-webcomponents パッケージをインストールします。

npm install igniteui-webcomponents

IgcRatingComponent を登録し、igc-rating をレンダリングする Angular コンポーネントに CUSTOM_ELEMENTS_SCHEMA を追加します。

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { defineComponents, IgcRatingComponent } from 'igniteui-webcomponents';

defineComponents(IgcRatingComponent);

@Component({
    selector: 'app-product-rating',
    template: '<igc-rating label="Rate this product"></igc-rating>',
    schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ProductRatingComponent {}

Ignite UI for Angular テーマは igc-rating にスタイルを設定するため、Rating は theme() ミックスインで含めたテーマに従います。

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

使用方法

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

ホバー プレビュー

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

プレビューがオンの間、Rating はポインターの下の値とともに igcHover を発行します。

<igc-rating hover-preview label="Rate this article" (igcHover)="onHover($event)"></igc-rating>

public hint = '';

public onHover(event: Event) {
    this.hint = `${(event as CustomEvent<number>).detail} stars`;
}

リセット

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

<igc-rating allow-reset label="Rate this song"></igc-rating>

読み取り専用

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

<igc-rating readonly value="4.3" label="Average rating"></igc-rating>

レイアウト

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

<igc-rating [value]="score" label="Rate this product" (igcChange)="onScoreChange($event)">
  <span slot="value-label">{{ score }} of 5</span>
</igc-rating>

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

Rating に表示用の label がない場合は、aria-label を設定するか、igniteui-webcomponents 7.4.1 以降では <label> 要素を関連付けます。支援技術は、既定で値を “3 of 5” として読み上げます。このテキストを置き換えるには valueFormat を設定します。Rating は {0} を値に、{1} を max に置き換えるため、テキストのローカライズも可能です。

<igc-rating aria-label="Delivery speed" value-format="{0} out of {1} stars"></igc-rating>

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

操作状態

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

<igc-rating disabled value="3" label="Rate this product"></igc-rating>

空/満たされた状態

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

値をプロパティとしてバインドし、igcChange ハンドラーで更新します。

<igc-rating [value]="score" max="10" label="Rate this movie" (igcChange)="onScoreChange($event)"></igc-rating>

public score = 3;

public onScoreChange(event: Event) {
    this.score = (event as CustomEvent<number>).detail;
}

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

<igc-rating step="0.5" value="3.5" label="Rate your stay"></igc-rating>

サイズ

Rating には、小、中、大の 3 つのサイズがあります。小、中、大のサイズでは、それぞれ 18px、24px、36px のシンボルがレンダリングされ、Angular 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;
}

<igc-rating class="rating-large" label="Rate this product"></igc-rating>

シンボル

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

次の Rating は、igniteui-webcomponents の registerIconFromText で登録したハート アイコンを使用します。Rating は igc-icon 要素のサイズをシンボル サイズに合わせるため、評価シンボルには igc-icon を使用してください。

<igc-rating label="Rate this recipe">
  @for (i of [1, 2, 3, 4, 5]; track i) {
    <igc-rating-symbol>
      <igc-icon name="favorite" collection="material"></igc-icon>
      <igc-icon name="favorite_border" collection="material" slot="empty"></igc-icon>
    </igc-rating-symbol>
  }
</igc-rating>

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

単一選択

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

<igc-rating single label="How was your experience?">
  @for (face of faces; track face) {
    <igc-rating-symbol>
      <span>{{ face }}</span>
      <span slot="empty">{{ face }}</span>
    </igc-rating-symbol>
  }
</igc-rating>

public faces = ['😣', '😔', '😐', '🙂', '😆'];

フォーム

Rating を ngModel または formControlName にバインドするには、Angular の ControlValueAccessor インターフェイスの実装が必要です。Ignite UI for Angular は、これをスタンドアロンの IgcFormControlDirective として提供しており、ngModel または formControlName を持つ igc-rating 要素にアタッチされます。FormsModule または ReactiveFormsModule とともにインポートします。

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { IgcFormControlDirective } from 'igniteui-angular/directives';
// import { IgcFormControlDirective } from '@infragistics/igniteui-angular/directives'; for licensed package

@Component({
    selector: 'app-review-form',
    template: `
        <form>
            <igc-rating name="userRating" [(ngModel)]="review.rating" label="Your rating"></igc-rating>
        </form>
    `,
    imports: [FormsModule, IgcFormControlDirective],
    schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ReviewFormComponent {
    public review = { rating: 0 };
}

リアクティブ フォームでは、formControlName で Rating をバインドします。

<form [formGroup]="reviewForm">
  <igc-rating formControlName="rating" label="Your rating"></igc-rating>
</form>

ディレクティブは igcChange でモデルを更新し、Rating がフォーカスを失ったときにコントロールを touched としてマークし、フォーム コントロールを無効にしたときに Rating を無効にします。

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

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

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

プロパティ

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

メソッド

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

イベント

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

スタイル設定

Angular 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-* 変数を出力します。

@use "igniteui-angular/theming" as *;

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

:host {
  @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 の任意プロパティを使用して、Angular Rating にスタイルを設定できます。最初に、Tailwind をセットアップしてください。

<igc-rating
  label="Rate this product"
  class="[--ig-rating-symbol-full-color:#7B9E89] [--ig-rating-symbol-size:2rem]"
></igc-rating>

アクセシビリティ

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

キーボード操作

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

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

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

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

スクリーン リーダー / ARIA

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

igniteui-webcomponents 7.3.0 以降では、スライダーは aria-disabled と aria-readonly も設定して、無効状態と読み取り専用状態を公開します。7.4.1 以降では、スライダーは次のうち最初に該当するものからアクセシブルな名前を取得します。

1. ホストの aria-labelledby 属性。
2. for でバインドされた、または Rating を囲んでいる <label> 要素。ラベルをクリックするとスライダーにフォーカスが移ります。
3. label プロパティ。スライダーが aria-labelledby で参照する表示ラベルをレンダリングします。
4. ホストの aria-label 属性。label プロパティが設定されている場合、スライダーはこれを無視します。

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

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

アクセシビリティ準拠

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

ユーザー側の責任:

• すべての Rating に名前を付けます (label プロパティ、関連付けられた <label> 要素、または aria-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 をサポートしません。

トラブルシューティング

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

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

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

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

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

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

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

API リファレンス

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

• IgcRatingComponent
• IgcRatingSymbolComponent
• IgcFormControlDirective
• rating-theme

依存関係

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

Rating には igniteui-webcomponents パッケージが必要で、Angular フォームのバインディングには IgcFormControlDirective が必要です。Ignite UI for Angular の theme() ミックスインは、$exclude パラメーターで igc-rating を除外しない限り、igc-rating のスタイルを含みます。

その他のリソース

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

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

関連コンポーネント

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

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

FAQ

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