【Web技术】990- 前端站点一键支持暗色模式

男娘i 2022-10-07 07:53 143阅读 0赞

> 作者：冯伟尧 & 石嘉 & 刘大畅

![09c43e0aae4858eb9279af9dda0b99fb.gif][]

## 需求 & 现状 ##

作为近两年的「新时尚」，暗色/深色模式已经几乎成为了各家系统、应用以及 Web 站点的标配功能。想要支持暗色模式，本质是判断在暗色模式下，更改生效的颜色值。在 Web 站点中，一种简单的做法是通过 CSS 变量\[1\] 来实现：

.button {
        background-color: var(--color-bg-0);
    }
    body {
        --color-bg-0: #fff;
    }
    body[theme-mode=dark] {
        --color-bg-0: #000;
    }

CSS 变量就是一些自定义的属性，遵循正常的的样式覆盖原则。如上所示，`button`的背景颜色由 `--color-bg-0` CSS 变量决定，当给 body 设置 `<body theme-mode="dark">...</body>` 时， `--color-bg-0: #000` 会覆盖 `--color-bg-0: #fff`，此时 `button` 背景色为黑色。

以上即是 **Semi Design** 实现暗色模式的大致原理。如果你想让自己的站点支持暗色模式，**一个关键点是，CSS 样式中所有的颜色值必须使用 Semi Design 颜色变量（比如前面的`--color-bg-0`)。**

现在的问题是，对于已有项目，为了支持暗色模式，必须将项目中所有颜色值手动替换为 Semi 颜色变量，这个过程非常繁琐且工作量巨大。因此本文将介绍 Semi 团队在内部项目中如何通过自动化的方式来解决这个问题。

为了避免理解歧义，这里统一名词概念：

*  **颜色字面量**：指样式文件中确定的颜色值，如 `white`, `#FFF`, `rgb(23,45,0)` 等；

*  **颜色变量**：指与颜色相关的 CSS 变量，这里特指 Semi 颜色变量，如 `--color-primary`；

## 解决思路 ##

主要关注两点：

**关注点一**：如何解析识别 css/scss/stylus 等样式文件中的【颜色字面量】，如：`background: white` 中的 `white`。

**关注点二**：计算识别的【颜色字面量】是否可以替换为 Semi 主题包中提供的【颜色变量】如：var(--color-bg-0)。如果【颜色字面量】与【颜色变量】对应的颜色值相同或相近则认为可以替换。

对于第二点，计算是否有对应的颜色变量，可以使用 chorma-js\[2\]。chorma-js 可以实现任意颜色格式之间的转换以及计算颜色之间的相似度，比如：`chroma.distance(color1, color2)`。

更重要的是第一点，如何解析识别【颜色字面量】，此时首先想到的是 PostCSS。

### PostCSS\[3\] ###

> PostCSS is a tool for transforming styles with JS plugins. These plugins can lint your CSS, support variables and mixins, transpile future CSS syntax, inline images, and more.

PostCSS 与 CSS 的关系，就相当于 Babel 与 JavaScript。PostCSS 可以将 CSS 解析为抽象语法树 (AST)，并提供了 API 允许分析和转换 CSS 文件的内容。

如下图所示，左边为一段 CSS 代码，右边为使用 PostCSS 解析后的结果（可访问 AST explorer 站点\[4\] 体验）：

![9c2a13f2435937b315e88a3afa258abc.png][]

不仅仅是 CSS，通过引入插件，PostCSS 可以解析任何形式的样式代码，比如 `Sass`, `Less`, `Stylus`以及 `JSX` 中的样式代码。

#### 如何识别颜色值 ####

CSS 中指定颜色值的方式有三类，分别为：

*  **颜色关键字**，如：`white`, `blue` 等等;

*  **RGB 16 进制形式**，如：`#FFF`;
 *  **函数形式**，如：`rgb(255, 255, 0)` 或者 `rgba(255, 0, 255, 0.5)`，`hsl(0deg, 0%, 13%)` 或者 `hsla(0deg, 0%, 13%, 1)` 或者 `hwb(...)` `gray(...)`;

因此借助 PostCSS 解析后的结果，针对以上三种形式的颜色值，识别算法为：

*  **CSS 属性值中是否包含穷举的** **颜色关键字\[5\]**；
 *  **CSS 属性值以 '\#' 开头则认为是 RGB 16 进制形式**；
 *  **CSS 属性值为函数形式且名称为** `rgb`**,** `rgba`**,** `hsl`**,** `hsla` **等则认为是函数形式**。

由此，基于 PostCSS 我们可以完成样式的解析以及颜色的识别。如果要达到自动完成项目中样式文件的颜色值替换工作，只需要添加收集项目中的样式文件的逻辑，并封装为 CLI 工具方便使用即可。

PostCSS 已经能够满足我们的需求，然而，还有另一种实现方式，Stylelint。

### Stylelint\[6\] ###

> A mighty, modern linter that helps you avoid errors and enforce conventions in your styles.

Stylelint 与 CSS 的关系，就相当于 ESLint 与 JavaScript 的关系。Stylelint 是针对样式文件的代码审查工具。Stylelint 底层基于 PostCSS，对样式文件进行解析分析，可以对 CSS/Sass/Stylus/Less 等样式文件进行审查。

比如 Stylelint 其中一个规则，`color-named`，不允许使用**颜色关键字**，效果如下：

![44a692f0ce499c582e46dfae1f3544ba.png][]

当我们在代码中使用了类似 `white` 颜色关键字，Stylelint 会给出提示，借助编辑器插件，我们能够在编码过程中获得实时提示，非常方便。

每个规则在 Stylelint 中都是一个插件，插件的输入是样式文件通过 PostCSS 解析后的抽象语法树，插件可以基于 PostCSS API\[7\] 遍历语法树，分析/修改样式代码。因此类似规则 `color-named`，我们也可以实现一个 Stylelint 插件，分析并识别样式文件中的【颜色字面量】，并给出提示，针对有对应的 Semi 颜色变量的，支持自动替换（autofix）。具体可以查看官方的插件开发文档\[8\]。

相比 PostCSS，使用 Stylelint 的好处是：

1.  **不需要关心样式文件的解析，只需要关注拿到解析结果后如何分析**
2.  **不需要关心根据不同的样式语言，引入不同的 PostCSS 解析插件**
3.  **StyleLint 有完善的 CLI 工具以及 VS Code 插件，可以直接复用**

综上我们最终基于 Stylelint 来实现需求。

## 最终的能力 & 使用方式 ##

> 配合 Stylelint 可以达到如下效果。

*  通过 StyleLint CLI 命令行工具一键【查找 & 替换】所有颜色变量;

*  通过 Stylelint 编辑器插件，写码过程中提示哪些【颜色字面量】没有使用 Semi 【颜色变量】，可设置保存时自动替换;

### Step 1: 安装 npm 包 ###

$ npm i -D stylelint @ies/stylelint-semi

### Step 2: 添加/更改配置文件 ###

根目录下添加 `.stylelintrc.json` 文件，配置 `@ies/stylelint-semi` 插件与 `semi/color-no-literal` 规则：

{
      "plugins": ["@ies/stylelint-semi"],
      "rules": {
        "semi/color-no-literal": [true, { "severity": "warning", "fixExact": false }]
      }
    }

### Step 3: 执行 CLI 命令 ###

$ npx stylelint "**/*.scss"

执行后，会检测项目下所有 `.scss` 文件，以下写法将会得到提示：

.banner {
        color: white;
        background: #eee;
        border: 1px solid rgb(0, 0, 0);
    }

![eb3cee0f237bcaaa953defaaaebd13a8.png][]

如果要替换为 Semi 颜色变量，可以使用：

$ npx stylelint "**/*.scss" --fix

替换后的结果为：

.banner {
        color: var(--color-white);
        background: var(--color-tertiary-light-hover);
        border: 1px solid var(--color-black);
    }

### Step 4: 编辑器提示 ###

VS Code 中安装 Stylelint 插件\[9\]。此时鼠标 hover 到颜色值会有以下提示：

![7d3cbae1840b95dd84567ecabcf070ff.png][]

## 实际效果展示 ##

支持暗色模式前后的效果：

**浅色版**

![eb3ac219bea5708c014cb3298342c7fd.png][]

**深色版**

![ed0ac6bc34361031114f1776c6d12e9c.png][]

## 欢迎反馈 ##

![2b25ef2ccf403e3d5867786e0f82b62b.png][]

这里是 Semi Design 团队，Semi 是由互娱社区前端团队与 UED 团队共同设计开发并维护的设计系统。包括设计语言、React 组件库、物料市场、Semi DV、主题商店等一整套全面、易用、优质的中后台解决方案。帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。

### 参考资料 ###

\[1\]

CSS 变量: *https://developer.mozilla.org/en-US/docs/Web/CSS/Using\_CSS\_custom\_properties*

\[2\]

chorma-js: *https://github.com/gka/chroma.js/*

\[3\]

PostCSS: *https://github.com/postcss/postcss*

\[4\]

AST explorer 站点: *https://astexplorer.net/\#/2uBU1BLuJ1*

\[5\]

颜色关键字: *https://developer.mozilla.org/en-US/docs/Web/CSS/color\_value\#color\_keywords*

\[6\]

Stylelint: *https://github.com/stylelint/stylelint*

\[7\]

PostCSS API: *https://api.postcss.org/*

\[8\]

官方的插件开发文档: *https://stylelint.io/developer-guide/rules\#add-autofix*

\[9\]

Stylelint 插件: *https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint*

\[10\]

Postcss plugin 开发文档: *https://github.com/postcss/postcss/blob/main/docs/writing-a-plugin.md*

\[11\]

Stylelint rule 开发: *https://stylelint.io/developer-guide/rules*

\[12\]

AST 调试工具: *https://astexplorer.net/\#/2uBU1BLuJ1*

![1f3e435d37109d7e52c14999ef8a2f7c.gif][]

[1. JavaScript 重温系列（22篇全）][1. JavaScript _22]

[2. ECMAScript 重温系列（10篇全）][2. ECMAScript _10]

[3. JavaScript设计模式 重温系列（9篇全）][3. JavaScript_ _9]

4. [正则 / 框架 / 算法等 重温系列（16篇全）][_ _ _ _ _16]

5. [Webpack4 入门（上）][Webpack4]|| [Webpack4 入门（下）][Webpack4 1]

6. [MobX 入门（上）][MobX] || [MobX 入门（下）][MobX 1]

7. 120[\+篇原创系列汇总][Link 1]

![530f0a513b98a0ec80b3369d89b96545.gif][]

回复“**加群**”与大佬们一起交流学习~

点击“**阅读原文**”查看 120+ 篇原创文章

###  ###

[09c43e0aae4858eb9279af9dda0b99fb.gif]: /images/20221005/375f459af2cb40c4909ceea6001aa080.png
[9c2a13f2435937b315e88a3afa258abc.png]: /images/20221005/4f4840cd280f43c78b3b66b1cdef3217.png
[44a692f0ce499c582e46dfae1f3544ba.png]: /images/20221005/6dc489de4ffd4111982ec544bcc26ecb.png
[eb3cee0f237bcaaa953defaaaebd13a8.png]: /images/20221005/f14fa74edfeb4aaab677ee890749355d.png
[7d3cbae1840b95dd84567ecabcf070ff.png]: /images/20221005/dda2fcb8bd064748a828ab3d193fac22.png
[eb3ac219bea5708c014cb3298342c7fd.png]: /images/20221005/64eb6cf783fa4d7cb62c11203c8a52a4.png
[ed0ac6bc34361031114f1776c6d12e9c.png]: /images/20221005/cf4af983378544e2ba1993ca4bfc74f8.png
[2b25ef2ccf403e3d5867786e0f82b62b.png]: /images/20221005/a0b8f0acde8a49209fe32438044dc51d.png
[1f3e435d37109d7e52c14999ef8a2f7c.gif]: /images/20221005/7ab329364602416e9127bc463b9f66e5.png
[1. JavaScript _22]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c224ea86b5adfc10c3aa1841be3879b9360d671e98cc73391c2490246f1348857b9821d32c&idx=1&mid=2458453187&scene=21&sn=a69b4d7d991867a07a933f86e66b9f55#wechat_redirect
[2. ECMAScript _10]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c224e086b5adf6dad41a0d36b77a9bfb4bc9f0d29a816266b3e28c892e54274967dbce380b&idx=1&mid=2458453193&scene=21&sn=e5392cb77bc17c9e94b6c826b5f52a83#wechat_redirect
[3. JavaScript_ _9]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c224e386b5adf554ab928cdeaf7ee16dbb2d895be17f2a12a59054a75b913470ca7649bbc7&idx=1&mid=2458453194&scene=21&sn=e7f0734b04484bee5e10a85a7cbb85c1#wechat_redirect
[_ _ _ _ _16]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c224e286b5adf432850f82db18cc8647d639836798cf16b478d9a6f7c81df87c6da5257684&idx=1&mid=2458453195&scene=21&sn=1e0c8b7ea8ddc207b523ec0a636a5254#wechat_redirect
[Webpack4]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c2251f86b5ac09dbbbb7c8e1d80c6cbd793a523cdfa690f8734def57812e616b9906aeec79&idx=1&mid=2458453302&scene=21&sn=904e40a421024ea0d394e9850b674012#wechat_redirect
[Webpack4 1]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c2251e86b5ac08464872cd880811423e0d1bbcebbe11dcac9d99fa38c5332c089c06d65d95&idx=1&mid=2458453303&scene=21&sn=422f2b5e22c3b0e91a8353ee7e53fed9#wechat_redirect
[MobX]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c2264c86b5af5aa7300a04d55efead6223e310d68e10222cd3577a25c783d3429f00767960&idx=1&mid=2458453605&scene=21&sn=0a506769d5eeb7953f676e93fb4d18eb#wechat_redirect
[MobX 1]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c2264086b5af5611524eedb0d409afe86d859dce6ceff1c17ddab49d353c385e45611a73fa&idx=1&mid=2458453609&scene=21&sn=f0c22e82f2537204d9b173161bae6b82#wechat_redirect
[Link 1]: http://mp.weixin.qq.com/s?__biz=MjM5MDc4MzgxNA%3D%3D&chksm=b1c224dd86b5adcbd98189315e60de6a0106993690b69927cc1c1f19fd8f591fefce4e3db51f&idx=2&mid=2458453236&scene=21&sn=daf00392f960c115463c5aaf980620b4#wechat_redirect
[530f0a513b98a0ec80b3369d89b96545.gif]: /images/20221005/498ce0fe35d742e89fb4d382f4fe2d7f.png