实战:qiankun 微前端主题隔离,把 data-theme 从 html 挪进自己的容器

业务背景

前两篇解决了组件库的类名冲突,但还有一类问题更隐蔽:主题变量互相串味。

我们的 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](有空格)= 容器的后代带这个属性,基本用不上。

系列文章

实现思路

  1. 给应用一个全局唯一的根容器 id,主题标记只挂在它上面;
  2. 用一份 rootElement.ts 统一管理根容器的获取和创建,兼容独立运行和 qiankun 两种场景;
  3. 把代码里所有 document.documentElement 的主题操作换掉;
  4. 第三方主题包的 CSS 是构建产物、改不了源码,用 loader 把 :root 批量改写成 #sub-a-root;
  5. 清掉 html 模板里硬编码的 data-theme,避免首屏就污染全局;
  6. 弹层挂载点跟着迁移,否则弹窗里的主题变量全部失效。

实现步骤

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 检查

  1. 选中 <html>,确认没有 data-theme 属性,也没有 light / dark 类名;
  2. 选中 #sub-a-root,确认有 data-theme 和对应类名;
  3. 切换主题,只有本应用 DOM 在变;
  4. 打开 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 样式正常。

业务开发注意事项

  1. 新代码里不要再出现 document.documentElement.setAttribute('data-theme', ...),统一走 getRootElement();
  2. 新增第三方主题包,确认它的 dist 路径进了 loader 的 include;
  3. 写全局变量声明,用 #sub-a-root 而不是 :root;
  4. 任何新加的弹层容器,都要确认挂在根容器内;
  5. 升级主题包后重跑校验脚本,重点看 :root[data-theme] 有没有回来。
相关推荐
疯华整猫7 分钟前
别再抄 Flutter 了:2026 年 Android / iOS / 小程序跨端架构选型的四本成本账
android·前端·ios
Warson_L8 分钟前
上传头像 (angular 16)
前端·angular.js
zhanlang021713 分钟前
HTML 零基础入门到企业实战【第七章 表单标签|7.1 表单核心作用:数据收集、用户交互原理】
前端·html·交互
FungLeo28 分钟前
成为全栈·Vue 管理后台篇·Biome、类型检查、构建和API 代理如何组成质量门禁
前端·javascript·vue.js·typescript·vite·前端工程化·biome
夕水1 小时前
受不了满屏广告的诗词网站,以及很多打不开的诗词网站,我干脆自己租服务器用trae重构了一个(纯公益、无广告)
前端·javascript
Brookty1 小时前
HTML基础知识:表格布局、表单数据提交、元素标识与资源相对路径
前端·html
徐小夕1 小时前
开源!我们用知识图谱重构了电子档案,AI 驱动全文智能关联
前端·vue.js·github
不一样的少年_2 小时前
用了这 Skill,前端兄弟都觉得好
前端·后端·ai编程
恋猫de小郭2 小时前
Flutter Native Interop 稳定了,Platform Channel 要退场了
android·前端·flutter