业务背景
公司内部有需要大量列表数据展示场景,购买了aggrid的商业版,但是没有对各个系统有对应的统一规范的要求,各个系统按照自己的系统风格,设计去对aggrid进行了改造。
AG-Grid 所有样式固定用 .ag-* 类名,而且没有提供自定义类名前缀的配置。几个子应用同时引 AG-Grid,全局 .ag-* 直接互相覆盖:行高被压扁、边框消失、右键菜单和筛选面板样式错乱。
一条路是改组件库源码,另一条是让别的子应用一起改,两条都不现实。最后选了第三条:构建期改写 CSS 选择器,给样式加命名空间。
核心逻辑很简单:DOM 保留 .ag-* 原样,所有 CSS 规则外面补一个祖先选择器,样式只在带指定 class 的容器内生效。
系列文章
- 总览篇:qiankun 微前端:放弃官方样式隔离,我们落地了 3 套构建期解决方案
- 第二篇:实战:Ant Design 5 在 qiankun 下的类名前缀重命名隔离
- 第四篇:qiankun 主题隔离,把 data-theme 从 html 挪进自己的容器
实现思路
- 构建期自定义 pre loader,处理 AG-Grid 官方样式和设计系统提供的 aggrid 主题 CSS;
- 改写选择器,给样式加祖先作用域类
sub-a-aggrid-scope; ag-theme-*主题类特殊处理:它必须和 scope 挂在同一个 DOM 上,所以用复合选择器而不是后代;- 业务侧每个表格容器都挂
sub-a-aggrid-scope+ 对应主题类; - 弹窗单独处理: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)
规则只有三条,记牢就不容易改错:
- 一条选择器只加一次 scope,加在第一个含
.ag-的复合选择器之前; - 同元素用复合、内部元素用后代;
- 伪类内部不动,逗号也要先保护再分割。
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);
浏览器侧逐项看一遍:
- 表格边框、行高、表头背景色正常;
- 排序/筛选箭头图标字体正常;
- 列宽、行高、容器宽高正常;
- 右侧列配置侧边栏宽度、按钮内边距正常;
- 筛选面板、分页、右键菜单样式正常;
- 多子应用同时运行,别的系统的表格不受影响。
业务开发注意事项
- 每个 AG-Grid 表格都要挂 scope + 主题类,多个表格别共用外层一个 scope div;
- 只要用到弹窗、下拉菜单,就必须在
onGridReady里setPopupParent; - 升级 AG-Grid 或主题包,重跑校验脚本,重点看有没有新的属性选择器、嵌套伪类被误改;
- loader 只管构建期静态 CSS,JS 动态 inject 的样式只能业务侧兜底。