Back to Details

styling

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Styling UI5 Web Components

UI5 Web Components 样式定制

UI5 Web Components use Shadow DOM for encapsulation. Styles are isolated — external CSS won't leak in, but customization requires specific techniques. There are five approaches, ordered from most recommended to least.
UI5 Web Components 使用Shadow DOM进行样式封装。样式是隔离的——外部CSS不会渗透到内部，但定制需要特定技巧。以下是五种方法，按推荐程度从高到低排序。

1. Styles on Tag Level

1. 标签级样式设置

Some components (Title, Label, Tag, Button, Input, and others) are designed so that styles set directly on the custom element take effect.
css
ui5-input {
  width: 150px;
  color: yellow;
  background: purple;
}
This works for simpler components. For complex components with deep DOM structures, tag-level styling has no effect on internal elements.
Best practice: Always use tag-level styling for sizing properties (margin, padding, width, height) to avoid design inconsistencies.
部分组件（Title、Label、Tag、Button、Input等）设计为直接在自定义元素上设置的样式会生效。
css
ui5-input {
  width: 150px;
  color: yellow;
  background: purple;
}
这种方式适用于较简单的组件。对于具有深层DOM结构的复杂组件，标签级样式对内部元素无效。
最佳实践： 对于尺寸属性（margin、padding、width、height），始终使用标签级样式设置，以避免设计不一致。

2. CSS Shadow Parts

2. CSS Shadow Parts

For complex components, specific internal elements are exposed as CSS shadow parts.
css
ui5-card-header::part(status) {
  color: red;
}
Important: Available shadow parts are listed in each component's API reference under the "Overview" section. Only documented parts are stable — do not rely on undocumented internal structure.
对于复杂组件，特定内部元素会以CSS shadow parts的形式暴露出来。
css
ui5-card-header::part(status) {
  color: red;
}
重要提示： 可用的shadow parts在每个组件的API参考文档的“概述”部分列出。只有文档中记录的parts是稳定的——不要依赖未记录的内部结构。

3. CSS Custom States

3. CSS自定义状态

Components can expose custom states via the CSS custom state pseudo-class, allowing you to style based on internal component conditions.
css
ui5-toolbar-item:state(overflowed) {
  flex-direction: column;
}
Important: Available custom states are listed in each component's API reference under the "Overview" section.
组件可以通过CSS自定义状态伪类暴露自定义状态，允许你根据组件内部条件设置样式。
css
ui5-toolbar-item:state(overflowed) {
  flex-direction: column;
}
重要提示： 可用的自定义状态在每个组件的API参考文档的“概述”部分列出。

4. Overriding CSS Variables

4. 覆盖CSS变量

UI5 Web Components use SAP CSS variables (
--sap*
) for theming. You can override these on a per-component or per-scope basis.
css
ui5-button {
  --sapButton_TextColor: purple;
}
All global SAP CSS variables are defined in @sap-theming/theming-base-content. Overriding them changes the appearance of any component that uses them.
Best practice: For broad theme changes, prefer using the UI Theme Designer to ensure consistency. Use direct CSS variable overrides only for targeted, scoped customizations.
UI5 Web Components 使用SAP CSS变量（
--sap*
）进行主题定制。你可以在组件级别或作用域级别覆盖这些变量。
css
ui5-button {
  --sapButton_TextColor: purple;
}
所有全局SAP CSS变量都定义在@sap-theming/theming-base-content中。覆盖这些变量会改变所有使用它们的组件的外观。
最佳实践： 对于广泛的主题更改，优先使用UI Theme Designer以确保一致性。仅在需要针对性、作用域化定制时，才直接覆盖CSS变量。

5. Custom CSS via 
addCustomCSS
(Last Resort)

5. 通过
addCustomCSS
添加自定义CSS（最后手段）

If none of the above work, custom CSS can be injected directly into a component's shadow DOM using the 
addCustomCSS
API. It targets internal DOM structure that may change between versions. Only use it when CSS variables, tag-level styles, and shadow parts cannot achieve the desired result.
Before writing custom CSS:
  1. Find the component's template and existing styles in node_modules
  2. Optionally, inspect the component's shadow DOM in DevTools to understand the internal structure
  3. Target the minimal set of selectors needed
Custom CSS must be registered before any instances of the component are created:
javascript
import { addCustomCSS } from "@ui5/webcomponents-base/dist/Theming.js";

addCustomCSS("ui5-select", `
  .ui5-select-root {
    background-color: red;
  }
`);
The first argument is the component's tag name, the second is a CSS string that gets injected into every instance's shadow DOM.
如果上述方法都不适用，可以使用
addCustomCSS
API将自定义CSS直接注入组件的shadow DOM中。这种方式针对的内部DOM结构可能会在版本间变化。仅当CSS变量、标签级样式和shadow parts无法实现所需效果时才使用。
编写自定义CSS前：
  1. 在node_modules中找到组件的模板和现有样式
  2. （可选）在开发者工具中检查组件的shadow DOM，了解内部结构
  3. 仅使用实现所需效果的最少选择器
自定义CSS必须在组件实例创建前注册：
javascript
import { addCustomCSS } from "@ui5/webcomponents-base/dist/Theming.js";

addCustomCSS("ui5-select", `
  .ui5-select-root {
    background-color: red;
  }
`);
第一个参数是组件的标签名，第二个参数是要注入每个实例shadow DOM的CSS字符串。

What NOT to Do

禁止操作

  • Don't pierce shadow DOM with deprecated 
    >>>
    or 
    /deep/
    selectors — they don't work.
  • Don't rely on internal DOM structure — it can change between versions. Only use documented shadow parts.
  • Don't use 
    !important
    on SAP variables     — scope your overrides instead.
  • Don't override raw colors when a SAP CSS variable exists — use the variable to maintain theme consistency.
  • 不要使用已弃用的
    >>>
    或
    /deep/
    选择器穿透shadow DOM    ——这些选择器已失效。
  • 不要依赖内部DOM结构——它可能在版本间变化。仅使用文档中记录的shadow parts。
  • 不要在SAP变量上使用
    !important
    ——改为限定你的覆盖范围。
  • 当存在SAP CSS变量时，不要直接覆盖原始颜色——使用变量以保持主题一致性。

Quick Decision Guide

快速决策指南

GoalTechnique
Change width, margin, paddingTag-level styles
Restyle a specific internal element
::part(name)
Style based on component state
:state(name)
Change colors/fonts globallyOverride 
--sap*
CSS variables
Full theme customizationUI Theme Designer
Override internal shadow DOM styles
addCustomCSS
(last resort)
目标方法
修改宽度、外边距、内边距标签级样式设置
重新样式化特定内部元素
::part(name)
根据组件状态设置样式
:state(name)
全局修改颜色/字体覆盖
--sap*
CSS变量
完整主题定制UI Theme Designer
覆盖内部shadow DOM样式
addCustomCSS
（最后手段）