mcpField
S
styling

styling

github.com/ui5デザイン・UI1.8k264 回インストール今日更新
リポジトリ

styling について

UI5 Web Componentsをカスタマイズする開発者向けのスタイリングガイドです。タグへのCSS指定、Shadow Parts、カスタム状態、SAP CSS変数、最終手段としてのaddCustomCSSを説明します。

主な機能

  1. 01コンポーネントタグへのスタイル指定
  2. 02CSS Shadow Partsの利用
  3. 03コンポーネント状態に応じたスタイル
  4. 04SAP CSS変数の上書き
  5. 05addCustomCSSによるスタイル注入

活用シーン

  1. 01コンポーネントの寸法や余白の調整
  2. 02内部の特定要素のスタイル変更
  3. 03コンポーネント状態に応じた外観変更
  4. 04テーマの色やフォントのカスタマイズ

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ui5/webcomponents --skill styling

インストール後、Claude Code で/stylingを入力して読み込まれたか確認します。

詳細

UI5 Web Components のスタイリング

UI5 Web Components は、カプセル化に Shadow DOM を使用します。スタイルは分離されているため、外部 CSS の影響を受けませんが、カスタマイズには特定の手法が必要です。以下に、推奨度の高いものから順に5つの方法を紹介します。

1. タグレベルのスタイル

一部のコンポーネント（Title、Label、Tag、Button、Input など）は、カスタム要素に直接設定したスタイルが反映されるように設計されています。

ui5-input {
  width: 150px;
  color: yellow;
  background: purple;
}

これは、よりシンプルなコンポーネントで有効です。DOM 構造が深い複雑なコンポーネントでは、タグレベルのスタイルは内部要素に影響しません。

ベストプラクティス： デザインの不整合を避けるため、サイズに関するプロパティ（margin、padding、width、height）には常にタグレベルのスタイルを使用してください。

2. CSS Shadow Parts

複雑なコンポーネントでは、特定の内部要素がCSS Shadow Partsとして公開されています。

ui5-card-header::part(status) {
  color: red;
}

重要： 利用可能な Shadow Parts は、各コンポーネントの API リファレンスの「Overview」セクションに記載されています。安定しているのはドキュメントに記載された Parts のみです。ドキュメントに記載されていない内部構造には依存しないでください。

3. CSS カスタムステート

コンポーネントは、CSS カスタムステート疑似クラスを使ってカスタムステートを公開できます。これにより、コンポーネント内部の状態に基づいてスタイルを設定できます。

ui5-toolbar-item:state(overflowed) {
  flex-direction: column;
}

重要： 利用可能なカスタムステートは、各コンポーネントの API リファレンスの「Overview」セクションに記載されています。

4. CSS 変数のオーバーライド

UI5 Web Components は、テーマ設定に SAP CSS 変数（--sap*）を使用します。コンポーネント単位またはスコープ単位でこれらをオーバーライドできます。

ui5-button {
  --sapButton_TextColor: purple;
}

すべてのグローバル SAP CSS 変数は、@sap-theming/theming-base-contentで定義されています。これらをオーバーライドすると、該当する変数を使用するすべてのコンポーネントの外観が変わります。

ベストプラクティス： テーマ全体に広く変更を加える場合は、一貫性を保つため、UI Theme Designer の使用をおすすめします。CSS 変数の直接オーバーライドは、対象を絞ったスコープ内のカスタマイズにのみ使用してください。

5. addCustomCSS によるカスタム CSS（最後の手段）

上記の方法で対応できない場合は、addCustomCSS API を使用して、コンポーネントの Shadow DOM にカスタム CSS を直接挿入できます。この方法はバージョン間で変更される可能性のある内部 DOM 構造を対象とします。CSS 変数、タグレベルのスタイル、Shadow Parts で目的の結果を実現できない場合にのみ使用してください。

カスタム CSS を記述する前に：

  1. node_modules でコンポーネントのテンプレートと既存のスタイルを確認します
  2. 必要に応じて、DevTools でコンポーネントの Shadow DOM を調べ、内部構造を把握します
  3. 必要最小限のセレクターを対象にします

カスタム CSS は、コンポーネントのインスタンスが作成される前に登録する必要があります。

import { addCustomCSS } from "@ui5/webcomponents-base/dist/Theming.js";

addCustomCSS("ui5-select", `
  .ui5-select-root {
    background-color: red;
  }
`);

第1引数はコンポーネントのタグ名、第2引数はすべてのインスタンスの Shadow DOM に挿入される CSS 文字列です。

やってはいけないこと

  • 非推奨の >>> や /deep/ セレクターで Shadow DOM の境界を越えないでください。これらは機能しません。
  • 内部 DOM 構造に依存しないでください。バージョン間で変更される可能性があります。ドキュメントに記載された Shadow Parts のみを使用してください。
  • SAP 変数に !important を使用してオーバーライドしないでください。代わりに、オーバーライドのスコープを限定してください。
  • SAP CSS 変数がある場合は、色を直接オーバーライドしないでください。テーマの一貫性を保つため、変数を使用してください。

簡単な選択ガイド

目的手法
幅、マージン、パディングを変更するタグレベルのスタイル
特定の内部要素のスタイルを変更する::part(name)
コンポーネントの状態に基づいてスタイルを設定する:state(name)
色やフォントを全体的に変更する--sap* CSS 変数のオーバーライド
テーマを全面的にカスタマイズするUI Theme Designer
Shadow DOM 内部のスタイルをオーバーライドするaddCustomCSS（最後の手段）

コメント

Markdown 対応