为什么使用 antdv-next ？

# 引言

ant-design-vue 陪伴了 JeeSite 很久了，一直很稳定。但有段时间未更新了，技术这东西不进则退。而 antdv-next 是基于 Ant Design v6 新一代的设计体系 Vue 组件库实现，在 TypeScript 支持、CSS 样式、组件能力和性能表现等方面都有显著提升。加上 Ant Design 6 设计语言已经落地，我们觉得是时候跟上了。

当然，换底层组件库是个大事，我们心里也清楚。所以这件事前前后后打磨了不短的时间。

# 简单介绍一下

antdv-next 是 Vue 生态下基于 Ant Design v6 设计体系的一次完整重新实现，不是在 ant-design-vue 上做二次开发，而是从头搭建的。我们关注它有一段时间了，选它主要是因为这几个方面：

antdv-next 的源码组织结构清晰，读起来舒服。这一点我们比较看重。我们团队在做底层封装的过程中，需要经常翻源码去理解组件的内部逻辑和实现细节，整体感受是代码读得懂、改得动。遇到需要魔改或者二次封装的场景，没有那种"不敢碰"的心理负担。对于像 JeeSite 这样需要深度定制底层组件的项目来说，这一点其实很关键。

设计体系升级到 Ant Design v6。antdv-next 是 Vue 生态里完整落地 Ant Design v6 Token 系统的实现。v6 的 Token 体系比之前的版本更系统、更灵活，主题定制能力也更强。JeeSite 的整体视觉风格跟着对齐到了 Ant Design 6.3。

API 更贴合 Vue 的使用习惯。antdv-next 没有简单地把 React 的 API 照搬过来，而是做了一轮 Vue 化的调整。举个例子，React 里的 classNames、rootClassName 这些属性，在 antdv-next 里统一改成了 classes、rootClass，更符合 Vue 开发者的直觉。

Slot 优先的设计思路。Vue 的 slot 是组件组合的核心机制，antdv-next 把它作为默认的内容扩展方式。同时对常见的渲染类 slot 做了统一命名规范——labelRender、contentRender、extraRender、iconRender，用起来很清晰。对习惯 JSX 写法的同学，通过 props 传节点也完全支持。

整体来说，antdv-next 不是老版本的小修小补，而是一次从设计体系到工程实现的全面升级。

# 迁移成本高吗？

先说结论：比我们预期的要低很多。

这得益于 JeeSite 之前封装的 BasicTable 和 BasicForm 这两个核心组件。业务代码里大量的表格和表单都是基于它们来写的，没有直接裸用底层组件。所以这次换库，主要的改动都在底层封装层，到了业务层面，需要改的东西其实非常少。

打个比方：相当于给车换了一台新发动机，但方向盘、仪表盘、座椅都没变，开车的人基本感觉不到操作上有啥区别。开发者的使用习惯不用做太大调整。

# 具体改了些什么？

简单列一下：

底层组件库：全面切到 antdv-next，API 和能力更新到最新
设计语言：对齐 Ant Design 6.x，视觉上更现代，Token 体系更完善
TypeScript：类型推导更准了，写代码时提示更到位
运行性能：整体性能有较大提升，底层实现重构

这些变化主要集中在底层。如果你是 JeeSite 的使用者，业务代码层面的改动不大。

# 迁移步骤

如果你是已有项目，想升级上来，大致步骤如下：

第一步：同步 JeeSite 仓库代码

建立两个 git 分支，然后将新分支合并到您的分支，然后进行 diff 对比并解决冲突文件。或者，直接将 JeeSite 仓库代码替换到您项目中的代码，然后对每一个代码变更进行 diff，再进行代码合并。

第二步：替换全局注册

全局替换项目文件内容，查找 ant-design-vue 替换为 antdv-next；样式替换 overlayClassName="" 替换为 :classes="{ root: '', container: '' }"

第三步：检查业务代码

大部分业务代码不需要改动。重点关注以下几类情况：

如果你直接使用了底层组件（没有走 BasicTable / BasicForm 封装），需要对照 antdv-next 的文档检查一下 API 变更，部分属性名和用法有调整
如果你自定义了表格列配置或表单项配置，BasicTable 和 BasicForm 的封装接口基本没变，大概率可以直接用
如果你写了自定义样式覆盖，v6 的 Token 体系有变化，建议检查一下样式是否还生效，antdv-next 的 class 命名有少量变化

第四步：回归测试

这一步别偷懒。虽然业务层改动小，但底层换了，该走的流程还是要走一遍。特别是表格、表单、校验、联动这些高频交互，建议重点过一遍。

第五步：遇到问题提 Issue

迁移过程中碰到任何问题，欢迎直接在 jeesite-vue 源码仓库上提 Issues，附上截图和复现步骤，我们尽快跟进。

提问入口：https://gitee.com/thinkgem/jeesite-vue/issues (opens new window)

当然，以上只是大概的几个步骤，同时：

我们也提供了详细的迁移文档：https://jeesite.com/docs/antdv-next-migration/ (opens new window)（欢迎查阅）