企业官网建设流程全解析

amis-ui 背景色工具类全解：bg-* 系列 class 的取值、状态/响应式变体与源码实现

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis

背景色（background-color）工具类是 amis 前端低代码框架中 amis-ui 样式体系的一部分，它仿照 Tailwind CSS 的原子化思路，为开发者提供了一批开箱即用的bg-*工具类，无需编写任何自定义 CSS 即可为任意 DOM 节点、amis 组件节点或 Schema 中的className字段设置背景色。本文将完整梳理bg-*系列的全部类名与取值，深入讲解 hover、active、focus、disabled、group-hover 状态变体和m:/pc:响应式前缀的用法，并结合 _background-color.scss 与 _variables.scss 的源码剖析其生成原理，帮助你彻底掌握这套颜色体系并在项目中高效运用。

一、背景色工具类是什么

在 amis 中，几乎所有组件都支持通过className属性附加额外的 CSS 类。amis-ui 的样式库在 helper.scss 中统一引入了背景色、边框、布局、间距、排版等十余组工具类模块，其中背景色模块由 _background-color.md（文档）与 _background-color.scss（实现）组成。

背景色工具类的设计完全对标 Tailwind CSS 的背景色体系，核心价值有三点：

• 零样式代码：给组件加一个className="bg-primary"即可完成上色，无需在 CSS 文件中新增任何规则；
• 全色阶覆盖：从 50 到 900 共 9 级色阶外加transparent、current两个特殊值，能覆盖绝大多数视觉需求；
• 状态与响应式齐备：hover:、active:、focus:、disabled:、group-hover:前缀以及m:、pc:设备前缀一应俱全，与组件交互态和移动端适配天然配套。

下面先看它在 amis 组件中的真实应用，再逐表对照全部取值。

二、在 amis 中的实际使用示例

在 amis 源码中，背景色工具类已被内置组件直接使用。以 Progress.tsx（进度条组件）为例，其阈值颜色映射就声明为：

map: ['bg-danger', 'bg-warning', 'bg-info', 'bg-success', 'bg-success']

这意味着进度条会根据进度高低自动套用bg-danger（危险红）、bg-warning（警告黄）、bg-info（信息蓝）、bg-success（成功绿）等背景色类。另一个例子是 App.tsx，其中导航徽标的默认类名为link.badgeClassName || 'bg-info'，即直接以bg-info作为徽标默认背景。

从这两个用例可以直观看到：bg-*类既可以写死在组件渲染逻辑里，也可以由使用方通过className/badgeClassName等属性传入覆盖，使用方式与普通 CSS 类完全一致。你在自己的 amis Schema 中也可以这样写：

{ "type": "button", "label": "危险操作", "className": "bg-danger text-white" }

三、基础与语义色背景类

原文档首先给出了一批基础类，包含三个特殊值（bg-none、bg-transparent、bg-current）、黑白两色以及八组语义色。其中：

• bg-none是唯一带!important的类，用于强制清除所有背景（包括背景图片）；
• bg-transparent将背景设为完全透明；
• bg-current使用 CSS 关键字currentColor，即背景色跟随当前元素的color值，是实现"文字与背景同色联动"的利器。

注意：原文档表格中bg-warning一列写的是#28a745，与 _variables.scss 中warning: #fad733不一致，属于文档快照与源码变量的偏差；实际生效值以 SCSS 变量为准（上表已按源码修正为#fad733）。这也是本章后面要强调的原则：一切以$colors变量为最终事实来源。

语义色对应着 amis 的主题色体系：primary为主色、danger为危险操作色、success为成功反馈色、info为信息提示色、warning为警告色、light/dark为明暗中性色。在表单校验、状态标签、进度条等场景中优先使用语义色，可以在主题切换时自动跟随主题变量，避免硬编码颜色值导致的主题漂移。

四、灰色与彩色色阶背景类

除基础色外，amis-ui 还提供了 gray、red、yellow、green、blue、cyan、indigo、purple、pink 九大色系，每个色系包含transparent、current两个特殊类以及 50～900 共 9 级明度色阶。数值越大颜色越深，50 为最浅、900 为最深，整体遵循 Tailwind 色板约定（源码注释也给出了 tailwind.ink 等色板生成工具作为参考，见 _variables.scss）。

4.1 灰色色阶

4.2 红色色阶

4.3 黄色色阶

4.4 绿色色阶

4.5 蓝色色阶

4.6 青色色阶

4.7 靛蓝色阶

4.8 紫色色阶

4.9 粉色色阶

五、状态变体：hover / active / focus / disabled / group-hover

原文档明确指出"还有 hover、active、focus、disabled 扩展，比如hover:bg-black"。这些变体的写法是在类名前加状态前缀，形如：

<button class="bg-blue-500 hover:bg-blue-700">悬停变深</button>

完整的变体清单如下（均可与第三节、第四节的任意bg-*类组合）：

其中active与disabled两个变体同时支持 CSS 伪类（:active/:disabled）和 amis 常用的.is-active/.is-disabled状态类，这是因为 amis 很多组件（如按钮的按下态）并不触发原生:active，而是通过框架添加.is-active类来标记状态。group-hover则解决了"悬停父容器、高亮子元素"的常见交互需求，父节点需先加上group类：

<div class="group"> <div class="bg-white group-hover:bg-gray-100">悬停父容器时变色</div> </div>

六、响应式变体：m: 与 pc: 前缀

背景色类还支持设备前缀，在 _variables.scss 中定义了设备断点映射：

$devices: ( m: '(max-width: 768px)', pc: '(min-width: 769px)' ) !default;

• m:前缀：屏幕宽度 ≤ 768px（移动端）时生效；
• pc:前缀：屏幕宽度 ≥ 769px（桌面端）时生效。

用法示例：

<div class="bg-white pc:bg-gray-50">桌面端显示浅灰背景，移动端为白色</div> <div class="bg-blue-500 m:bg-green-500">移动端背景为绿色</div>

从源码看，设备变体与状态变体还可以自由叠加，例如m:hover:bg-blue-700、pc:focus:bg-blue-500等组合都会被生成（见 _background-color.scss）。其实现依赖 _mixins.scss 中的media-devicemixin，最终会编译为对应的@media查询块。

七、源码实现原理：从 $colors 变量到全套类名

背景色工具类的全部类名并非手写，而是由 SCSS 程序化生成的。整个生成链路分为三层：

7.1 颜色变量源：$colorsmap

所有颜色值集中在 _variables.scss 的$colorsmap 中：

$colors: ( black: #000, white: #fff, primary: #007bff, secondary: #6c757d, success: #28a745, info: #007bff, warning: #fad733, danger: #dc3545, light: #f8f9fa, dark: #343a40, gray: (50: #f9fafb, ..., 900: #111827), red: (50: #fef2f2, ..., 900: #7f1d1d), yellow: (50: #fffbeb, ..., 900: #78350f), green: (50: #ecfdf5, ..., 900: #064e3b), blue: (50: #eff6ff, ..., 900: #1e3a8a), cyan: (50: #ecfeff, ..., 900: #164e63), indigo: (50: #eef2ff, ..., 900: #312e81), purple: (50: #f5f3ff, ..., 900: #4c1d95), pink: (50: #fdf2f8, ..., 900: #831843) ) !default;

注意$colors使用了!default声明，意味着在引入样式前你可以自行覆盖该变量，从而整体替换这套配色，这是 amis-ui 支持主题定制的关键机制之一。顶层键（如primary、red）作为类名中段，嵌套 map（如red: (50: ..., 900: ...)）则递归展开为bg-red-50～bg-red-900。

7.2 递归生成 mixin：bg-colors-map与bg-colors

_background-color.scss 中定义了两个核心 mixin：

• bg-colors-map：遍历$colorsmap 生成.bg-{色名}规则；遇到嵌套 map 时递归调用自身，把父键拼进类名（这正是色阶类名的由来）；同时特判了is-active与is-disabled两种后缀以生成双选择器规则。
• bg-colors：在调用 map 生成之前，先固定输出bg-transparent与bg-none（后者带!important）。

7.3 全局展开：状态变体与设备变体

文件末尾对 mixin 进行了多轮调用（第 182～213 行）：

@include bg-colors(); @include bg-colors('.' + selector-escape('hover:'), ':hover'); @include bg-colors('.' + selector-escape('active:'), '.is-active'); @include bg-colors('.' + selector-escape('focus:'), ':focus'); @include bg-colors('.' + selector-escape('disabled:'), '.is-disabled'); @include bg-colors('.group:hover .' + selector-escape('group-hover:')); @each $deivce in map-keys($devices) { @include media-device($deivce) { @include bg-colors('.' + selector-escape($deivce + ':')); // 以及 $deivce + ':hover' / ':active' / ':focus' / ':disabled' / 'group-hover' 的叠加组合 } }

这里有两个值得注意的工程细节：

1. 由于类名中包含冒号（如hover:bg-black），源码使用 Sass 的selector-escape函数对冒号进行转义，确保生成的 CSS 选择器（.hover\:bg-black:hover）能被浏览器正确解析；
2. 状态变体和设备变体都通过"前缀 + 后缀"两个参数注入 mixin，因此可以任意组合，例如m:hover:bg-primary会在移动端媒体查询内生成.m\:hover\:bg-primary:hover规则。

最终这一整套规则经 helper.scss 的@import './helper/background/background-color'被纳入 amis-ui 全局样式。

八、同族工具类与最佳实践

背景色工具类是 amis-ui 原子化工具类体系中的一员，与其同族、可搭配使用的还有：

• 文字颜色：text-*系列，与bg-*共用同一套$colors色板；
• 边框颜色：border-*系列，同样基于$colors生成；
• 宽度/高度 与 padding 等布局工具类，常用于组合出可预览的色块（原文档示例中的w-24 h-6即宽度与高度工具类）。

实际开发中的推荐实践：

• 优先使用语义色（bg-primary、bg-danger、bg-success等）表达业务含义，避免散落的魔数色值；
• 深浅色阶用于层次：用bg-gray-50～bg-gray-200做卡片、表头等浅色底，用bg-gray-800～bg-gray-900做深色区块；
• 状态色组合交互：按钮类元素用hover:、active:、disabled:变体实现完整的交互态配色；
• 移动端优先：默认值面向移动端书写，再用pc:前缀覆盖桌面端表现；
• 主题一致性：若需全局换肤，优先覆盖$colors变量而不是逐个替换类名。

九、注意事项与已知细节

1. 文档快照与源码的偏差：_background-color.md 中bg-warning标注为#28a745，而实际$colors中warning为#fad733；bg-info与bg-primary同为#007bff。遇到类似疑问时，一律以 _variables.scss 的$colorsmap 为最终事实来源。
2. !important语义：全系列中只有bg-none使用background: none !important，用于强制清除既有背景（例如覆盖组件默认背景图片或背景色），其余类均未加!important，因此叠加类时后声明的规则会按 CSS 层叠规则生效。
3. 冒号类名写法：使用状态/设备变体时类名中包含冒号，在 HTML 中直接写class="hover:bg-black"即可；若在 JSX 或 JSON Schema 中书写，注意字符串原样保留冒号，不要转义。
4. background与background-color的差异：基础特殊类（bg-transparent、bg-current、bg-none）使用简写属性background，其余色阶类使用background-color，两者在层叠时行为略有不同（简写会重置背景图片等子属性），如需同时使用背景图与背景色，应避免在同一个元素上叠加这两类特殊值与背景图场景。

十、总结

本文完整覆盖了 amis-uibg-*背景色工具类的全部类名、取值、状态变体、响应式前缀及其 SCSS 生成原理。从使用层面，你可以直接在组件className中组合使用基础色、语义色与九大色阶，配合hover:/active:/focus:/disabled:/group-hover:与m:/pc:前缀实现完整的交互与响应式配色；从原理层面，所有类名均由$colorsmap 经bg-colors-map/bg-colorsmixin 递归生成，修改 _variables.scss 即可整体定制配色。掌握这套体系后，在 amis 低代码页面中做任何背景色定制都不再需要编写额外的 CSS 文件。

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis