UI Styles
開発者がYAMLファイルでCSSクラスベースのスタイルを定義し、サイトビルダーがブロック、Layout Builderコンポーネント、リージョン、Views、CKEditorコンテンツなどに適用できるようにします。
ui_styles
インストール
composer require 'drupal/ui_styles:8.x-1.19'
概要
UI Stylesは、テーマ開発者とサイトビルダーの間のギャップを埋める、Drupal向けの包括的なスタイリングフレームワークです。開発者はモジュールまたはテーマ内のYAMLファイルで再利用可能なスタイル（CSSクラスのコレクション）を定義し、サイトビルダーはコードを書くことなく直感的な管理インターフェースを通じてこれらのスタイルを簡単に適用できます。
このモジュールは、ラベル、説明、カテゴリ、オプションを持つスタイルを宣言的に定義するプラグインベースのアーキテクチャを提供します。各オプションはターゲット要素に適用される1つ以上のCSSクラスにマッピングされます。システムは、チェックボックス（単一オプション）、セレクト/ラジオボタン（複数オプション）、またはアイコンツールバー（アイコンが提供されている場合）のどのフォームウィジェットをレンダリングするかをインテリジェントに検出します。
主要な機能として、テーマライブラリから関連するCSSルールのみを抽出する自動スタイルシート生成があり、管理インターフェースとCKEditorでのプレビューでスタイルを利用可能にします。これにより、スタイルを選択する際にWYSIWYGのような動作が保証されます。
Features
- 開発者がラベル、説明、カテゴリ、プレビュー設定を持つ再利用可能なCSSクラスの組み合わせを宣言できるYAMLベースのスタイル定義システム
- 適切なウィジェットタイプを自動選択するスマートフォームウィジェットレンダリング（単一オプションの場合はチェックボックス、複数オプションの場合はプレビュー付きラジオボタン、アイコンが提供されている場合はアイコンツールバー）
- テーマCSSライブラリを解析し、定義されたスタイルオプションに関連するCSSルールのみを抽出する自動スタイルシート生成
- 管理フォームで折りたたみ可能なグループを持つカテゴリベースのスタイル整理
- 現在のテーマとそのベーステーマで定義されたスタイルのみを表示するテーマ対応のスタイルフィルタリング
- サイトビルダーが事前定義されたオプション以外の任意のCSSクラスを追加できる追加クラスフィールド
- 現在要素に適用されているスタイルを示す視覚的インジケーター
- 設定可能なプレビュークラスと表示モード（inside、aside、hidden）によるスタイルプレビューのサポート
- 視覚的なアイコンベースのツールバーを可能にするスタイルオプションのアイコンサポート
- スタイル定義の外部ドキュメントリンクサポート
- より高い重みのモジュール/テーマでenabled: falseを宣言することで継承されたスタイルを無効化する機能
Use Cases
Bootstrapベースのテーマスタイリング
Bootstrapを使用するテーマ開発者が、背景色（bg-primary、bg-secondary）、テキスト色、スペーシングユーティリティ、ボーダースタイルなどの一般的なBootstrapユーティリティクラス用のUI Stylesを定義します。サイトビルダーは、CSSクラス名を知らなくても、ドロップダウンメニューから「プライマリ背景」や「大きなパディング」を選択するだけで、これらのBootstrapクラスをブロック、セクション、リージョンに適用できます。
CKEditorでのコンテンツ編集者向け視覚的スタイリング
CKEditor 5統合により、コンテンツ編集者はWYSIWYGエディタ内でテキストや段落に事前定義されたスタイルを直接適用できます。例えば、段落を選択して「ハイライトボックス」スタイルを適用したり、テキストを選択して「重要」インラインスタイルを適用し、エディタ内で結果を即座に確認できます。
Layout Builderコンポーネントのスタイリング
Layout Builderを使用する際、サイトビルダーは個々のセクションとブロックにスタイルを適用できます。各セクションにはセクションラッパーとそのリージョンにスタイルを適用でき、各ブロックにはラッパー、タイトル、コンテンツ領域に個別のスタイルを設定できます。これにより、カスタムテンプレートなしで柔軟なビジュアルレイアウトが可能になります。
未公開コンテンツの視覚的表示
UI Styles Entity Statusを使用すると、テーマは半透明のオーバーレイや特徴的なボーダーを未公開コンテンツに自動的に適用でき、カスタムコードなしで、どのコンテンツがまだ公開されていないかを編集者に視覚的に明確にします。
テンプレートオーバーライドなしのViewsスタイリング
サイトビルダーは管理インターフェースを通じてViews出力にスタイルを適用できます：公開フォームにカードスタイルのレイアウトを適用し、フォーマット/スタイル出力にグリッドクラスを追加し、ページャーにカスタムカラーでスタイルを設定できます。テンプレートファイルに触れることなくすべて可能です。
デザインシステムドキュメント
スタイルライブラリページはテーマのデザインシステムのライブドキュメントとして機能します。開発者が説明とプレビュークラスを持つスタイルを定義すると、ライブラリページはコンテンツ編集者やサイトビルダーが参照できるライブサンプル付きの利用可能なすべてのスタイルを表示するリファレンスになります。
Tips
- テーマ固有のスタイリングにはテーマのTHEMENAME.ui_styles.ymlファイルでスタイルを定義し、テーマ間で再利用可能なスタイルにはカスタムモジュールで定義してください
- カテゴリを使用して関連するスタイルをまとめて整理してください - 管理UIで折りたたみ可能なグループとして表示されます
- 「previewed_with」プロパティを使用すると、ヘルパークラス（パディングやボーダーなど）を追加してライブラリでのスタイルプレビューをより見やすくできます
- フロートやポジションユーティリティなど、段落テキストでうまく機能しないスタイルには「previewed_as: aside」を設定してください
- ライブラリでプレビューすべきでない副作用のあるスタイルには「previewed_as: hidden」を使用してください
- 継承されたスタイルを無効にするには、同じIDと「enabled: false」を持つ定義をより高い重みのモジュールまたはテーマで作成できます
- すべてのスタイルフォームの「追加クラス」フィールドにより、サイトビルダーは事前定義されたオプション以外のカスタムCSSクラスを追加できます
- スタイルはテーマによって自動的にフィルタリングされます - アクティブなテーマとそのベーステーマからのスタイルのみが利用可能です
- アイコンベースのスタイル選択には、スタイル定義または個々のオプションに「icon」プロパティを設定してください
- 「links」プロパティを使用して外部ドキュメントにリンクし、編集者が各スタイルをいつ使用すべきか理解できるようにできます
Technical Details
Admin Pages 3
/admin/appearance/ui/styles
カテゴリ別にグループ化された利用可能なすべてのスタイルを表示する包括的な概要ページです。各スタイルにはラベル、説明、ライブCSSプレビュー付きのオプション、および外部ドキュメントリンクが表示されます。サイトビルダーやコンテンツ編集者のリファレンスとして便利です。
/admin/appearance/regions-styles
インストールされているすべてのテーマと、各テーマの個別リージョンスタイル設定ページへのリンクを一覧表示する概要ページです。
/admin/appearance/regions-styles/{theme}
特定のテーマで定義された各リージョンにスタイルを適用できる設定ページです。各リージョンには、利用可能なすべてのスタイルオプションと追加クラスフィールドを含む折りたたみ可能なスタイルフォームがあります。
権限 1
Hooks 1
hook_ui_styles_styles_alter
スタイルプラグイン定義がYAMLファイルから収集された後、Cacheされる前にモジュールが変更できるようにします。
Troubleshooting 4
YAMLファイルが正しく命名され（YOURMODULE.ui_styles.ymlまたはYOURTHEME.ui_styles.yml）、適切にフォーマットされていることを確認してください。スタイル定義を追加または変更した後はCacheをクリアしてください。テーマ固有のフォームについては、スタイルが現在のテーマまたはそのベーステーマで定義されていることを確認してください。
スタイルシートジェネレーターはCSSファイルにアクセスする必要があります。テーマのライブラリが正しく定義され、CSSファイルがアクセス可能であることを確認してください。/ui_styles/stylesheetエンドポイントがプレビューCSSを生成します - 期待されるスタイルが返されるか確認してください。
スタイル定義のオプションがテーマに存在する有効なCSSクラスにマッピングされていることを確認してください。ターゲット要素のテンプレートがクラスを追加する#attributesまたは#item_attributesプロパティをサポートしているか確認してください。
CKEditor 5プラグインがテキストフォーマット設定で有効になっていることを確認してください。エディタは/ui_styles/stylesheet?prefix=.ck-contentからスタイルを読み込みます - このエンドポイントがスタイルCSSルールを返すか確認してください。
Security Notes 2
- 「追加クラス」フィールドはサイトビルダーからの任意のCSSクラス入力を受け付けます。これはクラスのみを追加し（任意のHTMLではなく）、スタイル設定へのアクセス権を持つユーザーはサイトの外観に影響を与える可能性があるため、信頼できるユーザーであることを確認してください。
- YAMLファイルのスタイル定義は信頼できるソースから提供される必要があります。これらはレンダリングされる出力に追加されるCSSクラスを定義するためです。