mcpField
S
styling

styling

github.com/ui5设计与 UI1.8k264 次安装今天更新
代码仓库

关于 styling

这项技能说明如何为 UI5 Web Components 设置样式，适用于构建和定制 UI5 界面的开发者。它按适用场景介绍标签样式、Shadow Parts、自定义状态、CSS 变量及最后手段 addCustomCSS。

主要功能

  1. 01为组件标签设置样式
  2. 02使用 CSS Shadow Parts
  3. 03按组件状态应用样式
  4. 04覆盖 SAP CSS 变量
  5. 05通过 addCustomCSS 注入样式

适用场景

  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 不会渗入，但自定义样式需要采用特定技巧。以下五种方式按推荐程度从高到低排列。

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 将自定义 CSS 直接注入组件的 shadow DOM。此方法会针对可能随版本变化的内部 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;
  }
`);

第一个参数是组件的标签名，第二个参数是要注入每个实例的 shadow DOM 中的 CSS 字符串。

不要这样做

  • 不要使用已弃用的 >>> 或 /deep/ 选择器穿透 shadow DOM——它们不起作用。
  • 不要依赖内部 DOM 结构——它可能会随版本变化。只能使用文档中说明的 shadow parts。
  • 不要对 SAP 变量使用 !important——请改为限定覆盖范围。
  • 如果存在 SAP CSS 变量，不要覆盖原始颜色——应使用变量以保持主题一致性。

快速选择指南

目标技术
更改宽度、margin、padding标签级样式
重新设置特定内部元素的样式::part(name)
根据组件状态设置样式:state(name)
全局更改颜色或字体覆盖 --sap* CSS 变量
全面自定义主题UI Theme Designer
覆盖内部 shadow DOM 样式addCustomCSS（最后手段）

评论

支持 Markdown