前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载本文以 ant-design-vue 官方迁移文档site/src/vueDocs/migration-v3.en-US.md为核心系统梳理从 2.x 升级到 3.x 的全部不兼容变更包括设计规范调整、被移除/废弃的 API、以 TS Composition API 重构的组件体系以及 Form 组件由劫持子元素改为依赖注入的重大机制变化。读完本文你将掌握一套可逐步推进的升级路径先清理 2.x 警告、再按组件模块逐一迁移Tree/Table/DatePicker/Form等高频组件并能在遇到自定义表单控件、表格自定义选择项等场景时直接落地正确写法。升级前准备两步走避免一次性大爆炸迁移文档明确建议不要直接从 2.x 旧版本跳到 3.x而是分两步推进先升级到 2.x 的最新版本并根据控制台输出的警告信息逐一移除/修改相关 API 用法。2.x 是专为兼容 Vue 3 开发的过渡版本大多数 API 变更都是为了更好地兼容 Vue 3 而做的铺垫因此在 2.x 时代控制台就会给出大量废弃提示。建议同时翻阅 2.x 的历史 ChangeLog仓库根目录下有 CHANGELOG.en-US.md 与 CHANGELOG.zh-CN.md了解每个废弃点出现的版本便于按版本逐个处理。将项目升级到 Vue 3.2 及以上。3.x 的依赖注入、v-slot等机制依赖 Vue 3.2 的运行时能力低于该版本无法获得完整支持。文档对 2.x 的评价是没有带来太多新特性大部分 API 变更只是为了更好地兼容 Vue 3而 3.x 在性能、易用性和功能上都有大幅提升且 3.x 稳定后 2.x 将被归档。虽然变更点很多但基本保持兼容可以按控制台警告逐步升级不必一次性重写全部代码。3.0 设计规范调整颜色体系与交互细节3.x 在设计层面与 antd 4.x 规范对齐涉及以下四处可见变化字体颜色由rgba(0, 0, 0, 0.65)调整为rgba(0, 0, 0, 0.85)正文可读性更强、对比度更高。部分组件的选中色统一改为blue-1: #E6F7FF对应的hover色改为gray-2: #FAFAFA。错误色值调整由red-5: #F5222D改为red-5: #FF4D4F。DatePicker 交互重构面板与输入框分离范围选择RangePicker现在可以分别选择开始时间和结束时间交互对齐 antd 4.x。这些色值变更通常不需要业务代码改动但如果你在业务中硬编码了旧的色值如写死了#F5222D需要注意视觉差异。被移除的 API 清单Transfer移除lazy属性。文档明确说明该属性没有真实的优化效果属于冗余 API升级时直接删除即可。Select移除combobox模式请改用AutoComplete组件实现输入框下拉补全场景。ButtonButton.Group被废弃请改用Space组件组合按钮。例如!-- 旧写法2.x -- a-button-group a-buttonCancel/a-button a-button typeprimaryOK/a-button /a-button-group !-- 新写法3.x -- a-space a-buttonCancel/a-button a-button typeprimaryOK/a-button /a-spaceDatePicker / TimePicker / Calendar移除 momentjs默认改用 dayjs。如果你的项目体量很大、大量使用了 momentjs 的方法可以按仓库文档 site/src/vueDocs/replace-date.en-US.md 中的方式换回 moment 或 date-fns// moment 或 date-fns import DatePicker from ant-design-vue/es/date-picker/moment; import TimePicker from ant-design-vue/es/time-picker/moment; import Calendar from ant-design-vue/es/calendar/moment; // import DatePicker from ant-design-vue/es/date-picker/date-fns; // import TimePicker from ant-design-vue/es/time-picker/date-fns; // import Calendar from ant-design-vue/es/calendar/date-fns; import { createApp } from vue; import App from ./App.vue; import antd from ant-design-vue; const app createApp(App); app.use(DatePicker).use(TimePicker).use(Calendar).use(antd).mount(#app);注意若需全局注册组件库use(DatePicker)、use(TimePicker)、use(Calendar)必须在use(antd)之前执行否则无法覆盖默认的 dayjs 版本。从仓库源码看components/date-picker 目录同时提供moment.tsx、dayjs.tsx、date-fns.tsx三个入口而测试代码如 components/date-picker/tests/DatePicker.test.js已全面切换到dayjs印证了 dayjs 为默认实现。Tree / TreeSelect废弃使用a-tree-node与a-tree-select-node构建节点请改用treeData属性。3.x 引入了虚拟滚动数据驱动的方式能显著提升大数据量下的性能。废弃scopedSlots/slots自定义渲染节点改用v-slot:title既提升易用性、避免插槽配置膨胀也规避了插槽命名冲突。废弃replaceFields改用fieldNames。仓库源码 components/tree/Tree.tsx 中对此有明确守护当检测到使用replaceFields时会输出replaceFields is deprecated, please use fieldNames instead的警告并在内部将其透传给fieldNames见 components/tree/Tree.tsx保证旧代码在升级过渡期仍能运行。官方示例 components/tree/demo/replaceFields.vue 展示了新写法a-tree v-model:expandedKeysexpandedKeys v-model:selectedKeysselectedKeys v-model:checkedKeyscheckedKeys checkable :tree-datatreeData :field-namesfieldNames template #title{ name, key } span v-ifkey 0-0-1 stylecolor: #1890ff{{ name }}/span template v-else{{ name }}/template /template /a-treeconst fieldNames { children: child, title: name, };Table移除rowSelection.hideDefaultSelections改用rowSelection.selections配合SELECTION_ALL与SELECTION_INVERT常量自定义选择项。移除 Column 插槽改为v-slot:headerCell、v-slot:bodyCell、v-slot:customFilterDropdown、v-slot:customFilterIcon四个具名插槽。组件重构TS Composition API 全面改造为了获得更好的性能与可维护性3.x 使用TypeScript Vue 3 Composition API重构了几乎所有组件。文档强调极少数尚未重构的组件会在未来逐步重构且其余组件不会有破坏性更新因此无需担心未来的升级成本。3.0 重构后的大版本更新集中在Tree、TreeSelect、DatePicker、TimePicker、Calendar、Form、Table这几个组件其余组件也有对应的功能更新可查阅 ChangeLog 了解细节。Tree / TreeSelect虚拟滚动与数据驱动新增虚拟滚动废弃用a-tree-node/a-tree-select-node手工拼接节点的方式改用treeData属性提升组件性能。从源码看components/tree/Tree.tsx 在useConfigInject中透传了virtual配置渲染层通过虚拟列表只渲染可视区域节点。废弃scopedSlots/slots统一用v-slot:title自定义节点标题避免插槽配置膨胀与命名冲突示例见上文replaceFields.vue。AutoComplete不再支持optionLabelProp请直接设置 Option 的value。options 定义与 Select 对齐请使用options取代原来的dataSource数据驱动的下拉选项定义方式与 Select 完全一致。Table选择、插槽与粘性表头3.x 的 Table 是一次重点重构新增能力集中在以下几个方面rowSelection.selections自定义选择项替代hideDefaultSelections。仓库常量定义在 components/table/hooks/useSelection.tsxexport const SELECTION_ALL SELECT_ALL as const; export const SELECTION_INVERT SELECT_INVERT as const; export const SELECTION_NONE SELECT_NONE as const;官方示例 components/table/demo/row-selection-custom.vue 给出了完整用法selections设为true时显示默认选择项设为数组时可混用内置常量与自定义项key/text/onSelect结构const rowSelection { selectedRowKeys: unref(selectedRowKeys), onChange: onSelectChange, selections: [ Table.SELECTION_ALL, Table.SELECTION_INVERT, Table.SELECTION_NONE, { key: odd, text: Select Odd Row, onSelect: changableRowKeys { let newSelectedRowKeys []; newSelectedRowKeys changableRowKeys.filter((_key, index) { if (index % 2 ! 0) return false; return true; }); selectedRowKeys.value newSelectedRowKeys; }, }, ], };新增expandFixed控制展开图标是否固定。新增showSorterTooltip控制表头是否显示下一次排序的 tooltip。新增sticky设置粘性表头与滚动条。新增rowExpandable设置行是否允许展开。新插槽体系替代旧的 Column 插槽规避插槽配置膨胀与冲突v-slot:headerCell个性化表头单元格v-slot:bodyCell个性化单元格v-slot:customFilterDropdown自定义筛选菜单需与column.customFilterDropdown配合使用该布尔字段定义于 components/vc-table/interface.ts用于标记该列启用自定义筛选下拉v-slot:customFilterIcon自定义筛选图标v-slot:emptyText自定义空数据显示内容v-slot:summary自定义汇总行。DatePicker / TimePicker / Calendardayjs 与交互对齐默认以更轻量的dayjs 替换 momentjs项目若依赖大量 momentjs 方法可按上文replace-date文档换回 momentjs。UI 交互与 antd 4.x 交互规范对齐面板与输入框分离、范围选择分步选择起止时间。Form 机制重构从劫持子元素到依赖注入Form 是本次升级中机制变化最深的组件核心目标是提升性能。文档特别指出如果你没有自定义表单控件几乎可以忽略这一部分只有自定义控件接入 Form.Item 校验时才需要理解新机制。机制变化说明自 3.0 起Form.Item不再劫持子元素而是通过provider/inject依赖注入自动校验。这一变化的收益是组件性能提升子元素数量不受限制子元素可以是进一步封装后的高阶组件。对应地自定义控件接入校验的方式参见官方示例 components/form/demo/customized-form-controls.vue 与 components/form/demo/price-input.vue。但新机制有两个明确代价1. 自定义组件需主动注入 FormItem 上下文。若希望自定义控件被 Form.Item 校验并展示错误状态需要在组件内调用useInjectFormItemContext()并调用相应方法script // custom component import { Form } from ant-design-vue; export default { name: custom-name, setup() { const formItemContext Form.useInjectFormItemContext(); }, }; /script仓库源码 components/form/FormItemContext.ts 定义了useInjectFormItemContext它返回的上下文包含idComputedRefstring、onFieldBlur、onFieldChange、clearValidate四个成员见 components/form/FormItemContext.ts。自定义控件在值变化/失焦时调用onFieldChange()/onFieldBlur()即可通知 Form.Item 触发校验与状态刷新。2. 一个 Form.Item 只能收集一个表单项的数据。若一个 Form.Item 内出现多个表单项会导致收集混乱例如a-form-item a-input namea/a-input a-input nameb/a-input /a-form-item如上写法Form.Item 无法判断应收集namea还是nameb。仓库源码对此有运行期守护useProvideFormItemContext会监听注册字段集合当检测到同一 Form.Item 下注册了多个字段时会在开发环境输出FormItem can only collect one field item...警告见 components/form/FormItemContext.ts。解决该问题有三种方式方式一拆分为多个a-form-item文档推荐的第一种写法a-form-item a-input namea/a-input a-form-itema-input nameb/a-input/a-form-item /a-form-item方式二用自定义组件包裹在自定义组件中调用useInjectFormItemContext等价于把多个表单项合并为一个适合需要整体作为一个值的场景如价格 数字 币种a-form-item custom-com a-input namea/a-input a-input nameb/a-input /custom-com /a-form-item方式三使用a-form-item-rest组件阻止数据收集。把不需要收集与校验的表单项放进该组件与方式一效果类似但不会产生额外的 DOM 节点a-form-item a-input namea/a-input a-form-item-resta-input nameb/a-input/a-form-item-rest /a-form-item从源码看a-form-item-rest对应 components/form/FormItemContext.ts 中导出的AFormItemRest组件其实现就是向子级 provide 一个空上下文defaultInternalContext/defaultContext使子组件不再向父级 Form.Item 注册同时渲染时直接透传默认插槽、不产生多余 DOM。升级过程中遇到问题怎么办V3 做了大量细节改进与重构官方已尽可能收集了所有已知的不兼容变更及影响但仍可能存在未覆盖的场景。如果在升级过程中遇到问题可前往官方 issue 反馈渠道提交问题维护团队会尽快响应并持续完善本文档即 site/src/vueDocs/migration-v3.en-US.md及相关说明。升级检查清单项目 Vue 版本 ≥ 3.2先升级到 2.x 最新版清空控制台全部废弃警告replaceFields、scopedSlots、dataSource、Button.Group等删除 Transfer 的lazySelect 的combobox模式迁移到 AutoComplete日期类组件代码中的moment迁移为dayjs或按replace-date文档整体换回 moment/date-fnsTree / TreeSelect 改用treeDatav-slot:titlefieldNamesTable 的hideDefaultSelections改为selectionsSELECTION_ALL/SELECTION_INVERT列插槽改为headerCell/bodyCell/customFilterDropdown/customFilterIcon等具名插槽自定义表单控件注入useInjectFormItemContext多表单项场景用多个a-form-item或a-form-item-rest收敛对照 CHANGELOG.en-US.md 检查各组件新增功能sticky、expandFixed、rowExpandable、showSorterTooltip等是否可顺手启用。需要说明的是本仓库当前版本已演进到 4.2.6见 package.json在完成 2.x → 3.x 迁移后还可继续参考仓库内同目录的 site/src/vueDocs/migration-v4.en-US.md 了解后续版本的变化但 3.x 本身已具备完善的 TS 类型、Composition API 重构与 dayjs 生态足以作为稳定的生产基线长期使用。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Vux 2.x 升级完全指南从 Vue 1.x 迁移到 Vue 2.x 的 API 变更、构建配置与组件改造实战Vux 2.x 升级完全指南从 Vue 1.x 迁移到 Vue 2.x 的 API 变更、构建配置与组件改造实战 本篇技术指南以 Vux 官方《升级到 vuxUI组件前端winston 2.x 升级到 3.x 完整迁移指南API 变更、format 体系与模块化改造winston 2.x 升级到 3.x 完整迁移指南API 变更、format 体系与模块化改造 本指南以官方 UPGRADE 3.0.md https://开发工具Monolog 2.x/3.x/4.x 升级迁移完全指南API 变更、代码迁移与实战改造Monolog 2.x/3.x/4.x 升级迁移完全指南API 变更、代码迁移与实战改造 导读 本文基于 Monolog 仓库中的 UPGRADE.md ht后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考