在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

Semantic-Org/Semantic-UI

菜单

变量和覆盖

相关源文件

本文档解释了 Semantic UI 中的变量和覆盖（overrides）系统，这是其强大主题功能的基础。有关实施自定义主题的信息，请参阅 创建自定义主题。

目的与范围

Semantic UI 的主题系统围绕两个关键机制展开：

  • 变量 (Variables)：LESS 变量，通过预定义参数控制组件外观。
  • 覆盖 (Overrides)：直接的 CSS 修改，可在需要时提供精细控制。

这些机制共同实现了组件之间的一致性样式，同时允许进行精确的定制。本文档解释了这些系统如何工作、它们的定义位置以及使用它们的最佳实践。

变量系统

什么是变量？

Semantic UI 中的变量是 LESS 变量，用于定义组件的视觉属性。它们提供了一种结构化的方式来控制：

  • 颜色和背景
  • 间距和尺寸
  • 排版
  • 动画时长
  • 组件特有属性

变量结构和层级

变量遵循层级结构：

  1. 全局变量（`site.variables`）定义了全站设置。
  2. 组件类型变量定义了特定 UI 类别的设置。
  3. 组件特有变量定义了单个组件的设置。

来源：src/themes/default/elements/icon.variables1-94 src/themes/default/collections/message.variables1-158

变量文件位置

变量文件位于主题目录中，具有特定的结构。

src/themes/[theme-name]/
├── globals/
│   └── site.variables       # Global variables
├── elements/
│   ├── button.variables     # Button variables
│   └── icon.variables       # Icon variables
├── collections/
│   ├── form.variables       # Form variables
│   └── message.variables    # Message variables
└── modules/
    ├── dropdown.variables   # Dropdown variables
    └── modal.variables      # Modal variables

变量示例

来自图标元素

来自消息集合

请注意，变量可以引用其他变量（例如 `@width: @iconWidth;`），这使得可以实现一致的设计系统。

来源：src/themes/default/elements/icon.variables52-94 src/themes/default/collections/message.variables15-25

覆盖系统

什么是覆盖？

覆盖是直接的 CSS 规则，用于补充基于变量的样式。它们允许开发者：

  1. 添加变量未涵盖的全新样式
  2. 对特定元素进行定向的 CSS 调整
  3. 定义复杂的选择器或媒体查询
  4. 与第三方库或框架集成

覆盖文件位置

覆盖文件遵循与变量相同的结构，但使用 `.overrides` 扩展名。

src/themes/[theme-name]/
├── elements/
│   ├── button.overrides
│   └── icon.overrides
├── collections/
│   ├── form.overrides
│   └── message.overrides
└── modules/
    ├── dropdown.overrides
    └── modal.overrides

覆盖示例

来自图标元素的覆盖文件

此文件定义了每个图标的特定 Unicode 内容，这仅通过变量管理是不可行的。

来源：src/themes/default/elements/icon.overrides34-42 src/themes/default/elements/icon.overrides43-50

变量和覆盖如何协同工作

在组件文件中集成

组件的 LESS 文件（例如 `src/definitions/elements/icon.less`）遵循以下模式：

  1. 定义组件类型和名称
  2. 导入主题配置（包括变量）
  3. 使用导入的变量定义样式
  4. 在文件末尾使用 `.loadUIOverrides()` 加载覆盖。

来自图标元素的示例

来源：src/definitions/elements/icon.less16-19 src/definitions/elements/icon.less37-57 src/definitions/elements/icon.less505

生成最终 CSS

当 Semantic UI 进行构建时，会发生以下情况：

  1. 默认主题中的变量提供基础值。
  2. 自定义主题中的变量会覆盖默认值。
  3. 组件 LESS 文件使用最终的变量来生成样式。
  4. 应用默认主题中的覆盖。
  5. 应用自定义主题中的覆盖。
  6. 最终结果会被编译成 CSS。

这个过程允许强大的定制，同时保持一致的结构。

变量和覆盖文件的实践

文件关系图

关键文件及其用途

文件目的
src/themes/default/globals/site.variables影响整个 UI 的全局变量
src/themes/default/elements/*.variables基础元素的变量（按钮、输入框、图标等）
src/themes/default/collections/*.variables集合（表单、网格、菜单等）的变量
src/themes/default/modules/*.variables交互式模块（下拉菜单、模态框等）的变量
src/themes/default/elements/*.overrides基础元素的 CSS 覆盖
src/themes/default/collections/*.overrides集合的 CSS 覆盖
src/themes/default/modules/*.overrides交互式模块的 CSS 覆盖
theme.config指定要为每个组件使用的主题

来源：src/themes/default/elements/icon.variables src/themes/default/elements/icon.overrides src/themes/default/collections/message.variables

何时使用变量或覆盖？

使用变量的情况：

  • 更改颜色、大小和间距等通用属性。
  • 进行系统性更改，这些更改应在各个组件之间保持一致。
  • 在现有设计参数内工作。
  • 定制组件的预定义方面。

使用覆盖的情况：

  • 添加现有变量未涵盖的新样式。
  • 进行高度特定的 CSS 调整。
  • 实现复杂的选择器或媒体查询。
  • 集成第三方组件或库。
  • 定义一次性自定义。

定制工作流程

要定制 Semantic UI 组件，请：

  1. 确定要定制的组件。
  2. 检查 `src/themes/default/[type]/[component].variables` 中的默认变量。
  3. 创建自定义主题并修改变量。
  4. 添加任何无法通过变量实现的 CSS 覆盖。
  5. 更新 `theme.config` 以使用您的自定义主题。

结论

Semantic UI 的变量和覆盖系统为创建自定义主题提供了强大的基础。通过了解这两种机制如何协同工作，您可以有效地定制框架的外观，同时保持其核心结构和功能。

变量提供了一致性和可维护性，而覆盖则为特定的定制提供了灵活性。层级结构确保了可以从全局设置到单个组件属性的不同级别的特异性进行更改。

来源：src/definitions/elements/icon.less src/themes/default/elements/icon.variables src/themes/default/elements/icon.overrides src/themes/default/collections/message.variables