业务背景
前两篇解决了组件库的类名冲突,但还有一类问题更隐蔽:主题变量互相串味。
我们的 qiankun 平台里,一堆跑了多年的老系统:jQuery 时代的后台、Vue2 的中台、几个 React 应用。因为之前都是独立应用,不涉及互相影响的问题,所以它们的主题切换基本都是一套写法:
js
document.documentElement.setAttribute('data-theme', 'dark');
documentElement 就是 <html>。而所有子应用共用同一个 <html>:
css
<html data-theme="dark"> ← 一个节点,几个应用都在读写
├─ 子应用 A 的 DOM
└─ 子应用 B 的 DOM
后果很直接:
- A 切了暗色,B 的
[data-theme=dark]规则立刻跟着生效,页面莫名其妙变黑; :root { --color-primary: ... }声明的变量挂在<html>上,所有子应用都能读到,颜色互相覆盖;- 主应用自己也维护一套
data-theme,三家一起抢同一个属性,谁最后写谁生效,表现上就是,谁最后打开,就是采用谁的主题样式和颜色,打开的顺序不同,展示的样式也是不同。
唯一可行的做法是:退出这场争夺------不往 <html> 写主题,也不再依赖 <html> 上的主题。
具体就是把主题标记挪到本应用自己的根容器上,所有全局选择器跟着挪。
两件事必须一起改
很多人以为把 [data-theme] 挪走就完事了,结果还有一半颜色不对。因为这里其实是两个独立的全局选择器:
[data-theme='dark']:属性选择器,"谁带属性谁命中",任何元素带上都会生效;:root:等价于html,整个文档唯一的根节点,--xxx变量声明在它上面就是全局面量。
所以 :root { --ag-row-height: 25px } 这种写法,即使不带 data-theme,变量也已经污染到全局了。
对应关系:
text
:root → #sub-a-root
:root[data-theme=dark] → #sub-a-root[data-theme=dark]
[data-theme=dark] → #sub-a-root[data-theme=dark]
[data-theme=dark] .foo → #sub-a-root[data-theme=dark] .foo
注意无空格和有空格是两回事:
#sub-a-root[data-theme=dark](无空格)= 容器自身带这个属性,用来声明变量;#sub-a-root [data-theme=dark](有空格)= 容器的后代带这个属性,基本用不上。
系列文章
实现思路
- 给应用一个全局唯一的根容器 id,主题标记只挂在它上面;
- 用一份
rootElement.ts统一管理根容器的获取和创建,兼容独立运行和 qiankun 两种场景; - 把代码里所有
document.documentElement的主题操作换掉; - 第三方主题包的 CSS 是构建产物、改不了源码,用 loader 把
:root批量改写成#sub-a-root; - 清掉 html 模板里硬编码的
data-theme,避免首屏就污染全局; - 弹层挂载点跟着迁移,否则弹窗里的主题变量全部失效。
实现步骤
1. 确定根容器 id
public/index.html 里留一个容器:
html
<div id="sub-a-root"></div>
id 必须全局唯一,别用
app、root、main这种通用词,跟别的系统撞上就白做了。推荐直接带应用标识,比如sub-a-root。
2. 统一管理根容器
独立运行时容器来自 index.html;qiankun 下主应用只给一个空壳容器,#sub-a-root 得子应用自己建。所以抽一个模块统一处理:
typescript
// src/rootElement.ts
// 统一管理子应用根容器 #sub-a-root。
// 独立运行用 index.html 里的容器;qiankun 下主应用只给空容器,由这里补建。
// 主题标记、antd 弹层挂载点、message 容器都依赖它,必须唯一且能拿到。
export const ROOT_ID = 'sub-a-root';
let rootElement: HTMLElement | null = null;
/** 获取(必要时创建)根容器,container 为 qiankun 传入的 props.container */
export function ensureRootElement(container?: HTMLElement): HTMLElement {
if (rootElement && rootElement.isConnected) {
return rootElement;
}
// 1. 先在 qiankun 容器内找
if (container) {
const existed = container.querySelector<HTMLElement>(`#${ROOT_ID}`);
if (existed) {
rootElement = existed;
return rootElement;
}
}
// 2. 退回全局查找(独立运行,或主应用已经提供)
const globalEl = document.getElementById(ROOT_ID);
if (globalEl) {
rootElement = globalEl;
return rootElement;
}
// 3. 都没有:在 qiankun 容器内建一个
const created = document.createElement('div');
created.id = ROOT_ID;
(container || document.body).appendChild(created);
rootElement = created;
return rootElement;
}
/** 读当前根容器,可能为 null(卸载后调用需要判空) */
export function getRootElement(): HTMLElement | null {
if (rootElement && rootElement.isConnected) {
return rootElement;
}
return document.getElementById(ROOT_ID);
}
/** 卸载时清掉缓存引用 */
export function resetRootElement() {
rootElement = null;
}
入口里用起来:
tsx
import { ensureRootElement } from './rootElement';
function render(props: { container?: HTMLElement } = {}) {
const { container } = props;
const target = ensureRootElement(container);
root = ReactDOM.createRoot(target);
root.render(<App />);
}
3. 换掉所有主题设置代码
搜 document.documentElement,把主题相关的全部换掉。注意是同步替换,漏一处就等于没做。
tsx
import { getRootElement } from './rootElement';
// 主题只挂在本应用根容器上,不能挂 <html>,
// 否则作为 qiankun 子应用会和主应用、别的子应用互相污染
useLayoutEffect(() => {
getRootElement()?.setAttribute('data-theme', themeName);
}, [themeName]);
有些页面还需要根据来源调字号,这类"本应用内的外观差异"也放到容器类名上,别碰 <html>:
tsx
useLayoutEffect(() => {
const rootEl = getRootElement();
if (!rootEl) return;
if (getQueryParam('source') === 'legacy') {
rootEl.classList.add('legacy-font');
} else {
rootEl.classList.remove('legacy-font');
}
}, []);
例外:像
data-qiankun-flag这类明确给主应用读 的标记,仍然要挂在<html>上,不要一起迁移,否则主应用读不到。
4. 用 loader 改写第三方主题 CSS
主题包(@your-ds/theme-light、theme-dark)的 CSS 是构建产物,改不了源码,只能构建期改写:
javascript
// loaders/scope-theme-root-loader.js
// 把主题包 CSS 里的 :root 选择器改写到本应用根容器,实现主题隔离。
// 前提:已确认主题包产物中 :root 全部是主题变量块,没有 @media / @supports 依赖 :root 的写法。
const ROOT_SELECTOR = '#sub-a-root';
module.exports = function scopeThemeRootLoader(source) {
return source.replace(/:root(?![\w-])/g, ROOT_SELECTOR);
};
几个细节:
- 正则加了
(?![\w-]),避免误伤:rooted这类写法,也避免把选择器名里的字符改坏; - 这是纯字符串替换,注释里的
:root也会被改,不影响运行但会干扰 grep; - 它只处理
:root。如果主题包里还有裸[data-theme=dark]选择器,replace(/:root/g)是命中不了的,得单独加一条规则,或者先确认包里没有这种写法(我们这份主题包实测全是:root[data-theme=xxx],所以够用); - 如果主题包里存在
@media包着:root的写法,字符串替换依然能命中,但建议先用 postcss 的walkRules走一遍,确认语义正确。
5. 注册 loader
typescript
import path from 'path';
config.module.rules.push({
test: /\.css$/,
include: [
// 精确命中主题包的构建产物,不要写成整个 @your-ds(会误伤别的包)
/node_modules[\\/]@your-ds[\\/]theme-(light|dark)[\\/]dist[\\/](index|aggrid)\.css$/,
],
enforce: 'pre',
use: [{ loader: path.resolve(__dirname, 'loaders/scope-theme-root-loader.js') }],
});
和 AG-Grid 的 scope loader 会不会打架?不会。两个都是字符串层面的改写,谁先谁后结果完全一样。我实测过这两种顺序:
text
:root[data-theme=light] .ag-theme-alpine
→ 主题 loader 先: #sub-a-root[data-theme=light] .sub-a-aggrid-scope.ag-theme-alpine
→ scope loader 先: #sub-a-root[data-theme=light] .sub-a-aggrid-scope.ag-theme-alpine
最终产物一致,所以不用纠结注册顺序,但两者都必须 enforce: 'pre'。
6. 清掉模板里的硬编码
diff
- <html lang="en" data-theme="light">
+ <html lang="en">
不清掉的话,页面一加载就往全局写了一次主题,等于白改。
关于首屏闪烁:移除硬编码后,React 挂载前 <html> 上没有 data-theme。因为容器此时还是空的,视觉上通常看不出来。实在要压掉闪烁,可以在模板里加个内联脚本,提前给容器设好:
html
<script>
(function () {
var t = localStorage.getItem('theme') || 'light';
var el = document.getElementById('sub-a-root');
if (el) {
el.setAttribute('data-theme', t);
el.classList.add(t);
}
})();
</script>
7. 弹层挂载点迁移(最容易漏的一步)
antd 的 Modal / Drawer / Select 下拉 / Tooltip,还有静态 message,默认都挂到 document.body。
而主题样式现在被限定在 #sub-a-root[data-theme] 下面,body 不在容器内,于是:
--xxx变量读不到,弹窗颜色、圆角全错;- 弹层里的组件样式命中不了改写后的规则。
解决办法是把弹层挂进容器:
tsx
import { message, ConfigProvider } from 'antd';
import { getRootElement } from './rootElement';
// 弹层默认挂 body,会脱离主题作用域,统一挂到根容器内
const getPopupContainer = (): HTMLElement => getRootElement() || document.body;
message.config({ getContainer: getPopupContainer });
<ConfigProvider locale={zhCN} prefixCls="sub-a" getPopupContainer={getPopupContainer}>
再配 AG-Grid 的弹窗,就按第三篇说的 onGridReady 里 setPopupParent 处理。
全屏 Modal 挂进容器后可能被容器的
overflow或transform限制,遇到这种情况给容器留overflow: visible,或用position: fixed的浮层容器单独承载。
8. 原子类 dark: 变体(可选)
如果用了 UnoCSS / Tailwind 的 dark: 变体,要确认变体选择器还认这个层级。默认类策略生成的是 .dark .foo,只要 .dark 挂在容器上、.foo 在容器内,仍然能命中。真正失效的是挂在 body 上的弹层;遇到跨层级的情况,可以用 :is() 双向兼容:
css
/* .dark 在容器自身或容器祖先上都能命中 */
:is(#sub-a-root .dark, .dark #sub-a-root) .foo { ... }
生产踩坑记录
坑 1:只改了 JS,没改 CSS
现象:主题切换完全没反应。
原因:属性已经挂到 #sub-a-root,但选择器还是 :root[data-theme],谁都不匹配。
坑 2:只改了 CSS,没改 JS
现象:一样完全失效。
原因:选择器要求容器带属性,属性却还写在 <html> 上。
坑 3:只搜了 [data-theme],漏了 :root[data-theme]
现象:只有一部分变量生效,颜色对一半。
原因::root[data-theme=...] 是组合写法,只按 [data-theme] 搜索很容易漏。两个关键词都要搜,grep -rn ":root" 和 grep -rn "\[data-theme" 各跑一遍。
坑 4:根容器 id 撞车
现象:改了还是互相污染。
原因:id 不唯一,getElementById 拿到的是别人的容器,主题写到了别人身上。
坑 5:容器还没挂载就设置主题
现象:报 Cannot read properties of null,或者主题静默丢失。
原因:getElementById 返回 null。统一走 ensureRootElement / getRootElement,别在模块顶层直接取 DOM。
坑 6:有代码在 <html> 上读 CSS 变量
现象:主题切了,图表 / 一些自定义取色逻辑不跟着变。
原因:类似 getComputedStyle(document.documentElement).getPropertyValue('--color-primary') 的写法,变量已经搬到容器上了,读 <html> 自然取空。这类代码要改成读 getRootElement()。
坑 7:body 级样式没地方放了
现象:页面最外层的背景色、滚动条样式失效。
原因:以前靠 :root / body 上的变量,现在变量只在容器内。这类样式要给根容器补上(背景、min-height),不再指望 body。
坑 8:原子类 dark: 变体失效
现象:暗色下部分原子类不生效。
原因:变体选择器假设 .dark 在 <html> 上,迁移后层级变了,或者元素本身在容器外。
坑 9:把给主应用读的标记也迁走了
现象:主应用读不到本应用状态,联动功能坏掉。
原因:data-qiankun-flag 这类标记被一起搬到了容器上。原则是只迁主题相关标记,给外部读的标记留在 <html>。
坑 10:弹层样式裸奔
现象:Modal / 下拉打开后颜色和圆角全错,甚至像没加载样式。
原因:弹层挂在 document.body,不在 #sub-a-root[data-theme] 的作用域里。
校验方式
DevTools 检查
- 选中
<html>,确认没有data-theme属性,也没有light/dark类名; - 选中
#sub-a-root,确认有data-theme和对应类名; - 切换主题,只有本应用 DOM 在变;
- 打开 Modal / Drawer / Select 下拉,确认弹层 DOM 位于
#sub-a-root内且样式正常。
产物校验脚本
保存为 check-theme-scope.js,构建后执行 node check-theme-scope.js。
javascript
const fs = require('fs');
const path = require('path');
function walk(dir) {
return fs.readdirSync(dir).flatMap((name) => {
const full = path.join(dir, name);
return fs.statSync(full).isDirectory() ? walk(full) : [full];
});
}
let residual = 0;
let scoped = 0;
let css = '';
for (const file of walk('dist')) {
if (file.endsWith('.css')) css += fs.readFileSync(file, 'utf8');
}
// 去掉注释,避免注释里的 :root 影响判断
const cleaned = css.replace(/\/\*[\s\S]*?\*\//g, '');
residual += (cleaned.match(/:root[^\w-]/g) || []).length;
scoped += (cleaned.match(/#sub-a-root\[data-theme/g) || []).length;
console.log(':root 残留:', residual, '(主题包相关产物应为 0,其它三方库可能有,需人工确认)');
console.log('#sub-a-root[data-theme] 命中:', scoped, '(必须大于 0)');
多子应用联调
- 同时打开本应用和另外两个子应用;
- 本应用切主题,其他子应用样式不动;
- 其他子应用切主题,本应用不动;
- 本应用颜色、背景、边框全部跟着变;
- 弹窗、下拉、Tooltip、
message样式正常。
业务开发注意事项
- 新代码里不要再出现
document.documentElement.setAttribute('data-theme', ...),统一走getRootElement(); - 新增第三方主题包,确认它的
dist路径进了 loader 的include; - 写全局变量声明,用
#sub-a-root而不是:root; - 任何新加的弹层容器,都要确认挂在根容器内;
- 升级主题包后重跑校验脚本,重点看
:root[data-theme]有没有回来。