JeecgBoot低代码平台 Ant Design Vue 4.x 升级避坑指南

针对JeecgBoot AI专题所做的专门研究，其中涉及到JeecgBoot低代码的antd组件库进行升级时，有着一份完整的迁移手册，手册涵盖升级背景以及影响范围。

Ant Design Vue 4.x属于一次底层架构层面的大版本升级，其最为显著的变化在于彻底摒弃了Less预处理器，转而采用CSS-in-JS方案了。进而对于基于JeecgBoot低代码平台（3.6.2+版本）的项目而言，此次升级涵盖了API命名规范、主题系统、样式权重等多个维度的适配工作。

这里会逐个去梳理，在升级进程当中的那些关键的变更之处，以此来助力你于最短的时间范围之内达成平稳的迁移。

API 命名规范变更

对 4.x 版本而言，其针对多个组件的属性名开展了统一规范化处理，此处理主要涵盖三类命名变更，分别是：

旧属性名新属性名影响组件

dropdownClassName

popupClassName

Select、Cascader、TreeSelect 等

visible

open

像Modal，还有Drawer，以及Dropdown，最后是Tooltip等等。

visibleChange

openChange

同上述组件的事件回调

善用编辑器全局搜索替换功能的批量替换技巧，是要按照以下顺序去执行的。

首先是，具有可见性的等于，接着是，开启状态关联到可见性变化，随后是，与此开启变化相关的下拉类名，最后是，弹出窗口类名。

建议每次替换后进行一轮快速测试，避免遗漏边界情况。

主题系统迁移

鉴于antd 4.x舍弃了Less，JeecgBoot低代码项目得在样式方面进行适配，核心改动聚焦于两个文件。

main.ts 中新增样式导入：

import 'ant-design-vue/dist/reset.css';

这行导入，引入了antd 4.x的全局样式重置，它替代了，原先通过Less变量实现的，基础样式。

generateModifyVars.ts 兼容处理：

那份文件得同时去兼容Less以及CSS-in-JS这两种技术栈，要保证在过渡阶段的时候项目样式不会出现断裂的情况。

App.vue 主题配置

升级过后的主题配置，从Less变量转移到了组件化的方案，要在App.vue里面引入ConfigProvider组件，以及主题算法。

经由token对象能够精细把控整个JeecgBoot低代码平台的视觉体系，涵盖主色调、圆角尺寸、组件大小等。要是需要暗黑主题，引入darkAlgorithm便能够一键实现切换。

CSS 选择器权重调整

4.x版本里，Modal、Drawer、Tooltip等，这些浮层类组件的，CSS选择器权重产生了变化。要是你的JeecgBoot低代码项目当中，存在数目众多的自定义样式覆盖情况，那么升级之后，有可能会发觉一部分样式实效失效了。

解决思路：

getPopupContainer 兼容处理

存在这样一个细节，它是那种容易被人给忽略掉的：处于4.x这个情况里，getPopupContainer回调函数所接收的节点参数，是有可能成为undefined这种状态的。要是在你的代码当中，直接去访问了该参数的属性，那么在升级之后，这就会触发运行时错误。

修复方式非常简单——使用可选链操作符：

getPopupContainer: (node) => node?.parentElement ?? document.body

受影响的核心组件清单

以下组件在升级过程中需要重点关注：

升级检查清单

完成代码修改后，建议按以下清单逐项验证：

总结

Ant Design Vue 4.x的升级，是JeecgBoot低代码平台前端走向现代化的关键部分，尽管其中涉及的改动之处数量不少，然而多数都是那种机械类型的命名替换，实际上真正需要深入去领会的，是有关主题系统的迁移，建议在施行升级操作之前，达成完备的样式快照对比，以此保证在视觉层面维持一致没错。

相关标签： # JeecgBoot # AntDesignVue # 升级指南 # 主题系统 # 组件库