如何把 Ant Design v5 项目升级到 v6 并处理不兼容变化【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design如果你的项目目前运行在 Ant Designantd5.x 上需要升级到 6.x 版本这篇文章给出一条可以按顺序执行的路径先确认环境满足新要求再完成依赖升级逐项处理废弃 API 与行为变化最后按官方清单验证结果。官方迁移文档把这次升级定位为技术升级组件 API 保持兼容但 v6 提高了 React 版本和浏览器的下限这些前提必须在动手安装之前确认。完整依据见 迁移文档。升级准备确认三个前提官方迁移文档要求升级前先确认以下三项先升级到 v5 最新版本并按控制台 warning 信息处理已废弃的 API。v5 阶段的警告正是哪些 API 会变化的信号提前处理能减少升级后的返工。确认项目可以运行在 React 18 及以上版本。v6 不再支持 React 17 及以下。确认目标浏览器均为现代浏览器。v6 默认使用 CSS variables仅支持现代浏览器IE 不再支持部分旧版国产浏览器可能存在兼容性问题。文档建议在应用发布前确认目标浏览器的支持情况。三项中有任何一项不满足都不要直接执行下面的安装命令前两项会直接导致升级后无法运行第三项会导致发布后样式错乱。可选用 CLI 辅助扫描废弃 API手动核对清单前官方推荐先使用 Ant Design CLI 辅助升级CLI 可以基于项目代码检查废弃 API、组件用法与版本差异避免只依赖文档逐项对照而遗漏。CLI 需要 Node.js 20.0.0全局安装npm install -g ant-design/cli # 或 pnpm add -g ant-design/cli安装后在升级目标项目的代码目录下执行以下命令摸清现状./src为文档示例中的代码目录替换为你项目实际的 antd 代码目录antd doctor # 诊断检查React 兼容性、重复安装、peer 依赖、SSR、babel 插件等 antd usage ./src # 分析项目中的 antd 导入 antd lint ./src # 检查废弃 API 和最佳实践antd doctor包含 React 兼容性检查可以直接帮你确认上一节的第一条前提antd lint的输出则可以作为后续逐项修改的依据。批量处理方面CLI 提供antd migrate from to生成迁移清单区分自动修复项和手动处理项配合--apply参数可生成 Agent 迁移提示。官方文档中的示例为antd migrate 4 5 --apply ./src按同样的签名v5 到 v6 可以写成antd migrate 5 6目标目录替换为你的代码目录。执行升级同时安装 antd6 与 icons6环境确认完成后升级依赖。这里有一个硬性约束ant-design/icons6与antd5不兼容必须同时升级两个包否则会出现构建错误。npm install --save antd6 npm install --save ant-design/icons6 # 或 yarn add antd6 yarn add ant-design/icons6 # 或 pnpm add antd6 pnpm add ant-design/icons6文档给出的升级要求是antd6要求 React 版本 18antd6要求ant-design/icons版本 6.0.0。如果升级过程中遇到构建错误文档提示先检查ant-design/icons版本是否与antd版本匹配。如果需要控制升级的影响范围迁移文档提到可以通过别名安装 v6的原子级迁移方案但文档明确注明这并非官方推荐的升级路径本文主路径仍是整体升级。逐项处理不兼容变化移除 React 19 兼容补丁如果用了v5 时代接入 React 19 需要引入ant-design/v5-patch-for-react-19v6 不再需要该包如果使用可以移除该依赖- import ant-design/v5-patch-for-react-19;处理废弃 API当前仍有警告7.0 移除v6 将大量组件属性标记为废弃Deprecated除特别标注外自 v6.0.0 起生效。这些属性当前仍可使用但控制台会提示弃用警告并将在 7.0 中被移除文档建议尽快迁移到对应替代属性。下面是 迁移文档 中的一部分条目可直接对照antd lint的输出逐项修复组件废弃用法替代写法AlertmessagetitleButton.GroupButton.GroupSpace.CompactInput.GroupInput.GroupSpace.CompactModalbodyStylestyles.bodyModaldestroyOnClosedestroyOnHiddenModalmaskClosablemask.closable6.3.0InputborderedvariantSelectdropdownRenderpopupRenderSpacedirectionorientationSpacesplitseparatorTagbordered{false}variantfilledStepsdirectionorientation清单里有几条反复出现的规律可以按类处理弹层类的dropdown*属性统一改为popup*、classNames.popup.root、styles.popup.root涉及Select、Cascader、TreeSelect、AutoComplete等destroyOnClose、destroyInactivePanel等统一改为destroyOnHidden各类*Style属性迁移到语义化的styles对象如Card的headStyle变为styles.header、bodyStyle变为styles.body。另有标注版本号的条目例如Splitter的collapsibleIcon自 6.4.0 起废弃变为collapsible.icon。统一 size 枚举值6.3.0 ~ 6.3.2v6 把组件size枚举值统一为large | medium | small。使用旧值时控制台会出现废弃警告旧值将在 v7 中移除Avatar、Badge、Card、Progress、Steps、Switch、Spin的size用medium替代defaultDescriptions的size用medium替代middle用large替代defaultTable、Divider的size用medium替代middle。文档示例- Switch sizedefault / Switch sizemedium / - Descriptions sizedefault / Descriptions sizelarge / - Table sizemiddle / Table sizemedium /注意三处行为变化弹层蒙层模糊。v6 为 Modal、Drawer 等弹层组件新增mask蒙层功能并支持模糊效果v6.0.0 ~ v6.2.x 默认开启模糊v6.3.0 起改为默认关闭。如需保留模糊效果通过ConfigProvider显式开启import { ConfigProvider, Drawer, Modal } from antd; export default () ( ConfigProvider modal{{ mask: { blur: true, }, }} drawer{{ mask: { blur: true, }, }} Modal / Drawer / /ConfigProvider );Tag 末尾外边距移除。v6 移除了Tag组件末尾的默认外边距v5 中 Tag 末尾会额外留出一段margin-inline-end。如果布局或自定义样式依赖这一行为用ConfigProvider的tag.styles补充import { ConfigProvider, Tag } from antd; export default () ( ConfigProvider tag{{ styles: { root: { marginInlineEnd: 8, }, }, }} TagTag A/Tag TagTag B/Tag /ConfigProvider );Form.List 提交值变化。v5 中 Form.List 会被视为一个 Field提交时会包含其下所有数据结构即便子元素的 Form.Item 没有注册过。v6 中 Form.List 不再包含未注册的子项数据因此不再需要通过getFieldsValue({ strict: true })过滤未注册字段const onFinish (values) { - const realValues getFieldsValue({ strict: true }); const realValues values; // ... } Form onFinish{onFinish} /复查针对内部 DOM 的自定义样式v6 对大量组件的 DOM 结构进行了升级和优化。对大多数正常使用 antd 样式的项目这不会产生影响但如果项目中存在针对组件内部 DOM 节点的自定义样式例如依赖特定选择器或层级结构升级后需要手动检查并调整样式。验证升级结果修改完成后按官方迁移文档的 Checklist 逐项确认React 版本确认项目使用的 React 版本 18并且不再引入ant-design/v5-patch-for-react-19。ant-design/icons 版本确认已升级到 6.0.0与antd6匹配。浏览器兼容性确认目标用户浏览器均为现代浏览器且支持 CSS variables。自定义样式检查如果有针对组件内部 DOM 节点的 CSS 定制验证在 v6 下是否依然生效。弹层蒙层配置Modal、Drawer 等弹层是否需要关闭mask的模糊效果不需要可保持默认。构建工具配置确认升级后构建无报错CSS 变量和 CSS-in-JS 能正常工作。控制台 warning运行应用并观察控制台处理所有legacy API的提示。也可以再次运行antd doctor对 React 兼容性、重复安装、peer 依赖等项目配置做最后核对。构建无报错、控制台的废弃警告全部处理完毕说明这次升级完成了主要部分升级中遇到的具体问题可以到 GitHub issues 反馈官方会响应并在文档中完善相关说明。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
如何把 Ant Design v5 项目升级到 v6 并处理不兼容变化
如何把 Ant Design v5 项目升级到 v6 并处理不兼容变化【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design如果你的项目目前运行在 Ant Designantd5.x 上需要升级到 6.x 版本这篇文章给出一条可以按顺序执行的路径先确认环境满足新要求再完成依赖升级逐项处理废弃 API 与行为变化最后按官方清单验证结果。官方迁移文档把这次升级定位为技术升级组件 API 保持兼容但 v6 提高了 React 版本和浏览器的下限这些前提必须在动手安装之前确认。完整依据见 迁移文档。升级准备确认三个前提官方迁移文档要求升级前先确认以下三项先升级到 v5 最新版本并按控制台 warning 信息处理已废弃的 API。v5 阶段的警告正是哪些 API 会变化的信号提前处理能减少升级后的返工。确认项目可以运行在 React 18 及以上版本。v6 不再支持 React 17 及以下。确认目标浏览器均为现代浏览器。v6 默认使用 CSS variables仅支持现代浏览器IE 不再支持部分旧版国产浏览器可能存在兼容性问题。文档建议在应用发布前确认目标浏览器的支持情况。三项中有任何一项不满足都不要直接执行下面的安装命令前两项会直接导致升级后无法运行第三项会导致发布后样式错乱。可选用 CLI 辅助扫描废弃 API手动核对清单前官方推荐先使用 Ant Design CLI 辅助升级CLI 可以基于项目代码检查废弃 API、组件用法与版本差异避免只依赖文档逐项对照而遗漏。CLI 需要 Node.js 20.0.0全局安装npm install -g ant-design/cli # 或 pnpm add -g ant-design/cli安装后在升级目标项目的代码目录下执行以下命令摸清现状./src为文档示例中的代码目录替换为你项目实际的 antd 代码目录antd doctor # 诊断检查React 兼容性、重复安装、peer 依赖、SSR、babel 插件等 antd usage ./src # 分析项目中的 antd 导入 antd lint ./src # 检查废弃 API 和最佳实践antd doctor包含 React 兼容性检查可以直接帮你确认上一节的第一条前提antd lint的输出则可以作为后续逐项修改的依据。批量处理方面CLI 提供antd migrate from to生成迁移清单区分自动修复项和手动处理项配合--apply参数可生成 Agent 迁移提示。官方文档中的示例为antd migrate 4 5 --apply ./src按同样的签名v5 到 v6 可以写成antd migrate 5 6目标目录替换为你的代码目录。执行升级同时安装 antd6 与 icons6环境确认完成后升级依赖。这里有一个硬性约束ant-design/icons6与antd5不兼容必须同时升级两个包否则会出现构建错误。npm install --save antd6 npm install --save ant-design/icons6 # 或 yarn add antd6 yarn add ant-design/icons6 # 或 pnpm add antd6 pnpm add ant-design/icons6文档给出的升级要求是antd6要求 React 版本 18antd6要求ant-design/icons版本 6.0.0。如果升级过程中遇到构建错误文档提示先检查ant-design/icons版本是否与antd版本匹配。如果需要控制升级的影响范围迁移文档提到可以通过别名安装 v6的原子级迁移方案但文档明确注明这并非官方推荐的升级路径本文主路径仍是整体升级。逐项处理不兼容变化移除 React 19 兼容补丁如果用了v5 时代接入 React 19 需要引入ant-design/v5-patch-for-react-19v6 不再需要该包如果使用可以移除该依赖- import ant-design/v5-patch-for-react-19;处理废弃 API当前仍有警告7.0 移除v6 将大量组件属性标记为废弃Deprecated除特别标注外自 v6.0.0 起生效。这些属性当前仍可使用但控制台会提示弃用警告并将在 7.0 中被移除文档建议尽快迁移到对应替代属性。下面是 迁移文档 中的一部分条目可直接对照antd lint的输出逐项修复组件废弃用法替代写法AlertmessagetitleButton.GroupButton.GroupSpace.CompactInput.GroupInput.GroupSpace.CompactModalbodyStylestyles.bodyModaldestroyOnClosedestroyOnHiddenModalmaskClosablemask.closable6.3.0InputborderedvariantSelectdropdownRenderpopupRenderSpacedirectionorientationSpacesplitseparatorTagbordered{false}variantfilledStepsdirectionorientation清单里有几条反复出现的规律可以按类处理弹层类的dropdown*属性统一改为popup*、classNames.popup.root、styles.popup.root涉及Select、Cascader、TreeSelect、AutoComplete等destroyOnClose、destroyInactivePanel等统一改为destroyOnHidden各类*Style属性迁移到语义化的styles对象如Card的headStyle变为styles.header、bodyStyle变为styles.body。另有标注版本号的条目例如Splitter的collapsibleIcon自 6.4.0 起废弃变为collapsible.icon。统一 size 枚举值6.3.0 ~ 6.3.2v6 把组件size枚举值统一为large | medium | small。使用旧值时控制台会出现废弃警告旧值将在 v7 中移除Avatar、Badge、Card、Progress、Steps、Switch、Spin的size用medium替代defaultDescriptions的size用medium替代middle用large替代defaultTable、Divider的size用medium替代middle。文档示例- Switch sizedefault / Switch sizemedium / - Descriptions sizedefault / Descriptions sizelarge / - Table sizemiddle / Table sizemedium /注意三处行为变化弹层蒙层模糊。v6 为 Modal、Drawer 等弹层组件新增mask蒙层功能并支持模糊效果v6.0.0 ~ v6.2.x 默认开启模糊v6.3.0 起改为默认关闭。如需保留模糊效果通过ConfigProvider显式开启import { ConfigProvider, Drawer, Modal } from antd; export default () ( ConfigProvider modal{{ mask: { blur: true, }, }} drawer{{ mask: { blur: true, }, }} Modal / Drawer / /ConfigProvider );Tag 末尾外边距移除。v6 移除了Tag组件末尾的默认外边距v5 中 Tag 末尾会额外留出一段margin-inline-end。如果布局或自定义样式依赖这一行为用ConfigProvider的tag.styles补充import { ConfigProvider, Tag } from antd; export default () ( ConfigProvider tag{{ styles: { root: { marginInlineEnd: 8, }, }, }} TagTag A/Tag TagTag B/Tag /ConfigProvider );Form.List 提交值变化。v5 中 Form.List 会被视为一个 Field提交时会包含其下所有数据结构即便子元素的 Form.Item 没有注册过。v6 中 Form.List 不再包含未注册的子项数据因此不再需要通过getFieldsValue({ strict: true })过滤未注册字段const onFinish (values) { - const realValues getFieldsValue({ strict: true }); const realValues values; // ... } Form onFinish{onFinish} /复查针对内部 DOM 的自定义样式v6 对大量组件的 DOM 结构进行了升级和优化。对大多数正常使用 antd 样式的项目这不会产生影响但如果项目中存在针对组件内部 DOM 节点的自定义样式例如依赖特定选择器或层级结构升级后需要手动检查并调整样式。验证升级结果修改完成后按官方迁移文档的 Checklist 逐项确认React 版本确认项目使用的 React 版本 18并且不再引入ant-design/v5-patch-for-react-19。ant-design/icons 版本确认已升级到 6.0.0与antd6匹配。浏览器兼容性确认目标用户浏览器均为现代浏览器且支持 CSS variables。自定义样式检查如果有针对组件内部 DOM 节点的 CSS 定制验证在 v6 下是否依然生效。弹层蒙层配置Modal、Drawer 等弹层是否需要关闭mask的模糊效果不需要可保持默认。构建工具配置确认升级后构建无报错CSS 变量和 CSS-in-JS 能正常工作。控制台 warning运行应用并观察控制台处理所有legacy API的提示。也可以再次运行antd doctor对 React 兼容性、重复安装、peer 依赖等项目配置做最后核对。构建无报错、控制台的废弃警告全部处理完毕说明这次升级完成了主要部分升级中遇到的具体问题可以到 GitHub issues 反馈官方会响应并在文档中完善相关说明。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
