UI Icons
DrupalのコアIcon APIを使用してサードパーティのアイコンパックをシームレスに統合する汎用アイコンマネージャー。
ui_icons
概要
UI Iconsは、さまざまなサードパーティアイコンパックを統合、管理、表示するための統一された方法を提供するDrupal向けの包括的なアイコン管理システムです。DrupalのコアIcon API（Drupal 11.1で導入）をベースに構築されており、フィールド、メニュー、テキストエディター、メディアエンティティ、UI Patternsを含むDrupalエコシステム全体でシームレスな統合を提供します。
このモジュールは、特定の統合のための複数のサブモジュールを持つ拡張可能なアーキテクチャを提供します。アイコンは、SVGファイル、Webフォント（TTF/WOFF）、コードポイントファイル、JSON、YAML設定など、さまざまなソースから検出できます。インテリジェント検索システムは、最適なパフォーマンスのためにファジーマッチングと優先度ベースの結果およびキャッシュを使用します。
主な機能には、アイコン選択用のオートコンプリートフォーム要素、ビジュアルピッカーモーダル、コンテンツにアイコンを埋め込むためのテキストフィルター、CKEditor 5統合、アイコンおよびリンクフィールド用のフィールドタイプとウィジェット、カスタマイズ可能な表示位置を持つメニューリンクアイコンサポートが含まれます。
Features
- アイコンパック検出: モジュールとテーマから*.icons.ymlファイルで定義されたアイコンパックを自動的に検出してロードし、複数のエクストラクター（path、SVG、font、sprite）をサポート
- オートコンプリートフォーム要素: 完全一致、単語順一致、部分一致を優先するインテリジェントなファジー検索を備えたicon_autocompleteフォーム要素を提供し、設定可能な結果制限（デフォルト24、最大132）に対応
- ビジュアルアイコンピッカー: グリッド表示とAJAXページネーションを備えた直感的なアイコン選択のためのモーダルベースのアイコンピッカー（icon_picker）
- アイコンライブラリブラウザ: /admin/appearance/ui/iconsにある管理インターフェースで、検索、グループによるフィルタリング、ページネーション表示（1ページあたり100アイコン）を備えた利用可能なすべてのアイコンパックを閲覧
- フィールドタイプ統合: 許可されたアイコンパック制限を設定可能なエンティティフィールド用のアイコンフィールドタイプ（ui_icon）
- リンクフィールドウィジェット: 位置オプション（before、after、icon only）を持つリンクフィールドにアイコンを追加するための拡張リンクフィールドウィジェット（icon_link_widget）
- テキストフィルター: icon_embedフィルターを使用して<drupal-icon>タグでコンテンツにアイコンを埋め込み、カスタム設定とアクセシビリティ属性をサポート
- CKEditor 5統合: アイコン選択と設定のための専用ダイアログを備えたリッチテキストエディターでのビジュアルアイコン挿入
- メニューアイコンサポート: 設定可能な表示位置とNavigationモジュールツールバーとの統合を備えたメニューリンクコンテンツエンティティへの自動アイコン選択追加
- メディアソース: パックID、ラベル、ライセンス、ソース情報を含む完全なメタデータサポートを備えた再利用可能なアイコンメディアエンティティ作成用のアイコンメディアソースプラグイン
- UI Patterns統合: アイコンプロップタイプサポートを備えたUI Patterns 1.xおよび2.x用のアイコンソースプラグイン
- Webフォントエクストラクター: dompdf/php-font-libライブラリを使用してWebフォント（.ttf、.woff）、コードポイントファイル、JSON、YAML定義からアイコンを抽出
- Twig拡張: テンプレートでアイコンプレビューをレンダリングするためのicon_preview(pack_id, icon_id, settings) Twig関数
- テーマ互換性: Gin、DaisyUI、DSFRの管理テーマ向け自動CSS適応
- キャッシュシステム: 最適なパフォーマンスのためのアイコンパックとコレクターキャッシュタグを備えたXXH3ハッシュベースの検索キャッシュ
- 設定管理: アイコンパック設定に基づく動的フォーム生成を伴うアイコンごとのエクストラクター設定サポート
Use Cases
コンテンツへのソーシャルメディアアイコンの追加
UI Icons Fieldsを有効にしてコンテンツタイプにアイコンフィールドを追加します。ソーシャルメディアアイコンパックのみに選択を制限するよう許可されたアイコンパックを設定します。コンテンツエディターがアイコンを選択するためにオートコンプリートまたはピッカーウィジェットを使用します。カスタムサイズ設定でアイコンフォーマッターを使用して表示します。
アイコン強化ナビゲーションメニューの作成
UI Icons for Menuを有効にしてメニューリンク編集にアイコン選択を自動的に追加します。編集者は各メニュー項目のアイコンを選択し、表示位置（テキストの前、テキストの後、またはアイコンのみ）を選択できます。アイコンは適切なマークアップでメニュー出力に自動的にレンダリングされます。
リッチテキストコンテンツへのアイコンの埋め込み
UI Icons TextとUI Icons for CKEditor 5を有効にします。許可されたアイコンパックでEmbed iconフィルターを有効にするようにテキストフォーマットを設定します。ユーザーはCKEditorツールバーボタンを使用してアイコンを挿入できます。アイコンはコンテンツ内で<drupal-icon>タグとしてレンダリングされ、表示時に処理されます。
再利用可能なアイコンメディアライブラリの構築
UI Icons Mediaを有効にしてアイコンメディアタイプを作成します。コンテンツエディターはコンテンツ全体で再利用するためにメディアライブラリにアイコンを追加できます。メディアアイコンには完全なメタデータ（パック、ライセンス、ソース）と視覚的な閲覧のための自動サムネイルが含まれます。
アイコン統合によるテーマ作成
テーマテンプレートでicon_preview Twig関数を使用します: {{ icon_preview('my_pack', 'icon_id', {size: 24}) }}。アイコンはパックで定義されたテンプレートまたはフォールバックのicon-preview.html.twigテンプレートを使用してレンダリングされます。
カスタムアイコンパックの作成
*.icons.ymlファイルを使用してモジュールまたはテーマでアイコンパックを定義します。エクストラクタータイプ（path、svg、font、sprite）、ソースファイル、オプションの設定フォームを指定します。Icon APIはサイト全体で使用するためにアイコンを自動的に検出して登録します。
Tips
- 類似したアイコンが多いアイコンパックを操作する場合は、アイコンオートコンプリートにグリッド結果形式を使用してください - ビジュアルグリッドがそれらを区別するのに役立ちます
- 開発中はUI Icons Libraryサブモジュールを有効にして、コンテンツに統合する前にアイコンパックを閲覧・テストしてください
- パフォーマンスのために、実際に必要なパックのみにフィールドの許可されたアイコンパックを制限してください - これにより検索範囲が縮小され、オートコンプリート速度が向上します
- icon_embedフィルターを使用する場合は、アクセシビリティコンプライアンスのために常に適切なARIA属性（aria-labelまたはaria-hidden）を含めてください
- 検索は優先度付きのファジーマッチングを使用します - 完全な単語一致が最初に表示されるため、一般的な命名規則（action-arrow-right）は非常に検索しやすくなります
- アイコン設定はパックごとに保存されるため、異なるコンテキストで同じアイコンに異なるビジュアル設定を使用できます
Technical Details
Admin Pages 2
/admin/appearance/ui/icons
サイトで利用可能なすべてのアイコンパックを閲覧します。プレビュー（パックごとに最大32個のランダムアイコン）、パック名、説明、バージョン、ライセンス情報、総アイコン数を含むアイコンパックのカードグリッドを表示します。無効なパックの表示/非表示を切り替えるトグルを含みます。
/admin/appearance/ui/icons/{pack_id}
特定のアイコンパック内のアイコンを検索および閲覧します。キーワード検索、グループフィルタリング、アイコン設定構成、1ページあたり100アイコンを64pxサイズでページネーション表示を提供します。
権限 1
Hooks 4
hook_preprocess_menu
メニューリンクURLに保存されたアイコンオプションに基づいてアイコンマークアップを追加するためにメニュー項目を前処理します。before、after、icon_onlyの表示モードを処理します。
hook_link_alter
アイコンオプションを持つリンクについて、管理メニュー管理コンテキスト（/admin/structure/menu/manage）でアイコンを表示するためにリンクを変更します。
hook_navigation_menu_link_tree_alter
ツールバー統合のための適切なクラス設定でアイコン表示をサポートするためにNavigationモジュールのメニューリンクツリーを変更します。
hook_entity_base_field_info_alter
メニューリンクでのアイコン選択を有効にするために、menu_link_contentエンティティのリンクフィールドをicon_link_widgetウィジェットを使用するように変更します。
Troubleshooting 5
アイコンパックが正しいエクストラクターとソース設定で*.icons.ymlファイルに適切に定義されていることを確認してください。アイコンパック定義を追加または変更した後にキャッシュをクリアしてください。アイコンパックが無効としてマークされていないことを確認してください。
テキストフォーマットでicon_embedフィルターが有効になっており、filter_htmlとfilter_autopフィルターの後に配置されていることを確認してください。<drupal-icon>タグが必要な属性（data-icon-id、data-icon-settings、class、aria-label、aria-hidden、role）でHTML制限で許可されていることを確認してください。
Composerを使用してdompdf/php-font-libライブラリをインストールしてください。アイコンパック定義でソースファイルが適切なファイル拡張子（.ttf、.woff、.codepoints、.json、.yml）で正しく指定されていることを確認してください。
フィールドの「許可されたアイコンパック」設定を確認してください。特定のパックが選択されている場合、それらのアイコンのみが利用可能になります。すべてのパックを許可するには空のままにしてください。
テーマのメニューテンプレートがアイコンマークアップを含む$item['title']を適切にレンダリングしていることを確認してください。アイコンはFormattableMarkupを使用してリンクテキストとインラインでレンダリングされます。
Security Notes 3
- icon_embedフィルターは、ユーザー提供のアイコン設定をレンダリングする際にXSSを防ぐためにHTML属性を適切にサニタイズします
- アイコンオートコンプリートエンドポイントは、不正なアイコン列挙を防ぐために「access content」権限を必要とします
- UI Icons Libraryは「access ui icons library」権限を必要とし、アイコン閲覧を許可されたユーザーに制限します