实战:AG-Grid 在 qiankun 下的 CSS 命名空间隔离

0 阅读4分钟

业务背景

公司内部有需要大量列表数据展示场景,购买了aggrid的商业版,但是没有对各个系统有对应的统一规范的要求,各个系统按照自己的系统风格,设计去对aggrid进行了改造。

AG-Grid 所有样式固定用 .ag-* 类名,而且没有提供自定义类名前缀的配置。几个子应用同时引 AG-Grid,全局 .ag-* 直接互相覆盖:行高被压扁、边框消失、右键菜单和筛选面板样式错乱。

一条路是改组件库源码,另一条是让别的子应用一起改,两条都不现实。最后选了第三条:构建期改写 CSS 选择器,给样式加命名空间。

核心逻辑很简单:DOM 保留 .ag-* 原样,所有 CSS 规则外面补一个祖先选择器,样式只在带指定 class 的容器内生效。

系列文章

实现思路

  1. 构建期自定义 pre loader,处理 AG-Grid 官方样式和设计系统提供的 aggrid 主题 CSS;
  2. 改写选择器,给样式加祖先作用域类 sub-a-aggrid-scope;
  3. ag-theme-* 主题类特殊处理:它必须和 scope 挂在同一个 DOM 上,所以用复合选择器而不是后代;
  4. 业务侧每个表格容器都挂 sub-a-aggrid-scope + 对应主题类;
  5. 弹窗单独处理:AG-Grid 的菜单、筛选面板默认挂 body,会跳出作用域,得手动改挂载节点。

这套 loader 是专门给 AG-Grid 写的,别直接复制给 Element、Vant。它们的选择器结构不一样,改写规则要重新验证。

而且这个是需要在代码中给aggrid的父级添加对应的类名。

实现步骤

1. 编写自定义 loader

新建 loaders/add-aggrid-scope-loader.js:

// loaders/add-aggrid-scope-loader.js
const SCOPE = 'sub-a-aggrid-scope';

// 主题类与 scope 挂在同一元素上,必须用复合选择器(中间没有空格)
const isThemeClass = (className) => className.startsWith('ag-theme-');

// :not() / :is() / :where() / :has() 内部不能插入作用域,否则会生成
// :not(.sub-a-aggrid-scope .ag-x) 这种非法选择器,浏览器直接丢弃整条规则。
// 先把伪类整体占位保存,处理完再还原。
const PSEUDO_RE = /:(?:not|is|where|has|matches|any)\([^(]*(?:\([^()]*\)[^()]*)*\)/g;

// 按组合符(空格 / > / + / ~)逐个复合选择器扫描
const COMPOUND_SCAN = /(^|[\s>+~])([^\s>+~]+)/g;

// 给单个选择器加作用域
const scopeOne = (selector) => {
  COMPOUND_SCAN.lastIndex = 0;
  let m;

  while ((m = COMPOUND_SCAN.exec(selector))) {
    const lead = m[1]; // 前置组合符,'' / 空格 / > / + / ~
    const compound = m[2]; // 复合选择器本体

    if (!compound.includes('.ag-')) continue;

    const agClass = compound.match(/\.ag-([a-zA-Z0-9_-]+)/);
    if (!agClass) continue;

    const start = m.index + lead.length;

    // 以 .ag- 开头且是主题类:scope 与它同元素,用复合形式
    // 其余(内部元素、button.ag-xxx、:root[data-theme] 后面的元素):scope 作祖先
    const sameElement =
      compound.startsWith('.ag-') && isThemeClass(`ag-${agClass[1]}`);
    const prefix = sameElement ? `.${SCOPE}` : `.${SCOPE} `;

    // 插在第一个含 .ag- 的复合选择器之前,前置条件(如 :root[data-theme])原样保留
    return selector.slice(0, start) + prefix + selector.slice(start);
  }

  return selector;
};

const scopeSelectorList = (selectors) => {
  // 1. 保护伪类内部(里面可能有逗号,不能参与后面的逗号分割)
  const placeholders = [];
  const protectedSelectors = selectors.replace(PSEUDO_RE, (pseudo) => {
    placeholders.push(pseudo);
    return `\u0000${placeholders.length - 1}\u0000`;
  });

  // 2. 按逗号拆开,逐个加作用域
  const scoped = protectedSelectors
    .split(',')
    .map((part) => {
      const trimmed = part.trim();
      if (!trimmed.includes('.ag-')) return part;
      return part.replace(trimmed, scopeOne(trimmed));
    })
    .join(',');

  // 3. 还原伪类
  return scoped.replace(/\u0000(\d+)\u0000/g, (_m, idx) => placeholders[Number(idx)]);
};

module.exports = function addAggridScopeLoader(source) {
  // 只改「{ 之前的选择器部分」,跳过 @font-face / @keyframes 的条件文本,
  // 避免破坏 font-family: "agGridAlpine"、url(...)、动画名
  return source.replace(/(^|})([^@]*?)(\{)/g, (match, lead, selectors, brace) => {
    if (!selectors.includes('.ag-')) return match;
    return `${lead}${scopeSelectorList(selectors)}${brace}`;
  });
};

改写的实际效果:

.ag-theme-alpine                      → .sub-a-aggrid-scope.ag-theme-alpine
.ag-cell                              → .sub-a-aggrid-scope .ag-cell
.ag-theme-alpine .ag-header-row       → .sub-a-aggrid-scope.ag-theme-alpine .ag-header-row
button.ag-side-button-button          → .sub-a-aggrid-scope button.ag-side-button-button
:root[data-theme=x] .ag-side-buttons  → :root[data-theme=x] .sub-a-aggrid-scope .ag-side-buttons
:root[data-theme=x] .ag-theme-alpine  → :root[data-theme=x] .sub-a-aggrid-scope.ag-theme-alpine
.ag-select:not(.a, .b)                → .sub-a-aggrid-scope .ag-select:not(.a, .b)

规则只有三条,记牢就不容易改错:

  1. 一条选择器只加一次 scope,加在第一个含 .ag- 的复合选择器之前;
  2. 同元素用复合、内部元素用后代;
  3. 伪类内部不动,逗号也要先保护再分割。

2. 注册 loader

rsbuild.config.ts:

import path from 'path';

config.module.rules.push({
  test: /\.(css|less)$/,
  include: [
    path.resolve(__dirname, 'src'),
    /node_modules[\\/]ag-grid/,
    // 设计系统提供的 aggrid 主题 css,第三方产物改不了源码,必须一起处理
    /node_modules[\\/]@your-ds[\\/]theme-[^\\/]+[\\/]dist[\\/]aggrid\.css$/,
  ],
  enforce: 'pre',
  use: [
    {
      loader: path.resolve(__dirname, 'loaders/add-aggrid-scope-loader.js'),
    },
  ],
});

3. 业务容器挂类名

关键点:sub-a-aggrid-scope 和 ag-theme-alpine 必须写在同一个 DOM 元素上,因为 loader 生成的是复合选择器。

<div className="sub-a-aggrid-scope ag-theme-alpine" style={{ height: 400, width: '100%' }}>
  <AgGridReact {...props} />
</div>

带斑马纹再加一层 stripe 类:

<div className="sub-a-aggrid-scope ag-theme-alpine ag-theme-alpine-stripe">

4. 弹窗处理(这里踩过很痛的坑)

先说我当时踩的坑:直接写 popupParent={containerRef.current} 当成 JSX 属性。

本地看着没问题,第一次打开筛选面板,弹窗直接飞到 body 上,样式裸奔。原因是首次渲染时 ref 还是 null,AG-Grid 拿不到节点就降级挂到 document.body,之后 ref 有值了也不会自动纠正。

正确做法是在 onGridReady 里用 API 指定挂载父容器:

import { useRef } from 'react';
import { AgGridReact } from 'ag-grid-react';

const MyTable = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  const handleGridReady = (params) => {
    // 表格就绪、ref 已赋值,这时才能把浮层挂回作用域容器
    if (containerRef.current) {
      params.api.setPopupParent(containerRef.current);
    }
  };

  return (
    <div
      ref={containerRef}
      className="sub-a-aggrid-scope ag-theme-alpine"
      style={{ height: 400, width: '100%' }}
    >
      <AgGridReact
        onGridReady={handleGridReady}
        rowData={[]}
        columnDefs={[]}
      />
    </div>
  );
};

两个配套注意:

  • 容器别设 overflow: hidden,否则挂进来的浮层会被裁掉;
  • 一页多个表格时,每个表格都要有自己的 ref 和 setPopupParent,不能共用。

5. 局部覆盖样式(可选)

需要统一压 CSS 变量、加自定义样式,用 createGlobalStyle 写在作用域里:

// src/style/aggrid-scoped.ts
import { createGlobalStyle } from 'antd-style';

export const AgGridScoped = createGlobalStyle`
  .sub-a-aggrid-scope {
    &.ag-theme-alpine {
      --ag-row-height: 28px;
      --ag-header-height: 28px;
      --ag-font-size: 14px;
    }
    .ag-row-odd {
      background-color: #fafafa;
    }
  }
`;

根组件里渲染一次即可。

生产踩坑记录

坑 1:scope 和主题类不在同一个元素

loader 生成的是 .sub-a-aggrid-scope.ag-theme-alpine,写成两层嵌套 div,样式完全匹配不到,表格看上去像「没套主题」。

坑 2:给每个 .ag- 都加前缀,宽高全失效

/* 错误:要求 DOM 里存在层层嵌套的 scope 元素,实际不存在 */
.sub-a-aggrid-scope.ag-theme-alpine .sub-a-aggrid-scope .ag-layout-auto-height .sub-a-aggrid-scope .ag-center-cols-viewport

布局类规则全部匹配不到,表格高度直接塌。

坑 3::not() 里插作用域,整条规则被丢弃

/* 非法 CSS,浏览器丢掉整条规则 */
.ag-select:not(.sub-a-aggrid-scope .ag-label-align-top);

/* 正确:scope 放在 :not 外面 */
.sub-a-aggrid-scope .ag-select:not(.ag-label-align-top);

坑 4:只盯「第一个复合选择器」,[data-theme] .ag-x 被静默漏改

AG-Grid 主题 CSS 里有不少 :root[data-theme=...] .ag-* 形式的规则。如果实现写成「只看开头第一个复合选择器是否含 .ag-」,这类规则压根不会被改写:

/* 第一个复合选择器是 :root[data-theme=light],不含 .ag- → 整条规则原样保留 */
:root[data-theme=light] .ag-side-buttons { width: 40px; }

不报错、不提示,切暗色主题时才炸。所以实现要扫描全部复合选择器,把 scope 插在第一个含 .ag- 的那个前面。

坑 5:第三方主题 CSS 没进 loader

设计系统的 aggrid.css 是全局 .ag-theme-alpine 规则,include 没覆盖到就不会被改写,污染照旧。

坑 6:@media 块内层的规则不会被改写

这是正则方案绕不过去的边界:条件块以 { 起头,不满足 ^ 或 } 的前导条件。项目里如果有媒体查询包着的 .ag-* 规则,需要人工确认,或者直接换 PostCSS 解析:

const postcss = require('postcss');

module.exports = function (source) {
  const root = postcss.parse(source);
  root.walkRules((rule) => {
    rule.selector = scopeSelectorList(rule.selector);
  });
  return root.toString();
};

walkRules 按规则树遍历,@media、注释都不再是问题。代价是多一个依赖,含 Less 语法的文件还要额外传 postcss-less。

坑 7:运行时注入的样式查不到

createGlobalStyle 是 JS 运行时往页面插 <style>,dist 里当然找不到。排查要去 DevTools 的 style 标签看,别只盯构建产物。

坑 8:一页多个表格共用一个外层 scope

弹窗挂载点、overflow 裁剪、样式覆盖范围会互相串。规范是一个表格一个 scope 容器。

构建产物校验

保存为 check-aggrid-scope.js,构建后执行 node check-aggrid-scope.js。

const fs = require('fs');
const path = require('path');

const SCOPE = 'sub-a-aggrid-scope';

function walk(dir) {
  return fs.readdirSync(dir).flatMap((name) => {
    const full = path.join(dir, name);
    return fs.statSync(full).isDirectory() ? walk(full) : [full];
  });
}

let css = '';
for (const file of walk('dist')) {
  if (file.endsWith('.css')) css += fs.readFileSync(file, 'utf8');
}

const count = (re) => (css.match(re) || []).length;
const log = (name, value, mustZero) =>
  console.log(`${name}: ${value} ${mustZero ? '(必须为 0)' : '(必须大于 0)'}`);

log('复合选择器', count(new RegExp(`\\.${SCOPE}\\.ag-theme-`, 'g')), false);
log('后代选择器', count(new RegExp(`\\.${SCOPE} \\.ag-`, 'g')), false);
log(':not 内插 scope', count(new RegExp(`:not\\([^)]*${SCOPE}`, 'g')), true);
log('重复 scope', count(new RegExp(`${SCOPE}[,{]*\\s+\\.${SCOPE}`, 'g')), true);
log('未隔离主题类', count(/(^|[^\w])\.ag-theme-alpine(?![-a-z])/g), true);
log('前缀插错位置', count(new RegExp(`button\\.${SCOPE}`, 'g')), true);

浏览器侧逐项看一遍:

  • 表格边框、行高、表头背景色正常;
  • 排序/筛选箭头图标字体正常;
  • 列宽、行高、容器宽高正常;
  • 右侧列配置侧边栏宽度、按钮内边距正常;
  • 筛选面板、分页、右键菜单样式正常;
  • 多子应用同时运行,别的系统的表格不受影响。

业务开发注意事项

  1. 每个 AG-Grid 表格都要挂 scope + 主题类,多个表格别共用外层一个 scope div;
  2. 只要用到弹窗、下拉菜单,就必须在 onGridReady 里 setPopupParent;
  3. 升级 AG-Grid 或主题包,重跑校验脚本,重点看有没有新的属性选择器、嵌套伪类被误改;
  4. loader 只管构建期静态 CSS,JS 动态 inject 的样式只能业务侧兜底。