React项目SCSS Module中主题mixin仅全局生效问题咨询

项目背景 #

• 小型React测试应用，目标实现明暗主题切换能力，前期使用CSS变量实现主题方案，尝试切换为SCSS方案简化主题配置
• 项目样式目录规则：src/components目录下每个组件单独建文件夹，内部存放.tsx组件文件与.module.scss格式的SCSS模块化样式文件，单组件对应独立样式文件

原有实现逻辑 #

• 新建_themes.scss文件，定义light、dark两套主题的色值映射表
• 新建mixins.scss文件，引入sass:map模块与主题配置文件，编写themed混入：遍历所有主题配置，生成.theme-主题名 &格式的选择器规则，为当前选择器设置对应主题下的样式属性
• 全局入口样式index.scss引入混入文件，为body、code等全局标签调用themed混入设置主题样式
• App.tsx中通过Redux读取全局主题状态，在useEffect钩子中监听主题变化，清空html根元素原有类名后添加theme-主题名格式的类名，触发主题切换

问题表现 #

• 全局index.scss中通过themed混入设置的样式可正常随主题切换生效
• 组件SCSS Module内普通非主题样式可正常渲染：例如Header组件.wrapper类设置的宽高、红色文字均可正常显示，其余普通SCSS混入也可正常使用
• 仅组件内通过themed混入设置的主题相关样式（如主题背景色）完全失效

问题根因 #

SCSS Module的核心能力是对样式文件内的类选择器自动添加哈希后缀，实现样式作用域隔离。全局index.scss不是模块化样式文件，内部类名不会被做哈希转换，因此.theme-主题名选择器可以正常匹配html根节点的类名。
而在.module.scss文件中调用themed混入时，混入生成的.theme-主题名选择器会被SCSS Module识别为局部类，自动加上哈希后缀，最终编译出的选择器类似.theme-light__2xjas .Header_wrapper__9xksl，无法匹配html根节点上不带哈希的全局类theme-light/theme-dark，导致主题样式失效。

修复方案 #

方案1：给混入中的全局主题类添加全局标记 #

修改mixins.scss中的themed混入逻辑，使用SCSS Module提供的:global()语法包裹全局主题类，告知编译器该类名不需要做哈希转换，示例代码：

@use "sass:map";
@import "./themes";

@mixin themed() {
  @each $theme-name, $theme-config in $themes {
    :global(.theme-#{$theme-name}) & {
      // 此处写主题属性赋值逻辑
      @content;
    }
  }
}

修改后编译生成的选择器格式为.theme-light .Header_wrapper__9xksl，可以正常匹配DOM结构，主题样式即可生效。

方案2：改用属性选择器匹配主题 #

如果不想使用:global()语法，可调整主题切换实现逻辑，改为给html根节点设置data-theme属性标识当前主题，混入中使用属性选择器匹配主题，属性选择器不会被SCSS Module做哈希转换。
混入修改示例：

@mixin themed() {
  @each $theme-name, $theme-config in $themes {
    [data-theme="#{$theme-name}"] & {
      @content;
    }
  }
}

对应主题切换逻辑修改为操作html节点的data-theme属性即可，同样可以解决匹配失效问题。

内容的提问来源于stack exchange，提问作者Gonçalo Condeço