Badge (バッジ) コンポーネント

React Badge コンポーネントはプラットフォーム固有の Ignite UI for React パッケージによって提供され、視覚的な通知が必要な場合に、アプリケーション内でアバター、ナビゲーション メニュー、またはその他のコンポーネントと組み合わせて使用されます。バッジは通常、情報、成功、警告、またはエラーを伝えるために事前定義されたスタイルで設計されています。

ライブ デモ

React Badge のデモは、このコンポーネントが他のインターフェース要素の隣でコンパクトなステータスや通知をどのように伝えられるかを示します。

構造

React Badge は、他のインターフェース要素を装飾するコンパクトなラベルまたはドット インジケーターを表示します。

このコンポーネントは、base CSS パーツ内にコンテンツをレンダリングします。テキストやその他のインライン コンテンツにはコンポーネントのデフォルト スロットを使用してください。dot が有効になっている場合、バッジはコンテンツのないインジケーターとしてレンダリングされます。

<igc-badge>
└── ::part(base)
  └── default slot content
</igc-badge>

作業の開始

React Badge を使用するには、まず Ignite UI for React の作業の開始 トピックに従って基本的なプロジェクトのセットアップを行い、その後、対象プラットフォーム用にコンポーネントを登録してください。

前提条件とバージョンの互換性

対象フレームワークでサポートされているバージョンの Ignite UI for React パッケージを使用してください。フレームワーク パッケージ、Badge パッケージ、テーマ パッケージは同じリリース バージョンに揃えてください。以下の例では、各コード ブロックで使用されているフレームワークとパッケージを明記しているため、周囲のページ コンテキストなしで読んでもスニペットが自己完結的になっています。

igniteui-react パッケージを使用する React の場合は、パッケージをインストールします:

npm install igniteui-react

次に、以下のように Badge のラッパーとそのテーマ CSS をインポートする必要があります:

import { IgrBadge } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

<IgrBadge />

使用方法

React Badge を使用して、他のコンポーネントと並べて短いステータス、カテゴリ、カウント、または通知インジケーターを表示します。

次の例は、Avatar 上に表示される success バッジを示しています。プラットフォーム固有のパッケージから Badge と Avatar コンポーネントをインポートし、相対位置指定のラッパー内に Badge を配置します。

import { IgrAvatar, IgrBadge } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

コンポーネントを JSX に追加します:

<div className="wrapper">
  <IgrAvatar icon="person" shape="circle" size="small"></IgrAvatar>
  <IgrBadge icon="check" variant="success"></IgrBadge>
</div>

相対位置指定のラッパーを使用して、バッジを Avatar の上に配置します:

.wrapper {
  position: relative;
  margin-top: 15px;
}

タイプ

Ignite UI for React Badge は、数字やアイコンなど、さまざまな種類のコンテンツを持つことができます。

value プロパティを使用して、バッジ内にテキストや数値のカウントを表示します:

<IgrBadge variant="primary">12</IgrBadge>

コンテンツを子要素として直接指定することもできます。アイコンとテキストの両方を子要素として指定する場合は、正しいパディングを保つためにテキストをラップしてください。

<IgrBadge>
  <IgrIcon name="bluetooth" />
  <span>Bluetooth</span>
</IgrBadge>

アイコン

バッジの子コンテンツとしてアイコンを追加します:

<IgrBadge variant="success">
  <IgrIcon name="heart-monitor" />
</IgrBadge>

カスタム アイコンの場合は、プラットフォームのアイコン サービスにアイコンを登録し、バッジの子コンテンツとしてレンダリングします。

たとえば、バッジで使用する前に SVG アイコンを登録します:

import { registerIconFromText } from 'igniteui-webcomponents';

registerIconFromText(
  'heart-monitor',
  '<svg viewBox="0 0 24 24"><path d="M3 12h4l2-6 4 12 2-6h6" /></svg>',
  'custom'
);

ドット

Ignite UI for React Badge は、dot 属性を設定することで、通知用の最小限のドット インジケーターとしてレンダリングすることもできます。ドット バッジはコンテンツをサポートしませんが、アウトライン表示が可能で、利用可能なすべてのドット タイプ (例: primary、success、info) を使用できます。

コンテンツのない最小限の通知インジケーターをレンダリングするには、dot 属性を設定します:

<IgrBadge dot={true} ></IgrBadge>

サイズ

--size CSS 変数でバッジのサイズを制御します。16px より小さいテキスト バッジの場合は、フォント サイズと行の高さも調整してください:

igc-badge {
  --size: 12px;

  font-size: calc(var(--size) / 2);
  line-height: normal;
}

形状

バッジ コンポーネントは、rounded (デフォルト) と square の形状をサポートします。これらの値は Shape 属性に割り当てることができます。

<IgrBadge shape="square" ></IgrBadge>

バッジの形状が square の場合、--border-radius CSS 変数を使用してカスタムのボーダー半径を設定することでさらにカスタマイズできます。

バリアント

Ignite UI for React Badge は、いくつかの事前定義されたスタイルのバリアント (Primary、Info、Success、Warn、Error) をサポートします。サポートされている値 primary、info、success、warning、danger のいずれかを variant 属性に割り当てます。

<IgrBadge variant="success" ></IgrBadge>

アウトライン

outlined 属性を設定すると、バッジの周囲に控えめなボーダーを表示することもできます。

<IgrBadge outlined={true} ></IgrBadge>

アウトライン バッジのボーダー カラーは、--border-color CSS 変数を使用してカスタマイズすることもできます。

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

使用すべき場合: バッジを使用して、他のコンポーネントと並べて短いステータス、カテゴリ、カウント、または通知の状態を伝えます。インジケーターに表示テキストが不要な場合は dot を使用します。

使用すべきでない場合: アクションのための主要なコントロールとして、フォームの検証メッセージの代わりとして、またはバッジのコンテンツ、周囲のコンテキスト、アクセシブルなラベルからステータスを理解できない場合に、バッジを使用しないでください。

使用すべき	使用すべきでない

プロパティ

React Badge は、コンテンツ、外観、インジケーターの動作を制御するためのプラットフォーム固有のプロパティを公開します。

React Badge は、次のプロパティを公開します。

スタイル設定

React Badge は、IgrBadge コンポーネントの base CSS パーツと、ドキュメント化されたスタイル設定変数を使用して外観をカスタマイズします。

Sass テーマ

Ignite UI for React のテーマ システムを使用して、アプリケーションの他の部分と一貫性のあるスタイルでバッジをスタイル設定します。

CSS 変数

igc-badge::part(base) {
  --background-color: var(--ig-error-A100);
  --border-radius: 2px;
}

スタイル パーツ

Tailwind によるスタイル設定

igniteui-theming のカスタム Tailwind ユーティリティ クラスを使用してバッジをスタイル設定できます。事前に Tailwind をセットアップ し、その後グローバル スタイルシートで Ignite UI ユーティリティをインポートしてください:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgrBadge className="!light-badge ![--background:#FF4E00] ![--border-radius:4px]"></IgrBadge>

感嘆符 (!) により、Tailwind ユーティリティがバッジのデフォルトのテーマ スタイルより優先されます。

アクセシビリティ

React Badge は、短いカウント、状態、または通知を伝える非インタラクティブなステータス表示です。

キーボード インタラクション

バッジはフォーカスを受け取らず、キーボード入力を処理せず、コンポーネントのインタラクション イベントを公開しません。

スクリーン リーダー / ARIA

バッジ ホストは role="status" を使用して、コンテンツをステータス情報として公開します。

• コンポーネントは aria-roledescription を設定して、バッジとその現在の variant を識別します。
• テキストのないバッジ (dot バッジを含む) が支援技術では他に得られないステータスを伝える場合は、aria-label を追加してください。
• バッジのコンテンツまたはアクセシブルなラベルは、装飾されるアイテムに固有のものにしてください。例えば、単に 3 ではなく 3 件の未読メッセージ のように記述してください。

アクセシビリティ準拠

インフラジスティックスは、アクセシビリティ準拠 トピックで、Section 508 および WCAG 2.1 ガイドライン領域における Ignite UI for React のアクセシビリティ サポートを文書化しています。

ユーザー側の責任:

• バッジに意味のあるテキストがない場合、特に dot バッジの場合は、ステータスを説明するアクセシブルな名前を提供してください。
• バッジの色のみをステータスの表示手段として使用しないでください。テキスト、アイコン、または他のアクセシブルな手掛かりと組み合わせてください。
• テーマ スタイルをオーバーライドする際は、バッジの前景色と背景色のコントラストを十分に確保してください。

トラブルシューティング

React Badge のトラブルシューティング ガイダンスは、一般的なスタイルおよびコンテンツの問題について、問題 → 原因 → 対処法の形式で構成されています。

カスタムの背景色を設定してもバッジが変わらないのはなぜですか?

選択した variant は --background-color CSS 変数よりも優先されます。カスタムの背景色を使用するには、独自の背景色を適用するバリアントを設定しないようにしてください。

ドット バッジにコンテンツが表示されないのはなぜですか?

dot プロパティはバッジを最小限のインジケーターとしてレンダリングし、コンテンツをサポートしません。テキストやその他のインライン コンテンツを表示する必要がある場合は、通常のバッジを使用してください。

既知の制限

React Badge には、次のプラットフォームに依存しない制限があります。

• ドット バッジはインジケーターのみであり、テキストやアイコンを表示できません。
• バッジのスタイルおよびバリアント/種類の名前は、Angular とその他のサポートされているフレームワーク間で異なります。属性をフレームワーク間でそのままコピーせず、このページのプラットフォーム固有の例と API リンクを使用してください。
• バッジは視覚的なステータス インジケーターであり、単体でキーボード インタラクションを提供しません。

API リファレンス

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

依存関係

React Badge は、視覚的なスタイルを適用するためにテーマ スタイルシートを必要とします。フレームワーク固有のセットアップについては、作業の開始 を参照してください。

その他のリソース

以下のリソースでは、React Badge に関する追加のガイダンスとプロジェクトのサポートを提供します。

• Ignite UI for React フォーラム (英語)
• Ignite UI for React GitHub (英語)

関連コンポーネント

React Badge は、ステータス インジケーターが他の視覚的要素に属する場合、Avatar などの関連コンポーネントと組み合わせて使用されることが一般的です。

• Avatar - Avatar と Badge を組み合わせてステータス インジケーターを表示します。

FAQ

これらの FAQ は、React Badge の一般的なコンテンツ、インジケーター、パッケージの選択について説明します。