解决 React + GrapesJS iframe 中 CSS-in-JS 样式隔离问题

解决 React + GrapesJS 中 CSS-in-JS 样式隔离问题

当你的可视化编辑器和主应用"抢"样式时，该怎么办？

背景

在做一个低代码平台时，我们使用 GrapesJS 作为可视化设计器，它运行在一个 iframe 中。同时，主文档（iframe 外部）也有大量的 Ant Design 组件，比如侧边栏的树形菜单、弹出的模态框等。

架构大概是这样：

复制代码

主文档 (document)
├── 侧边栏（模块树、弹框）  ← Ant Design 组件
└── GrapesJS 编辑器
    └── iframe (canvas)
        └── React 组件     ← 也是 Ant Design 组件

遇到的问题

一开始都正常。但当用户在 iframe 的设计器中操作后，再回到主文档打开一个弹框------样式全丢了！输入框变成原生的，按钮没有样式，整个弹框惨不忍睹。

最奇怪的是：刷新页面后又恢复正常。

排查过程

1. 为什么需要 Patch？

Ant Design 5.x 使用 CSS-in-JS，样式是动态生成的。当 React 组件渲染时，@ant-design/cssinjs 会调用 document.createElement('style') 创建样式标签，然后插入到 <head> 中。

问题来了：iframe 有自己独立的 document。如果我们在主文档创建样式标签，再移动到 iframe 的 <head> 里，某些浏览器行为会不一致。

所以我们做了一个"黑科技"：Patch 掉 document.createElement，让 iframe 内的组件用 iframe 自己的 document 创建样式。

javascript 复制代码

// 简化示意
document.createElement = function(tagName) {
  if (tagName === 'style' && 正在渲染iframe组件) {
    return iframeDocument.createElement('style');
  }
  return originalCreateElement(tagName);
};

2. 那主文档的样式为什么会丢？

关键在于"正在渲染 iframe 组件"这个判断。我们用了一个全局变量：

javascript 复制代码

window.__CURRENT_STYLE_CONTAINER__ = iframeHead; // 渲染 iframe 组件时设置

问题是：这个变量设置后没有清除。

当用户操作 iframe 后，这个变量还指向 iframe 的 head。之后用户打开主文档的弹框，弹框的样式也被"劫持"到了 iframe 里------而 iframe 里的样式对主文档是不可见的！

3. 为什么刷新能恢复？

刷新后，这个全局变量被重置为 undefined，patch 不会触发，样式正常注入到主文档。

解决方案

核心思路：在主文档组件渲染时，主动把这个标志"抢"回来。

我们创建一个"重置组件"，包裹整个应用：

tsx 复制代码

const StyleContainerReset: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  useLayoutEffect(() => {
    // 每次渲染时，确保样式容器指向主文档
    window.__CURRENT_STYLE_CONTAINER__ = document.head;
  });
  
  return <>{children}</>;
};

// 在 main.tsx 中使用
<ConfigProvider>
  <StyleContainerReset>
    <App />
  </StyleContainerReset>
</ConfigProvider>

为什么用 useLayoutEffect？

React 的 useLayoutEffect 在 DOM 变化后、浏览器绘制前同步执行。这意味着：

用户点击按钮打开弹框
React 开始渲染弹框组件
useLayoutEffect 执行，重置标志为 document.head
弹框的 CSS-in-JS 开始注入样式
样式正确地进入主文档的 <head>

而 iframe 的组件仍然能正常工作，因为它们通过 $mountReactComponent$ 渲染，会在渲染前把标志设置为 iframeHead。

总结

场景	标志值	样式去向
主文档组件渲染	`document.head`	主文档 ✓
iframe 组件渲染	`iframeHead`	iframe ✓

这个问题的根源是全局状态污染。当你在一个应用中同时有主文档和 iframe 两个渲染上下文时，共享的全局变量会互相影响。

解决方法就是：谁用谁负责重置。主文档在渲染前把标志重置为自己的 head，iframe 组件在渲染前把标志设置为 iframe 的 head。各管各的，互不干扰。

本文记录了一次真实的 CSS-in-JS 样式隔离 debug 过程。如果你也在做类似的"可视化编辑器嵌入主应用"的架构，希望这篇文章能帮你少踩坑。