Icon (アイコン)

Ignite UI for Web Components Icon は、カスタム SVG アイコンのコレクションなどの登録済みアイコン セットから、名前付きアイコンを表示するコンポーネントです。

SVG アイコンをコレクション内に名前で登録し、各アイコンをテーマベースのサイズで、周囲のテキストの色で表示します。

ライブ デモ

構造

アイコンは、コマンド、デバイス、ディレクトリ、または一般的なアクションを表すシンボルです。

Web Components Icon は igc-icon 要素を描画します。この要素は、登録された SVG をシャドウ ルート内に描画し、CSS パーツを公開しません:

igc-icon                 // host - inline box sized by --size
└─ #shadow-root
   └─ svg                // the registered SVG, 1em × 1em, filled with the current color

はじめに

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

igniteui-webcomponents パッケージをインストールします:

npm install igniteui-webcomponents

次に、Icon、そのテーマ CSS をインポートし、コンポーネントを登録します:

import { defineComponents, IgcIconComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcIconComponent);

登録後、アイコン名とコレクションを指定して Icon を表示します:

<igc-icon name="search" collection="material"></igc-icon>

名前とコレクションで説明するように、同じ名前とコレクションで SVG アイコンを登録するまで、アイコンは空のままです。

使用方法

Web Components Icon を使用して、ラベル、ボタン、リスト項目、ナビゲーションにわかりやすいシンボルを追加したり、ステータスをひと目で示したりします。

名前とコレクション

Web Components Icon は、コレクション内の名前で登録された SVG を描画します。コレクションの既定値は default です。ページ上のすべてのアイコンは 1 つのレジストリを共有するため、一度登録したアイコンはすべての Icon で使用でき、SVG が登録される前に描画された Icon は、登録された時点ですぐに更新されます。

SVG マークアップを registerIconFromText で登録するか、URL から SVG ファイルを registerIcon で取得します:

import { registerIcon, registerIconFromText } from 'igniteui-webcomponents';

const searchIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/></svg>';

registerIconFromText('search', searchIcon, 'material');
registerIcon('build', '/icons/build.svg', 'material');

次に、各アイコンに同じ名前とコレクションを設定します:

<igc-icon name="search" collection="material"></igc-icon>
<igc-icon name="build" collection="material"></igc-icon>

アイコン参照

アイコン参照は、アイコン名を別の登録済みアイコンに関連付けます。Combo や Date Picker などのコンポーネントは、default コレクション内の参照を通じて組み込みアイコンを表示し、設定した参照が優先されます。たとえば、input_clear 参照を独自のアイコンに関連付けると、これら 2 つのコンポーネントのクリア アイコンを置き換えることができます:

import { registerIconFromText, setIconRef } from 'igniteui-webcomponents';

const closeIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>';

registerIconFromText('close', closeIcon, 'my-icons');
setIconRef('input_clear', 'default', { name: 'close', collection: 'my-icons' });

サイズ

Web Components Icon は、テーマの小、中、大のサイズ プリセットをサポートし、既定では大のプリセットを使用します。--ig-size CSS 変数を --ig-size-small、--ig-size-medium、または --ig-size-large に設定して、プリセットを選択します:

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

.medium {
  --ig-size: var(--ig-size-medium);
}

<igc-icon class="small" name="build" collection="material"></igc-icon>

プリセット以外のサイズには、アイコンに --size を設定します。コンテナー内のすべてのアイコンのサイズを変更するには、コンテナーに --ig-icon-size を設定します:

.custom-size {
  --size: 56px;
}

.toolbar {
  --ig-icon-size: 2rem;
}

反転 (Mirrored)

mirrored を設定すると、アイコンが水平方向に反転します。右から左へのレイアウトで、矢印などの方向を示すアイコンに使用します。

<igc-icon name="arrow_forward" collection="material" mirrored></igc-icon>

アクセシブルな名前

装飾的なアイコンは支援技術から隠し、それ自体で意味を伝えるアイコンには、その意味を説明するアクセシブルな名前を付けます。

アイコンに aria-label を設定して名前を付けます。登録された SVG の <title> 要素もアイコンに名前を付けます。表示されているテキストの横にある装飾的なアイコンには、aria-hidden="true" を設定します:

<igc-icon name="warning" collection="material" aria-label="Warning"></igc-icon>

<span>
  <igc-icon name="search" collection="material" aria-hidden="true"></igc-icon>
  Search
</span>

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

背景との十分なコントラストを確保するようにアイコンの色を慎重に選択し、同じ色の類似した濃淡や、色収差を生じさせる組み合わせは避けてください。

プロパティ

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

メソッド

Web Components Icon は、次の API で登録したアイコンを描画します。

次の関数でアイコンを登録します。これらは igniteui-webcomponents からインポートします。collection オプションと stripMeta オプションを一緒に設定するには、コレクション名の代わりに RegisterIconOptions オブジェクトを渡します。

スタイル設定

Web Components Icon は、既定では周囲のテキストの色を使用します。次の CSS 変数で、色とサイズを変更します:

igc-icon 要素は CSS パーツを公開しないため、要素自体にスタイルを適用します。

Sass テーマ

icon-theme 関数でテーマを作成し、tokens() ミックスインで含めます。この関数は $color、$size、および $disabled-color パラメーターを受け入れ、ミックスインは、含めたスコープ内で対応する --ig-icon-* 変数を出力します。

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

@use "igniteui-theming" as *;

$custom-icon-theme: icon-theme(
  $color: #1481b8
);

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

CSS 変数

Sass ビルドの手順なしでローカルにスタイルを設定する必要がある場合は、アイコンまたはコンテナーに色とサイズを設定します:

igc-icon {
  --size: 28px;
  color: var(--ig-primary-500);
}

.toolbar {
  --ig-icon-color: var(--ig-primary-500);
}

Tailwind によるスタイル設定

igniteui-theming のカスタム Tailwind ユーティリティ クラスで Web Components Icon のスタイルを設定できます。最初にTailwind をセットアップしてから、グローバル スタイルシートで Ignite UI ユーティリティをインポートします:

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

対応するテーマには light-icon または dark-icon クラスを使用し、生成された CSS 変数を任意のプロパティでオーバーライドします:

<igc-icon name="search" collection="material" class="!light-icon ![--color:#7B9E89] ![--size:48px]"></igc-icon>

感嘆符 (!) は、Tailwind ユーティリティが Icon の既定のテーマ スタイルより優先されるようにします。

アクセシビリティ

Web Components Icon は、近くのコンテンツを装飾するか、それ自体で意味を伝える、対話型ではない視覚要素です。

キーボード操作

Web Components Icon はフォーカスを受け取らず、キーボード操作はありません。tabindex を設定せず、キーボード イベントやポインター イベントを処理しません。ユーザーがキーボードでアイコンを操作する必要がある場合は、Icon Button を使用します。

スクリーン リーダー / ARIA

Web Components Icon は、それ自体では何もアナウンスしません。支援技術が報告する内容は、アイコンのアクセシブルな名前によって決まります:

• アイコンは、igc-icon 要素の属性ではなく、ElementInternals を通じてロールとアクセシブルな名前を設定します。
• 登録されたアイコンのルート <svg> の直接の子である <title> 要素が、アイコンのアクセシブルな名前になります。
• アイコンの aria-label 属性または aria-labelledby 属性は、タイトルのない SVG のアイコンに名前を付け、タイトルより優先されます。
• igniteui-webcomponents 7.3.0 以降では、アイコンはアクセシブルな名前がある場合にのみ img ロールを宣言するため、名前のないアイコンが名前のない画像として公開されることはありません。
• アイコンは、SVG を解決するときにアクセシブルな名前を確認します。これは、name または collection が変更されたとき、テーマが変更されたとき、またはアイコンが登録されたときです。aria-label または aria-labelledby は初期のマークアップで設定してください。
• stripMeta 登録オプションは、保存される SVG から <title> 要素と <desc> 要素を削除しますが、アイコンはタイトルのテキストをアクセシブルな名前として保持します。

アクセシビリティ準拠

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

ユーザー側の責任:

• それ自体で意味を伝えるすべてのアイコンにアクセシブルな名前を付け、装飾的なアイコンは隠したままにします。アクセシブルな名前を参照してください。
• 情報を伝えるアイコンと背景の間で、特にテーマの色をオーバーライドする場合は、1.4.11 非テキストのコントラストが要求する 3:1 以上のコントラスト比を維持します。
• ユーザーが操作するアクションには、Icon ではなく Icon Button を使用します。
• 右から左へのレイアウトでは、方向を示すアイコンに mirrored を設定して、向きが読み順と一致するようにします。

トラブルシューティング

Web Components Icon が表示されない場合や、期待どおりに表示されない場合は、次の回答を参照してください。

アイコンが空なのはなぜですか?

Web Components Icon は、同じ名前とコレクションで登録された SVG のみを描画します。次の原因を確認します:

• 名前またはコレクションが登録と正確に一致していません。コレクションの既定値は default です。
• SVG マークアップの形式が正しくありません。テキストにルートの <svg> 要素がない場合や解析できない場合、登録は SVG element not found or malformed SVG string. エラーをスローします。
• SVG ファイルのリクエストが失敗しました。URL からの登録は、OK ではない応答で失敗するため、ブラウザーのコンソールとネットワーク パネルを確認します。別のオリジンのファイルには、クロスオリジン リクエストを許可するサーバーも必要です。

サーバー側レンダリング中、アイコンは SVG を描画しません。ブラウザーで読み込まれた後に SVG を描画します。

SVG アイコンにテーマの色が適用されないのはなぜですか?

Web Components Icon はルートの <svg> 要素に色を適用し、子要素はそれを塗りつぶしとして継承します。色がハードコードされている子要素は、その色を保持します:

<svg viewBox="0 0 24 24">
  <path fill="#050d42" d="..." />
</svg>

子要素からハードコードされた色を削除するか、テーマがオーバーライドするルートの <svg> 要素に色を設定します。アイコンの一部を意図的に着色するには、fill="var(--ig-primary-500)" などのテーマ カラー変数を使用します。

アイコンにカーソルを合わせるとツールチップが表示されるのはなぜですか?

ブラウザーは、SVG の <title> 要素をネイティブのツールチップとして表示します。

stripMeta オプションを指定してアイコンを登録すると、保存される SVG から <title> 要素と <desc> 要素が削除されます。アイコンはタイトルのテキストをアクセシブルな名前として保持します:

registerIconFromText('search', searchIcon, { collection: 'material', stripMeta: true });

既知の制限事項

Web Components Icon には次の制限事項があります:

• Icon は対話型ではない視覚要素です。フォーカスを受け取らず、キーボード入力も処理しません。
• テーマの色は、ルートの <svg> 要素と、その塗りつぶしを継承する子要素に適用されます。色がハードコードされている子要素は、その色を保持します。
• Icon は登録された SVG アイコンのみを描画します。アイコン フォントとリガチャはサポートされていません。

API リファレンス

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

• Icon
• registerIcon
• registerIconFromText
• setIconRef
• RegisterIconOptions

依存関係

Web Components Icon が、テーマベースのサイズと色を適用するには、テーマ スタイルシートが必要です。フレームワーク固有のセットアップについては、作業の開始を参照してください。

その他のリソース

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

• Icon - Design System Component
• Ignite UI for Web Components フォーラム
• Ignite UI for Web Components GitHub

関連コンポーネント

Web Components Icon は、他のコンポーネント内に表示されることがよくあります。アイコンがシンボルの表示以上のことを行う必要がある場合は、次のコンポーネントを使用します:

• Icon Button - ユーザーがアイコンをクリックまたは押してアクションを実行する場合は、Icon Button を使用します。
• Avatar - アイコン、イニシャル、または画像で、人物やエンティティを表すには、Avatar を使用します。
• Badge - 別の要素の横に短いステータスや数を表示するには、Badge を使用します。

FAQ

これらの質問では、Web Components Icon の一般的なセットアップ、アクセシビリティ、および使用シナリオについて説明します。