UI Patterns（DrupalにおけるSDC統合）
SDC（Single Directory Components）をDrupalプラグインとして公開し、Drupal開発やサイト構築でシームレスに使用できるようにします。
ui_patterns
インストール
composer require 'drupal/ui_patterns:^2.0'
概要
UI Patternsは、Drupal CoreのSingle Directory Components（SDC）APIを拡張する包括的なモジュールで、Drupalサイト全体で再利用可能なUIコンポーネントを定義、管理、使用するための堅牢なフレームワークを提供します。コンポーネントとは、明確な標準に基づいた再利用可能でネスト可能な要素であり、任意の数のアプリケーションを構築するために組み立てることができます。
このモジュールは、コンポーネントをBlock、Layout、Field Formatter、ViewsのRow/Styleプラグインとして使用できるプラグインベースのアーキテクチャを提供します。様々なデータソース（Field、Entity、Token、Menu、Breadcrumb）をコンポーネントのpropsやslotsにマッピングできる高度なSourceシステムを含んでいます。
UI PatternsはコンポーネントプロパティのJSON Schema検証を拡張し、プロパティタイプ（string、number、boolean、enum、URL、links、slotsなど）を自動検出し、管理UIで各プロパティタイプを設定するための適切なウィジェットを提供します。
Features
- Drupal Core SDC APIを追加機能と利便性向上で拡張
- コンポーネントをBlock、Layout、Field Formatter、Viewsプラグインとして公開するプラグインベースのアーキテクチャ
- コンポーネントのpropsとslotsにデータをマッピングするための包括的なSourceプラグインシステム
- JSON Schemaからの自動検出によるPropTypeシステム（string、number、boolean、enum、URL、links、list、attributes、slotなど）
- コンポーネントのドキュメント化とショーケース表示のためのコンポーネントライブラリブラウザ
- コンポーネントpropsを設定するためのウィジェットシステム（textfield、select、checkbox、WYSIWYGなど）
- Entity、Field、Viewのコンテキストに基づいて適応するコンテキスト対応のSourceプラグイン
- コンポーネントのバリアントとカスタム属性のサポート
- コンポーネントにクラスを追加し属性を設定するためのTwigフィルター
- カスタムui-patterns://スキーマプロトコルによるJSON Schema参照解決
- テーマがモジュールコンポーネントを置き換えることを可能にするコンポーネントネゴシエーションシステム
- UI Patterns 1.xコンポーネントとのレガシー互換性レイヤー
- コンポーネントドキュメント用のStories/プレビューシステム
Use Cases
コンテンツ一覧用のカードコンポーネント作成
テーマにtitle、image、summary、linkのpropsを持つカードコンポーネントを作成します。UI Patterns Field Formattersを有効にし、Entity参照フィールドで「Component per item」フォーマッターを使用するように設定します。参照先Entityのtitleをカードのtitle propに、imageフィールドをimage propに、body summaryをsummary propにマッピングします。各参照Entityがスタイル付きカードとしてレンダリングされます。
Layout Builderでのヒーローセクション構築
background、content、call-to-action用のslotsを持つヒーローコンポーネントを作成します。UI Patterns Layoutsを有効にしてLayoutとして公開します。Layout BuilderでセクションにヒーローLayoutを選択し、各slotリージョンにBlock（テキスト、画像、ボタン）を配置します。バリアントpropsを設定して中央揃えと左揃えのスタイルを切り替えます。
ナビゲーションメニューの表示
「links」propタイプを持つナビゲーションコンポーネントを作成します。BlockでコンポーネントをConfirmする際、links propに「Menu」Sourceを選択し、目的のMenuを選択します。Menuツリーはコンポーネントが期待するlinksデータ構造に自動的に変換されます。
再利用可能なページLayoutの作成
header、sidebar、main content、footer用のslotsを持つページLayoutコンポーネントを定義します。これらをLayout BuilderでLayoutとして使用し、サイト全体で一貫したページ構造を実現します。異なるバリアントで2カラムや3カラムの配置を提供できます。
コンポーネントテンプレートを使用したViewsの構築
コンテンツティーザー用のティーザーコンポーネントを作成します。UI Patterns Viewsを有効にし、ViewでRowプラグインとして「Component (UI Patterns)」を使用するように設定します。Field Sourceプラグインを使用してViewフィールドをコンポーネントpropsにマッピングします。各View結果がコンポーネントテンプレートを使用してレンダリングされます。
UI Patterns 1.xからの移行
UI Patterns Legacyを有効にして、1.x YAML形式で定義されたコンポーネントを読み込みます。これにより、既存のコンポーネント定義との後方互換性を維持しながら、新しいSDCベースのコンポーネント形式に段階的に移行できます。
Tips
- component.ymlの「group」プロパティを使用して、ライブラリ内でコンポーネントを論理的なカテゴリに整理する
- コンポーネントと一緒にstories.ymlファイルを定義して、コンポーネントライブラリにプレビュー例を提供する
- 「attributes」propはすべてのコンポーネントに自動追加される - カスタムクラスやdata属性を渡すために使用する
- component.ymlで「noUi: true」プロパティを使用して、内部/ユーティリティコンポーネントを選択インターフェースから非表示にする
- コンポーネントは「replaces」プロパティを使用して、他のモジュールやテーマのコンポーネントを上書きできる
- Sourceプラグインはコンテキスト対応 - Field SourceはEntityコンテキストが利用可能な場合にのみ表示される
- add_classとset_attribute Twigフィルターは、コンポーネントテンプレート内での属性操作に役立つ
- JSON Schema $refで「ui-patterns://」プロトコルを使用して、UI Patternsの組み込みpropタイプスキーマを参照する
- PropTypeアダプターは、互換性があるが構造が異なるスキーマ間のデータ変換を処理する
- コンポーネントの追加や変更後は、管理インターフェースで変更を確認するためにキャッシュをクリアする
Technical Details
Admin Pages 5
/admin/appearance/ui
コンポーネント、アイコン、スタイル、サンプルを含むUI関連ライブラリのランディングページ。デザインシステムライブラリへのエントリーポイントとして機能します。
/admin/appearance/ui/components
カテゴリ別にグループ化されたすべての利用可能なUIコンポーネントを閲覧します。コンポーネント名、プロバイダー、説明、および個別コンポーネントページへのクイックリンクを表示します。コンポーネントはcomponent.ymlで定義された「group」プロパティによって整理されます。
/admin/appearance/ui/components/{provider}
特定のモジュールまたはテーマが提供するコンポーネントを閲覧します。そのプロバイダーのすべてのコンポーネントをグループ別に表示します。
/admin/appearance/ui/components/{provider}/{machineName}
単一コンポーネントの詳細ドキュメントページ。コンポーネントのメタデータ（名前、グループ、説明、ステータス）、タイプとデフォルト値を含むpropsテーブル、slotsテーブル、定義されている場合はレンダリングされたストーリープレビューを表示します。
/admin/structure/component
フォーム表示管理を含むすべてのコンポーネントの管理一覧。コンテンツ編集フォームでコンポーネントのpropsとslotsがどのように表示されるかを設定できます。実験的なUI Patterns UIモジュールの一部です。
権限 3
Hooks 6
hook_component_info_alter
発見後のSDCコンポーネント定義を変更します。props、slots、その他のコンポーネントメタデータを変更できます。
hook_ui_patterns_source_value_alter
Sourceプラグインによって生成された値がコンポーネントに渡される前に変更します。
hook_ui_patterns_component_pre_build_alter
レンダラーパイプラインを通過する前にコンポーネントのrender要素を準備します。
hook_plugin_filter_block__ui_patterns_alter
UI PatternsでSourceとして使用できるBlockプラグインをフィルタリングします。Blockを除外するには_ui_patterns_compatibleをFALSEに設定します。
hook_component_form_display_groups
コンポーネントフォーム表示設定インターフェースのグループを定義します。（UI Patterns UIモジュール）
hook_component_form_display_group_row_alter
コンポーネントフォーム表示テーブルのグループ行を変更します。（UI Patterns UIモジュール）
Troubleshooting 5
component.ymlが有効であることを確認し、キャッシュをクリアし、コンポーネントに「noUi: true」が設定されていないことを確認してください。Block/Layout統合にはコンポーネントに少なくとも1つのslotが定義されている必要があります。
propのJSON Schemaが既知のPropTypeと一致していることを確認してください。カスタムスキーマを使用している場合は、既存のpropタイプと互換性があることを確認するか、PropTypeアダプターを作成してください。
prop値が期待されるJSON Schemaタイプと一致していることを確認してください。UI Patternsは値を正規化しますが、互換性のないデータ構造は依然として検証エラーを引き起こす可能性があります。
Entityコンテキストが利用可能であることを確認してください。Blockでは、これはBlockがEntityを提供するコンテキスト（例：Entity表示上のLayout Builder）に配置されている必要があります。
UI Patterns Libraryを必要とするUI Patterns Legacyモジュールを有効にしてください。レガシーパターン定義が期待されるYAML形式であることを確認してください。
Security Notes 4
- WYSIWYG SourceはDrupalのテキストフォーマット権限を尊重します - 適切なフォーマットが設定されていることを確認してください
- Token SourceでのToken置換はDrupalのTokenシステムのセキュリティモデルに従います
- Block Sourceはコンテンツ/コンフィグEntity依存を防ぐために、デフォルトでinline_blockと特定のシステムBlockを除外します
- コンポーネント属性値はレンダリング時にDrupalのAttributeクラスを通じてサニタイズされます