amis-ui SCSS 变量体系开发规范CSS 自定义变量与 SCSS 变量的双轨协作【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis本篇技术指南以 amis 前端低代码框架中packages/amis-ui的 SCSS 样式源码为对象系统讲解其样式体系中最核心的工程决策CSS 自定义变量--xxx与 SCSS 变量$xxx如何在同一个样式库中共存与协作。读者读完本篇后将掌握 amis-ui 样式文件的目录结构与职责划分、5 条关键开发约束颜色计算、禁用if/lighten/darken、负数写法、#{}插值、DevTools 调试并能依据这些规范正确地定制主题或为 amis 贡献样式代码。背景为什么 amis-ui 需要两套变量系统amis 的界面样式全部由 packages/amis-ui/scss 下的 SCSS 源码编译而来。与大多数传统 SCSS 工程不同amis-ui 的样式体系采用了两套变量并存的架构SCSS 变量$xxx编译期变量在 Sass 预编译阶段完成替换支持lighten、darken、颜色计算等一切 Sass 能力CSS 自定义变量--xxx运行期变量被编译进最终的 CSS 中可在浏览器里被动态覆盖是实现主题切换、运行时定制的关键。在 scss/README.md 的开发注意事项中项目方明确指出目前 SCSS 里大量使用了 CSS 自定义变量它和之前的 SCSS 变量明显不同。之所以同时保留 SCSS 变量是因为有大量颜色计算无法在自定义变量中使用——CSS 自定义变量本身不支持lighten()/darken()这类颜色运算函数这类计算只能交给编译期的 Sass 完成。因此项目采用的是两者结合的方式想修改颜色最好的方式还是 SCSS 变量但其他样式都能方便地用自定义变量修改。文档还透露了后续演进方向有可能基于 HSL 的方式让颜色也实现动态计算从而彻底摆脱对编译期颜色函数的依赖。这套双轨制是理解 amis-ui 全部样式代码的前提下面按 5 条规则逐一展开。规则一颜色修改走 SCSS 变量其他样式走自定义变量源码依据SCSS 变量的集中定义位于 scss/_variables.scss文件开头的注释直接说明了设计意图// 这里只放 sass 里的变量因为有很多颜色计算为了保持和之前的兼容性所以还保留这些变量 // 但后续会通过新增 css 自定义属性的方式逐渐替换该文件定义了三类 SCSS 变量命名空间与根字号$ns: 类名前缀、$remFactor: 16pxrem 换算基准设备断点$devicesmap如m: (max-width: 768px)、pc: (min-width: 769px)颜色调色板$colorsmap内置black、white、primary、secondary、success、info、warning、danger、light、dark以及gray、red、yellow、green、blue、cyan、indigo等各 10 级50~900渐变色阶。文件中还保留了 v1 版本的色板生成思路注释color50: tint($color, 0.95)等并推荐了 Tailwind 系列色板生成工具供开发者生成新色阶时参考。实用建议当需要调整 amis 的主题色系时优先修改$colors等 SCSS 变量再重新编译可以保证 hover、active、disabled 等派生颜色仍然协调。而组件级的布局、间距、字体、圆角等细节则尽量通过 CSS 自定义变量覆盖实现在运行时甚至由用户通过 JSON 配置动态调整。规则二组件内禁用 if / lighten / darken新增变量统一放到 _properties.scss这是对样式库贡献者最硬性的一条约束。components内的组件样式文件不要使用if、lighten、darken等函数因为这类 Sass 能力无法作用于 CSS 自定义变量——一旦某个值来自var(--xxx)编译期就无法对它再做条件判断或颜色运算。正确的做法是为组件新增变量放进 scss/_properties.scss 里这样变量既能被用户自定义覆盖又能保持组件样式代码的简洁一致。源码印证_properties.scss中确实集中声明了海量 CSS 自定义变量其结构分层清晰:root, .AMISCSSWrapper { --primary: var(--colors-brand-5); --primary-onHover: var(--colors-brand-6); --primary-onActive: var(--colors-brand-4); --borderColor: var(--colors-neutral-line-8); --borderColorLight: var(--colors-neutral-line-10); --borderRadius: var(--borders-radius-3); --gap-xs: var(--sizes-size-3); --gap-sm: var(--sizes-size-5); --gap-base: var(--sizes-size-7); ... }从这份文件可以看出 amis-ui 的变量组织惯例通用语义变量--primary、--success、--borderColor、--gap-*等与品牌 Token--colors-brand-5、--colors-neutral-line-8、--sizes-size-3、--fonts-size-7等之间是二次映射关系改动底层 Token 即可联动全局组件专用变量如--Audio-*、--Checkbox-*、--dialog-size-*也统一声明在此文件或_components.scss组件 SCSS 只负责消费这些变量。同时scss/_mixins.scss 中用于生成颜色变体的mixin color-schema/color-schema-lt等均已改用 Dart Sass 的新模块函数color.adjust(...)如调整 lightness、saturation并且mixin color-variant被明确标注为deprecated 不建议用了——这正体现了项目对旧式lighten/darken写法的淘汰趋势。整个components目录如 components/_button.scss中已检索不到lighten(/darken(的调用。规则三负数必须写成calc(var(--xxx) * -1)CSS 自定义变量的值无法直接在声明中加负号margin-top: -var(--gap-xs)是非法语法因此 amis-ui 约定负数的标准写法是使用calc()乘法。源码实例该写法在组件样式中已被广泛使用例如components/_button-group.scssmargin-left: calc(var(--ButtonGroup-borderWidth) * -1);components/_anchor-nav.scssmargin-bottom: calc(var(--Tabs-borderWidth) * -1);components/_button.scssmargin-left: calc(var(--gap-xs) * -1);components/_crud.scssmargin-top: calc(var(--Crud-toolbar-gap) * -1);这些场景大多用于实现负 margin 回拉如按钮组相邻按钮消除重复边框、锚点导航抵消滚动偏移。在贡献样式时凡是需要对var(--xxx)取负值都应严格遵循calc(var(--xxx) * -1)这一固定范式以保证与整个库的书写风格一致。规则四变量值中使用 Sass 功能必须用#{}插值包裹在 CSS 自定义变量的声明值里使用任何 Sass 功能函数调用、变量引用、运算时都必须用插值语法#{}包裹否则 Sass 无法正确将其输出到 CSS 变量值中。原文档给出的示例为--borderColorLight: #{lighten($borderColor, 5%)};源码印证#{}插值在 amis-ui 的变量文件中大量存在最典型的是配合px2rem()函数做单位换算scss/_properties.scss--borderWidth: #{px2rem(1px)};scss/_properties.scss--scrollbar-width: #{px2rem(17px)};scss/_components.scss--Checkbox-borderRadius: #{px2rem(2px)};scss/_components.scss--Form--horizontal-label-widthMd: #{px2rem(136px)};其中px2rem()定义在 scss/_functions.scss 中以$remFactor: 16px为基准将像素值换算为 rem。此外_functions.scss还提供tint、shade等颜色函数基于 RGB 通道向白/黑方向偏移这些函数同样只能在#{}插值中输出为 CSS 变量值。规则五Chrome DevTools 中点变量无响应时的处理由于 amis-ui 在:root上声明的 CSS 自定义变量数量极其庞大仅_components.scss就有 4300 余行、上千个变量在 Chrome 开发者工具的 Styles 面板中直接点击变量名往往会没有反应。原文档给出的处理方式是先在开发工具里点一下显示全部变量把变量列表完整展开后再进行操作。这里补充一个实用的工作流建议打开页面后用 DevTools 选中目标元素在 Styles 面板找到:root或.AMISCSSWrapper块先点击面板中显示全部 CSS 变量的按钮再搜索定位你要调整的变量结合 docs/zh-CN/style/css-vars.md 中的变量速查表基础颜色、字体、边框等分门别类列出快速定位语义变量例如--primary影响主按钮颜色、--fontSizeBase默认 14px、--borderColor控制边框颜色就地修改变量值即可实时预览确认效果后再将改动回填到主题变量文件中。主题定制CSS 变量在运行时如何被消费双轨制的最终目的是支持多主题与运行时定制。在 scss/themes 目录下项目为每种内置主题提供了独立的变量覆盖文件cxd、antd、ang三套主题及其对应主文件cxd.scss、antd.scss、ang.scss深色主题_dark-variables.scss与dark.scssIE11 兼容版本cxd-ie11.scss、antd-ie11.scss、ang-ie11.scss、dark-ie11.scss辅助脚本extract-antd-color.py用于从 Ant Design 色板中提取颜色 Token。主题文件通过在编译期覆盖:root或.AMISCSSWrapper中的 CSS 变量值实现换肤而.AMISCSSWrapper这一包裹类选择器意味着 amis 的变量作用域可以被限定在某个容器内避免污染宿主页面这一点正是 CSS 自定义变量运行期可覆盖能力的具体落地。对于业务侧而言无需改动 SCSS 源码仅靠注入自定义变量即可完成大部分主题定制工作。总结amis-ui 的样式工程给出了一个编译期能力 运行期能力互补的可行方案关注点推荐手段依据文件颜色修改含派生色计算SCSS 变量scss/_variables.scss组件样式细节、间距、圆角、字体CSS 自定义变量scss/_properties.scss、scss/_components.scss组件新增可定制变量加入_properties.scss组件内禁止if/lighten/darkenscss/README.md、scss/_mixins.scss负数取值calc(var(--xxx) * -1)components/_button-group.scss 等变量值内使用 Sass 能力#{}插值包裹scss/_functions.scss调试变量DevTools 先展开全部变量docs/zh-CN/style/css-vars.md遵循这 5 条规范开发者既能为 amis-ui 贡献风格统一、可被用户覆盖的样式代码也能准确判断改颜色该动 SCSS 变量还是自定义变量避免踩中自定义变量不支持颜色运算的经典陷阱。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考