From efbdf65f03966757447c2ad31d71c1877498c193 Mon Sep 17 00:00:00 2001 From: shifeng1993 Date: Sat, 15 Apr 2023 20:08:37 +0800 Subject: [PATCH 01/12] fix introduce doc --- site/src/vueDocs/introduce.en-US.md | 56 ++++------------------------ site/src/vueDocs/introduce.zh-CN.md | 58 ++++------------------------- 2 files changed, 14 insertions(+), 100 deletions(-) diff --git a/site/src/vueDocs/introduce.en-US.md b/site/src/vueDocs/introduce.en-US.md index 679b5bc1a6..d4cf1ae2af 100644 --- a/site/src/vueDocs/introduce.en-US.md +++ b/site/src/vueDocs/introduce.en-US.md @@ -49,11 +49,11 @@ You can subscribe to this feed for new version notifications: https://github.com **We recommend using npm or yarn to install**,it not only makes development easier,but also allow you to take advantage of the rich ecosystem of Javascript packages and tooling. ```bash -$ npm install ant-design-vue --save +$ npm install ant-design-vue@next --save ``` ```bash -$ yarn add ant-design-vue +$ yarn add ant-design-vue@next ``` If you are in a bad network environment,you can try other registries and tools like [cnpm](https://github.com/cnpm/cnpm). @@ -62,11 +62,11 @@ If you are in a bad network environment,you can try other registries and tools Add `script` and `link` tags in your browser and use the global variable `antd`. -We provide `antd.js` `antd.css` and `antd.min.js` `antd.min.css` under `ant-design-vue/dist` in antd's npm package. You can also download these files directly from [![jsdelivr](https://data.jsdelivr.com/v1/package/npm/ant-design-vue/badge)](https://www.jsdelivr.com/package/npm/ant-design-vue) or [unpkg](https://unpkg.com/ant-design-vue/dist/). +We provide `antd.js` `antd.min.js` and `reset.css` under `ant-design-vue/dist` in antd's npm package. You can also download these files directly from [![jsdelivr](https://data.jsdelivr.com/v1/package/npm/ant-design-vue/badge)](https://www.jsdelivr.com/package/npm/ant-design-vue) or [unpkg](https://unpkg.com/ant-design-vue/dist/). > **We strongly discourage loading the entire files** this will add bloat to your application and make it more difficult to receive bugfixes and updates. Antd is intended to be used in conjunction with a build tool, such as [webpack](https://webpack.github.io/), which will make it easy to import only the parts of antd that you are using. -> Note: you should import [dayjs](https://day.js.org/) and dayjs plugins before using antd.js. +> Note: you should import `vue`, [dayjs](https://day.js.org/) and dayjs plugins before using `antd.js`. Like: @@ -78,6 +78,7 @@ Like: + ``` ## Usage @@ -90,55 +91,12 @@ app.use(DatePicker); And import stylesheets manually: ```jsx -import 'ant-design-vue/dist/antd.css'; // or 'ant-design-vue/dist/antd.less' +import 'ant-design-vue/dist/reset.css'; ``` ### Use modularized antd -- Use [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) (Recommended) - - ```jsx - // .babelrc or babel-loader option - { - "plugins": [ - ["import", { "libraryName": "ant-design-vue", "libraryDirectory": "es", "style": "css" }] // `style: true` for less - ] - } - ``` - - > Note: Don't set `libraryDirectory` if you are using webpack 1. - - This allows you to import components from antd without having to manually import the corresponding stylesheet. The antd babel plugin will automatically import stylesheets. - - ```jsx - // import js and css modularly, parsed by babel-plugin-import - import { DatePicker } from 'ant-design-vue'; - ``` - -- Manually import - - ```jsx - import DatePicker from 'ant-design-vue/lib/date-picker'; // for js - import 'ant-design-vue/lib/date-picker/style/css'; // for css - // import 'ant-design-vue/lib/date-picker/style'; // that will import less - ``` - -- For Vite - - ```js - // vite.config.js - import Components from 'unplugin-vue-components/vite'; - import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'; - - export default { - plugins: [ - /* ... */ - Components({ - resolvers: [AntDesignVueResolver()], - }), - ], - }; - ``` +`antd` supports ES modules tree shaking by default. ## Links diff --git a/site/src/vueDocs/introduce.zh-CN.md b/site/src/vueDocs/introduce.zh-CN.md index 3da5b9ee47..a561c99e63 100644 --- a/site/src/vueDocs/introduce.zh-CN.md +++ b/site/src/vueDocs/introduce.zh-CN.md @@ -49,11 +49,11 @@ **我们推荐使用 npm 或 yarn 的方式进行开发**,不仅可在开发环境轻松调试,也可放心地在生产环境打包部署使用,享受整个生态圈和工具链带来的诸多好处。 ```bash -$ npm install ant-design-vue --save +$ npm install ant-design-vue@next --save ``` ```bash -$ yarn add ant-design-vue +$ yarn add ant-design-vue@next ``` 如果你的网络环境不佳,推荐使用 [cnpm](https://github.com/cnpm/cnpm)。 @@ -62,11 +62,11 @@ $ yarn add ant-design-vue 在浏览器中使用 `script` 和 `link` 标签直接引入文件,并使用全局变量 `antd`。 -我们在 npm 发布包内的 `ant-design-vue/dist` 目录下提供了 `antd.js` `antd.css` 以及 `antd.min.js` `antd.min.css`。你也可以通过 [![jsdelivr](https://data.jsdelivr.com/v1/package/npm/ant-design-vue/badge)](https://www.jsdelivr.com/package/npm/ant-design-vue) 或 [UNPKG](https://unpkg.com/ant-design-vue/dist/) 进行下载。 +我们在 npm 发布包内的 `ant-design-vue/dist` 目录下提供了 `antd.js`、`antd.min.js` 和 `reset.css`。你也可以通过 [![jsdelivr](https://data.jsdelivr.com/v1/package/npm/ant-design-vue/badge)](https://www.jsdelivr.com/package/npm/ant-design-vue) 或 [UNPKG](https://unpkg.com/ant-design-vue/dist/) 进行下载。 > **强烈不推荐使用已构建文件**,这样无法按需加载,而且难以获得底层依赖模块的 bug 快速修复支持。 -> 注意:引入 antd.js 前你需要自行引入 [dayjs](https://day.js.org/) 及其相关插件。 +> 注意:引入 `antd.js` 前你需要自行引入 `vue`、[`dayjs`](https://day.js.org/) 及其相关插件。 如: @@ -78,6 +78,7 @@ $ yarn add ant-design-vue + ``` ## 示例 @@ -90,57 +91,12 @@ app.use(DatePicker); 引入样式: ```jsx -import 'ant-design-vue/dist/antd.css'; // or 'ant-design-vue/dist/antd.less' +import 'ant-design-vue/dist/reset.css'; ``` ### 按需加载 -下面两种方式都可以只加载用到的组件。 - -- 使用 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import)(推荐)。 - - ```jsx - // .babelrc or babel-loader option - { - "plugins": [ - ["import", { "libraryName": "ant-design-vue", "libraryDirectory": "es", "style": "css" }] // `style: true` 会加载 less 文件 - ] - } - ``` - - > 注意:webpack 1 无需设置 `libraryDirectory`。 - - 然后只需从 ant-design-vue 引入模块即可,无需单独引入样式。等同于下面手动引入的方式。 - - ```jsx - // babel-plugin-import 会帮助你加载 JS 和 CSS - import { DatePicker } from 'ant-design-vue'; - ``` - -- 手动引入 - - ```jsx - import DatePicker from 'ant-design-vue/lib/date-picker'; // 加载 JS - import 'ant-design-vue/lib/date-picker/style/css'; // 加载 CSS - // import 'ant-design-vue/lib/date-picker/style'; // 加载 LESS - ``` - -- Vite 按需 - - ```js - // vite.config.js - import Components from 'unplugin-vue-components/vite'; - import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'; - - export default { - plugins: [ - /* ... */ - Components({ - resolvers: [AntDesignVueResolver()], - }), - ], - }; - ``` +`ant-design-vue` 默认支持基于 ES modules 的 tree shaking。 ## 链接 From 4fb5e9076e6d8c36dfd7c9171e4c6097a32ddf1a Mon Sep 17 00:00:00 2001 From: shifeng1993 Date: Sat, 15 Apr 2023 21:25:33 +0800 Subject: [PATCH 02/12] fix getting-started doc --- site/src/vueDocs/getting-started.en-US.md | 32 ++------------------- site/src/vueDocs/getting-started.zh-CN.md | 34 ++--------------------- 2 files changed, 6 insertions(+), 60 deletions(-) diff --git a/site/src/vueDocs/getting-started.en-US.md b/site/src/vueDocs/getting-started.en-US.md index 4706b7412d..836efd0326 100644 --- a/site/src/vueDocs/getting-started.en-US.md +++ b/site/src/vueDocs/getting-started.en-US.md @@ -37,7 +37,7 @@ And, setup your vue project configuration. #### Install ```bash -$ npm i --save ant-design-vue +$ npm i --save ant-design-vue@next ``` #### Component Registration @@ -50,7 +50,7 @@ If you use Vue's default template syntax, you need to register components before import { createApp } from 'vue'; import Antd from 'ant-design-vue'; import App from './App'; -import 'ant-design-vue/dist/antd.css'; +import 'ant-design-vue/dist/reset.css'; const app = createApp(App); @@ -99,35 +99,9 @@ In this way, component sub-components, such as Button and ButtonGroup, need to b [Component list](https://github.com/vueComponent/ant-design-vue/blob/main/components/components.ts) -## Compatibility - -Ant Design Vue 2.x supports all the modern browsers. If you want to use IE9+, you can use Ant Design Vue 1.x & Vue 2.x. - ## Import on Demand -we can import individual components on demand: - -```jsx -import Button from 'ant-design-vue/lib/button'; -import 'ant-design-vue/lib/button/style'; // or ant-design-vue/lib/button/style/css for css format file -``` - -We strongly recommend using [babel-plugin-import](https://github.com/ant-design/babel-plugin-import), which can convert the following code to the 'ant-design-vue/lib/xxx' way: - -```jsx -import { Button } from 'ant-design-vue'; -``` - -And this plugin can load styles too, read [usage](https://github.com/ant-design/babel-plugin-import#usage) for more details. - -> FYI, babel-plugin-import's `style` option will importing some global reset styles, don't use it if you don't need those styles. You can import styles manually via `import 'ant-design-vue/dist/antd.css'` and override the global reset styles. - -If you use Vite, you can use [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components) to load on demand. However, this plugin can only deal with components. Others such as message should be loaded manually: - -```ts -import { message } from 'ant-design-vue'; -import 'ant-design-vue/es/message/style/css'; //use ant-design-vue/es instead of ant-design-vue/lib -``` +`antd` supports tree shaking of ES modules, so using `import { Button } from 'antd';` would drop js code you didn't use. ## Customization diff --git a/site/src/vueDocs/getting-started.zh-CN.md b/site/src/vueDocs/getting-started.zh-CN.md index d31ebe166d..52b689e0dd 100644 --- a/site/src/vueDocs/getting-started.zh-CN.md +++ b/site/src/vueDocs/getting-started.zh-CN.md @@ -39,7 +39,7 @@ $ vue create antd-demo #### 安装 ```bash -$ npm i --save ant-design-vue +$ npm i --save ant-design-vue@next ``` #### 注册 @@ -52,7 +52,7 @@ $ npm i --save ant-design-vue import { createApp } from 'vue'; import Antd from 'ant-design-vue'; import App from './App'; -import 'ant-design-vue/dist/antd.css'; +import 'ant-design-vue/dist/reset.css'; const app = createApp(App); @@ -97,37 +97,9 @@ app.config.globalProperties.$message = message; ``` -## 兼容性 - -Ant Design Vue 2.x+ 支持所有的现代浏览器。 - -如果需要支持 IE9+,你可以使用 Ant Design Vue 1.x & Vue 2.x。 - ## 按需加载 -如果你仅需要加载使用的组件,可以通过以下的写法来按需加载组件。 - -```jsx -import Button from 'ant-design-vue/lib/button'; -import 'ant-design-vue/lib/button/style'; // 或者 ant-design-vue/lib/button/style/css 加载 css 文件 -``` - -如果你使用了 babel,那么可以使用 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 来进行按需加载,加入这个插件后。你可以仍然这么写: - -```jsx -import { Button } from 'ant-design-vue'; -``` - -插件会帮你转换成 `ant-design-vue/lib/xxx` 的写法。另外此插件配合 [style](https://github.com/ant-design/babel-plugin-import#usage) 属性可以做到模块样式的按需自动加载。 - -> 注意,babel-plugin-import 的 `style` 属性除了引入对应组件的样式,也会引入一些必要的全局样式。如果你不需要它们,建议不要使用此属性。你可以 `import 'ant-design-vue/dist/antd.css` 手动引入,并覆盖全局样式。 - -如果你使用的 Vite,你可以使用 [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components) 来进行按需加载。但是此插件无法处理非组件模块,如 message,这种组件需要手动加载: - -```ts -import { message } from 'ant-design-vue'; -import 'ant-design-vue/es/message/style/css'; //vite只能用 ant-design-vue/es 而非 ant-design-vue/lib -``` +`antd` 默认支持基于 ES modules 的 tree shaking,直接引入 `import { Button } from 'antd';` 就会有按需加载的效果。 ## 配置主题和字体 From 192e3e996605ccd8d6b41aad785b90b3ac0f1a60 Mon Sep 17 00:00:00 2001 From: shifeng1993 Date: Sun, 16 Apr 2023 10:39:27 +0800 Subject: [PATCH 03/12] add migration-v4 doc --- site/src/router/index.js | 22 ++- site/src/vueDocs/migration-v4.en-US.md | 197 ++++++++++++++++++++++++ site/src/vueDocs/migration-v4.zh-CN.md | 199 +++++++++++++++++++++++++ 3 files changed, 412 insertions(+), 6 deletions(-) create mode 100644 site/src/vueDocs/migration-v4.en-US.md create mode 100644 site/src/vueDocs/migration-v4.zh-CN.md diff --git a/site/src/router/index.js b/site/src/router/index.js index 9451c0c409..4661515db9 100644 --- a/site/src/router/index.js +++ b/site/src/router/index.js @@ -116,6 +116,16 @@ const routes = [ meta: { enTitle: 'Dynamic Theme (Experimental)', title: '动态主题', category: 'docs' }, component: () => import('../vueDocs/customize-theme-variable.en-US.md'), }, + { + path: 'vue/replace-date-cn', + meta: { enTitle: 'Custom Date Library', title: '自定义时间库', category: 'docs' }, + component: () => import('../vueDocs/replace-date.zh-CN.md'), + }, + { + path: 'vue/replace-date', + meta: { enTitle: 'Custom Date Library', title: '自定义时间库', category: 'docs' }, + component: () => import('../vueDocs/replace-date.en-US.md'), + }, { path: 'vue/migration-v2-cn', meta: { enTitle: 'V1 to V2', title: '从 v1 到 v2', category: 'docs' }, @@ -137,14 +147,14 @@ const routes = [ component: () => import('../vueDocs/migration-v3.en-US.md'), }, { - path: 'vue/replace-date-cn', - meta: { enTitle: 'Custom Date Library', title: '自定义时间库', category: 'docs' }, - component: () => import('../vueDocs/replace-date.zh-CN.md'), + path: 'vue/migration-v4-cn', + meta: { enTitle: 'V3 to V4', title: '从 V3 到 V4', category: 'docs' }, + component: () => import('../vueDocs/migration-v4.zh-CN.md'), }, { - path: 'vue/replace-date', - meta: { enTitle: 'Custom Date Library', title: '自定义时间库', category: 'docs' }, - component: () => import('../vueDocs/replace-date.en-US.md'), + path: 'vue/migration-v4', + meta: { enTitle: 'V3 to V4', title: '从 V3 到 V4', category: 'docs' }, + component: () => import('../vueDocs/migration-v4.en-US.md'), }, { path: 'vue/i18n-cn', diff --git a/site/src/vueDocs/migration-v4.en-US.md b/site/src/vueDocs/migration-v4.en-US.md new file mode 100644 index 0000000000..8237e02f87 --- /dev/null +++ b/site/src/vueDocs/migration-v4.en-US.md @@ -0,0 +1,197 @@ +This document will help you upgrade from ant-design-vue `3.x` version to ant-design-vue `4.x` version. If you are using `2.x` or older version, please refer to the previous [upgrade document](/docs/vue/migration-v3) to 3.x. + +## Upgrade preparation + +1. Please upgrade to the latest version of 3.x first, and remove / modify related APIs according to the console warning message. + +## Incompatible changes in v4 + +### Design specification + +- Basic rounded corner adjustment, changed from `2px` to four layers of radius, which are `2px` `4px` `6px` and `8px`. For example, radius of default Button is modified from `2px` to `6px`. +- Primary color adjustment, changed from `#1890ff` to `#1677ff`. +- Global shadow optimization, adjusted from three layers of shadows to two layers, which are used in common components (Card .e.g) and popup components (Dropdown .e.g). +- Overall reduction in wireframe usage. + +### Technology adjustment + +- Remove less, adopt CSS-in-JS, for better support of dynamic themes. The bottom layer uses [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) as a solution. + - All less files are removed, and less variables are no longer exported. + - Css files are no longer included in package. Since CSS-in-JS supports importing on demand, the original `ant-design-vue/dist/antd.css` has also been abandoned. If you need to reset some basic styles, please import `ant-design-vue/dist/reset.css`. + - If you need to reset the style of the component, but you don't want to introduce `ant-design-vue/dist/reset.css` to pollute the global style, You can try using the [App](/components/app) in the outermost layer to solve the problem that native elements do not have antd specification style. +- Remove css variables and dynamic theme built on top of them. +- LocaleProvider has been deprecated in 3.x (use `` instead), we removed the related folder `ant-design-vue/es/locale-provider` and `ant-design-vue/lib/locale-provider` in 4.x. +- Replace built-in Moment.js with Dayjs. For more: [Use custom date library](/docs/vue/use-custom-date-library/). +- `babel-plugin-import` is no longer supported. CSS-in-JS itself has the ability to import on demand, and plugin support is no longer required. + +### Compatibility + +- DO NOT support IE browser anymore. + +#### Component API adjustment + +- The classname API of the component popup box is unified to `popupClassName`, and `dropdownClassName` and other similar APIs will be replaced. + + - AutoComplete + - Cascader + - Select + - TreeSelect + - TimePicker + - DatePicker + - Mentions + + ```html + + + + ``` + +- The controlled visible API of the component popup is unified to `open`, and `visible` and other similar APIs will be replaced. + + - Drawer `visible` changed to `open`. + - Modal `visible` changed to `open`. + - Dropdown `visible` changed to `open`. + - Tooltip `visible` changed to `open`. + - Tag `visible` is removed. + - Slider `tooltip` related API converged to `tooltip` property. + - Table `filterDropdownVisible` changed to `filterDropdownOpen`. + + ```html + + + + ``` + +- `getPopupContainer`: All `getPopupContainer` are guaranteed to return a unique div. +- Upload List structure changes. [#34528](https://github.com/ant-design/ant-design/pull/34528) +- Notification + - Static methods are no longer allowed to dynamically set `prefixCls` `maxCount` `top` `bottom` `getContainer` in `open`, Notification static methods will now have only one instance. If you need a different configuration, use `useNotification`. + - `close` was renamed to `destroy` to be consistent with message. +- Drawer `style` & `className` are migrated to Drawer panel node, the original properties are replaced by `rootClassName` and `rootStyle`. +- The deprecated `message.warn` in 3.x is now completely removed, please use `message.warning` instead. + +#### Component refactoring and removal + +- Remove `locale-provider` Directory. `LocaleProvider` was removed in v4, please use `ConfigProvider` instead. +- BackTop is deprecated in `4.0.0`, and is merged into FloatButton. + +## Start upgrading + +Use git to save your code and install latest version: + +```bash +npm install --save antd@5.x +``` + +### less migration + +If you using ant-design-vue less variables, you can use compatible package to covert it into v3 less variables and use less-loader to inject them: + +```js +const { theme } = require('ant-design-vue/lib'); +const { convertLegacyToken } = require('@ant-design/compatible/lib'); + +const { defaultAlgorithm, defaultSeed } = theme; + +const mapToken = defaultAlgorithm(defaultSeed); +const v3Token = convertLegacyToken(mapToken); + +// Webpack Config +module.exports = { + // ... other config + loader: 'less-loader', + options: { + lessOptions: { + modifyVars: v3Token, + }, + }, +}; +``` + +Ant then remove ant-design-vue less reference in your less file: + +```diff +// Your less file +-- @import (reference) '~ant-design-vue/es/style/themes/index'; +or +-- @import '~ant-design-vue/es/style/some-other-less-file-ref'; +``` + +### Remove babel-plugin-import + +Remove `babel-plugin-import` from package.json and modify `.babelrc`: + +```diff +"plugins": [ +- ["import", { "libraryName": "ant-design-vue", "libraryDirectory": "lib"}, "ant-design-vue"], +] +``` + +### Replace Day.js locale + +Replace moment.js locale with day.js locale: + +```diff +- import moment from 'moment'; ++ import dayjs from 'dayjs'; +- import 'moment/locale/zh-cn'; ++ import 'dayjs/locale/zh-cn'; + +- moment.locale('zh-cn'); ++ dayjs.locale('zh-cn'); +``` + +### Legacy browser support + +Ant Design Vue v4 using `:where` css selector to reduce CSS-in-JS hash priority. You can use `StyleProvider` to cancel this function. Please ref [Compatible adjustment](/docs/vue/customize-theme#compatible-adjustment). + +## Encounter problems + +If you encounter problems during the upgrade, please go to [GitHub issues](https://github.com/vueComponent/ant-design-vue/issues) for feedback. We will respond and improve this document as soon as possible. diff --git a/site/src/vueDocs/migration-v4.zh-CN.md b/site/src/vueDocs/migration-v4.zh-CN.md new file mode 100644 index 0000000000..b5235957ba --- /dev/null +++ b/site/src/vueDocs/migration-v4.zh-CN.md @@ -0,0 +1,199 @@ +本文档将帮助你从 ant-design-vue `3.x` 版本升级到 ant-design-vue `4.x` 版本,如果你是 `2.x` 或者更老的版本,请先参考之前的[升级文档](/docs/vue/migration-v3-cn)升级到 3.x。 + +## 升级准备 + +1. 请先升级到 3.x 的最新版本,按照控制台 warning 信息移除/修改相关的 API。 + +## 4.0 有哪些不兼容的变化 + +### 设计规范调整 + +- 基础圆角调整,由统一的 `2px` 改为四级圆角,分别为 `2px` `4px` `6px` `8px`,分别应用于不同场景,比如默认尺寸的 Button 的圆角调整为了 `6px`。 +- 主色调整,由 `#1890ff` 改为 `#1677ff`。 +- 整体阴影调整,由原本的三级阴影调整为两级,分别用于常驻页面的组件(如 Card)和交互反馈(如 Dropdown)。 +- 部分组件内间距调整。 +- 整体去线框化。 + +### 技术调整 + +- 弃用 less,采用 CSS-in-JS,更好地支持动态主题。底层使用 [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) 作为解决方案。 + - 所有 less 文件全部移除,less 变量不再支持透出。 + - 产物中不再包含 css 文件。由于 CSS-in-JS 支持按需引入,原本的 `ant-design-vue/dist/antd.css` 也已经移除,如果需要重置一些基本样式请引入 `ant-design-vue/dist/reset.css`。 + - 如果需要组件重置样式,又不想引入 `ant-design-vue/dist/reset.css` 从而导致污染全局样式的话,可以尝试在应用最外层使用[App 组件](/components/app-cn),解决原生元素没有 ant-design-vue 规范样式的问题。 +- 移除 css variables 以及在此之上构筑的动态主题方案。 +- LocaleProvider 在 3.x 中已经废弃(使用 `` 替代),我们在 4.x 里彻底移除了相关目录 `ant-design-vue/es/locale-provider`、`ant-design-vue/lib/locale-provider`。 +- 内置的时间库使用 Dayjs 替代 Moment.js,具体请查看 [使用自定义日期库](/docs/vue/use-custom-date-library-cn/)。 +- 不再支持 `babel-plugin-import`,CSS-in-JS 本身具有按需加载的能力,不再需要插件支持。 + +### 兼容性调整 + +- 不再支持 IE 浏览器。 + +#### 组件 API 调整 + +- 组件弹框的 classname API 统一为 `popupClassName`,`dropdownClassName` 等类似 API 都会被替换。 + + - AutoComplete 组件 + - Cascader 组件 + - Select 组件 + - TreeSelect 组件 + - TimePicker 组件 + - DatePicker 组件 + - Mentions 组件 + + ```html + + + + ``` + +- 组件弹框的受控可见 API 统一为 `open`,`visible` 等类似 API 都会被替换。 + + - Drawer 组件 `visible` 变为 `open`。 + - Modal 组件 `visible` 变为 `open`。 + - Dropdown 组件 `visible` 变为 `open`。 + - Tooltip 组件 `visible` 变为 `open`。 + - Tag 组件 `visible` 已移除。 + - Slider 组件 `tooltip` 相关 API 收敛到 `tooltip` 属性中。 + - Table 组件 `filterDropdownVisible` 变为 `filterDropdownOpen`。 + + ```html + + + + ``` + +- `getPopupContainer`: 所有的 `getPopupContainer` 都需要保证返回的是唯一的 div。 +- Upload List dom 结构变化。[#34528](https://github.com/ant-design/ant-design/pull/34528) +- Notification + - 静态方法不再允许在 `open` 中动态设置 `prefixCls` `maxCount` `top` `bottom` `getContainer`,Notification 静态方法现在将只有一个实例。如果需要不同配置,请使用 `useNotification`。 + - `close` 改名为 `destroy`,和 message 保持一致。 +- Drawer `style` 和 `className` 迁移至 Drawer 弹层区域上,原属性替换为 `rootClassName` 和 `rootStyle`。 +- 3.x 中已经废弃的 `message.warn` 现在被彻底移除,请使用 `message.warning` 代替。 + +#### 组件重构与移除 + +- 移除 `locale-provider` 目录。`LocaleProvider` 在 v3 中已移除,请使用 `ConfigProvider` 替代。 + +- BackTop 组件在 `4.0.0` 中废弃,移至 FloatButton 悬浮按钮中。如需使用,可以从 FloatButton 中引入。 + +## 开始升级 + +通过 git 保存你的代码,然后按照上述文档进行依赖安装: + +```bash +npm install --save ant-design-vue@4.x +``` + +### less 迁移 + +如果你使用到了 ant-design-vue 的 less 变量,通过兼容包将 v4 变量转译成 v3 版本,并通过 less-loader 注入: + +```js +const { theme } = require('ant-design-vue/lib'); +const { convertLegacyToken } = require('@ant-design/compatible/lib'); + +const { defaultAlgorithm, defaultSeed } = theme; + +const mapToken = defaultAlgorithm(defaultSeed); +const v3Token = convertLegacyToken(mapToken); + +// Webpack Config +module.exports = { + // ... other config + loader: 'less-loader', + options: { + lessOptions: { + modifyVars: v3Token, + }, + }, +}; +``` + +同时移除对 ant-design-vue less 文件的直接引用: + +```diff +// Your less file +-- @import (reference) '~ant-design-vue/es/style/themes/index'; +or +-- @import '~ant-design-vue/es/style/some-other-less-file-ref'; +``` + +### 移除 babel-plugin-import + +从 package.json 中移除 `babel-plugin-import`,并从 `.babelrc` 移除该插件: + +```diff +"plugins": [ +- ["import", { "libraryName": "ant-design-vue", "libraryDirectory": "lib"}, "ant-design-vue"], +] +``` + +### 替换 Day.js 语言包 + +将 moment.js 的 locale 替换为 day.js 的 locale 引入: + +```diff +- import moment from 'moment'; ++ import dayjs from 'dayjs'; +- import 'moment/locale/zh-cn'; ++ import 'dayjs/locale/zh-cn'; + +- moment.locale('zh-cn'); ++ dayjs.locale('zh-cn'); +``` + +### 旧版浏览器兼容 + +Ant Design Vue v4 使用 `:where` css selector 降低 CSS-in-JS hash 值优先级,如果你需要支持旧版本浏览器(如 IE 11、360 浏览器 等等)。可以通过 `StyleProvider` 去除降权操作。详情请参阅 [兼容性调整](/docs/vue/customize-theme-cn#兼容性调整)。 + +## 遇到问题 + +如果您在升级过程中遇到了问题,请到 [GitHub issues](https://github.com/vueComponent/ant-design-vue/issues) 进行反馈。我们会尽快响应和相应改进这篇文档。 From 5f45324e02eb14969bcc1f1630da43bfbbc12acb Mon Sep 17 00:00:00 2001 From: shifeng1993 Date: Sun, 16 Apr 2023 10:46:19 +0800 Subject: [PATCH 04/12] fix docs --- site/src/vueDocs/getting-started.en-US.md | 2 +- site/src/vueDocs/getting-started.zh-CN.md | 2 +- site/src/vueDocs/introduce.en-US.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/site/src/vueDocs/getting-started.en-US.md b/site/src/vueDocs/getting-started.en-US.md index 836efd0326..08530f578b 100644 --- a/site/src/vueDocs/getting-started.en-US.md +++ b/site/src/vueDocs/getting-started.en-US.md @@ -101,7 +101,7 @@ In this way, component sub-components, such as Button and ButtonGroup, need to b ## Import on Demand -`antd` supports tree shaking of ES modules, so using `import { Button } from 'antd';` would drop js code you didn't use. +`ant-design-vue` supports tree shaking of ES modules, so using `import { Button } from 'ant-design-vue';` would drop js code you didn't use. ## Customization diff --git a/site/src/vueDocs/getting-started.zh-CN.md b/site/src/vueDocs/getting-started.zh-CN.md index 52b689e0dd..05b27da5e9 100644 --- a/site/src/vueDocs/getting-started.zh-CN.md +++ b/site/src/vueDocs/getting-started.zh-CN.md @@ -99,7 +99,7 @@ app.config.globalProperties.$message = message; ## 按需加载 -`antd` 默认支持基于 ES modules 的 tree shaking,直接引入 `import { Button } from 'antd';` 就会有按需加载的效果。 +`ant-design-vue` 默认支持基于 ES modules 的 tree shaking,直接引入 `import { Button } from 'ant-design-vue';` 就会有按需加载的效果。 ## 配置主题和字体 diff --git a/site/src/vueDocs/introduce.en-US.md b/site/src/vueDocs/introduce.en-US.md index d4cf1ae2af..9f27536639 100644 --- a/site/src/vueDocs/introduce.en-US.md +++ b/site/src/vueDocs/introduce.en-US.md @@ -94,9 +94,9 @@ And import stylesheets manually: import 'ant-design-vue/dist/reset.css'; ``` -### Use modularized antd +### Use modularized ant-design-vue -`antd` supports ES modules tree shaking by default. +`ant-design-vue` supports ES modules tree shaking by default. ## Links @@ -112,7 +112,7 @@ import 'ant-design-vue/dist/reset.css'; ## Contributing -If you'd like to help us improve antd, just create a [Pull Request](https://github.com/vueComponent/ant-design-vue/pulls). Feel free to report bugs and issues [here](https://vuecomponent.github.io/issue-helper/). +If you'd like to help us improve ant-design-vue, just create a [Pull Request](https://github.com/vueComponent/ant-design-vue/pulls). Feel free to report bugs and issues [here](https://vuecomponent.github.io/issue-helper/). > If you're new to posting issues, we ask that you read [_How To Ask Questions The Smart Way_](http://www.catb.org/~esr/faqs/smart-questions.html) and [How to Ask a Question in Open Source Community](https://github.com/seajs/seajs/issues/545) and [How to Report Bugs Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html) prior to posting. Well written bug reports help us help you! From 8d99a78dcccebdabd75d05a9b79b717225c79386 Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 14:28:13 +0800 Subject: [PATCH 05/12] Update migration-v4.zh-CN.md --- site/src/vueDocs/migration-v4.zh-CN.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/site/src/vueDocs/migration-v4.zh-CN.md b/site/src/vueDocs/migration-v4.zh-CN.md index b5235957ba..94a443ff30 100644 --- a/site/src/vueDocs/migration-v4.zh-CN.md +++ b/site/src/vueDocs/migration-v4.zh-CN.md @@ -22,7 +22,6 @@ - 如果需要组件重置样式,又不想引入 `ant-design-vue/dist/reset.css` 从而导致污染全局样式的话,可以尝试在应用最外层使用[App 组件](/components/app-cn),解决原生元素没有 ant-design-vue 规范样式的问题。 - 移除 css variables 以及在此之上构筑的动态主题方案。 - LocaleProvider 在 3.x 中已经废弃(使用 `` 替代),我们在 4.x 里彻底移除了相关目录 `ant-design-vue/es/locale-provider`、`ant-design-vue/lib/locale-provider`。 -- 内置的时间库使用 Dayjs 替代 Moment.js,具体请查看 [使用自定义日期库](/docs/vue/use-custom-date-library-cn/)。 - 不再支持 `babel-plugin-import`,CSS-in-JS 本身具有按需加载的能力,不再需要插件支持。 ### 兼容性调整 @@ -111,12 +110,7 @@ ``` - `getPopupContainer`: 所有的 `getPopupContainer` 都需要保证返回的是唯一的 div。 -- Upload List dom 结构变化。[#34528](https://github.com/ant-design/ant-design/pull/34528) -- Notification - - 静态方法不再允许在 `open` 中动态设置 `prefixCls` `maxCount` `top` `bottom` `getContainer`,Notification 静态方法现在将只有一个实例。如果需要不同配置,请使用 `useNotification`。 - - `close` 改名为 `destroy`,和 message 保持一致。 -- Drawer `style` 和 `className` 迁移至 Drawer 弹层区域上,原属性替换为 `rootClassName` 和 `rootStyle`。 -- 3.x 中已经废弃的 `message.warn` 现在被彻底移除,请使用 `message.warning` 代替。 +- Drawer `style` 和 `class` 迁移至 Drawer 弹层区域上,原属性替换为 `rootClassName` 和 `rootStyle`。 #### 组件重构与移除 @@ -176,20 +170,6 @@ or ] ``` -### 替换 Day.js 语言包 - -将 moment.js 的 locale 替换为 day.js 的 locale 引入: - -```diff -- import moment from 'moment'; -+ import dayjs from 'dayjs'; -- import 'moment/locale/zh-cn'; -+ import 'dayjs/locale/zh-cn'; - -- moment.locale('zh-cn'); -+ dayjs.locale('zh-cn'); -``` - ### 旧版浏览器兼容 Ant Design Vue v4 使用 `:where` css selector 降低 CSS-in-JS hash 值优先级,如果你需要支持旧版本浏览器(如 IE 11、360 浏览器 等等)。可以通过 `StyleProvider` 去除降权操作。详情请参阅 [兼容性调整](/docs/vue/customize-theme-cn#兼容性调整)。 From 8849f3cafe982ec6613949ed1811498281d955be Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 14:53:56 +0800 Subject: [PATCH 06/12] Update migration-v4.zh-CN.md --- site/src/vueDocs/migration-v4.zh-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/vueDocs/migration-v4.zh-CN.md b/site/src/vueDocs/migration-v4.zh-CN.md index 94a443ff30..5450d92bf6 100644 --- a/site/src/vueDocs/migration-v4.zh-CN.md +++ b/site/src/vueDocs/migration-v4.zh-CN.md @@ -132,7 +132,7 @@ npm install --save ant-design-vue@4.x ```js const { theme } = require('ant-design-vue/lib'); -const { convertLegacyToken } = require('@ant-design/compatible/lib'); +const convertLegacyToken = require('ant-design-vue/lib/theme/convertLegacyToken'); const { defaultAlgorithm, defaultSeed } = theme; From dc4b8772b95ef6100a4e83a6da47741829fbb6d5 Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:41:57 +0800 Subject: [PATCH 07/12] Update migration-v4.en-US.md --- site/src/vueDocs/migration-v4.en-US.md | 27 ++++---------------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/site/src/vueDocs/migration-v4.en-US.md b/site/src/vueDocs/migration-v4.en-US.md index 8237e02f87..0a02366a8b 100644 --- a/site/src/vueDocs/migration-v4.en-US.md +++ b/site/src/vueDocs/migration-v4.en-US.md @@ -15,7 +15,7 @@ This document will help you upgrade from ant-design-vue `3.x` version to ant-des ### Technology adjustment -- Remove less, adopt CSS-in-JS, for better support of dynamic themes. The bottom layer uses [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) as a solution. +- Remove less, adopt CSS-in-JS, for better support of dynamic themes. - All less files are removed, and less variables are no longer exported. - Css files are no longer included in package. Since CSS-in-JS supports importing on demand, the original `ant-design-vue/dist/antd.css` has also been abandoned. If you need to reset some basic styles, please import `ant-design-vue/dist/reset.css`. - If you need to reset the style of the component, but you don't want to introduce `ant-design-vue/dist/reset.css` to pollute the global style, You can try using the [App](/components/app) in the outermost layer to solve the problem that native elements do not have antd specification style. @@ -110,12 +110,7 @@ This document will help you upgrade from ant-design-vue `3.x` version to ant-des ``` - `getPopupContainer`: All `getPopupContainer` are guaranteed to return a unique div. -- Upload List structure changes. [#34528](https://github.com/ant-design/ant-design/pull/34528) -- Notification - - Static methods are no longer allowed to dynamically set `prefixCls` `maxCount` `top` `bottom` `getContainer` in `open`, Notification static methods will now have only one instance. If you need a different configuration, use `useNotification`. - - `close` was renamed to `destroy` to be consistent with message. -- Drawer `style` & `className` are migrated to Drawer panel node, the original properties are replaced by `rootClassName` and `rootStyle`. -- The deprecated `message.warn` in 3.x is now completely removed, please use `message.warning` instead. +- Drawer `style` & `class` are migrated to Drawer panel node, the original properties are replaced by `rootClassName` and `rootStyle`. #### Component refactoring and removal @@ -127,7 +122,7 @@ This document will help you upgrade from ant-design-vue `3.x` version to ant-des Use git to save your code and install latest version: ```bash -npm install --save antd@5.x +npm install --save ant-design-vue@4 ``` ### less migration @@ -136,7 +131,7 @@ If you using ant-design-vue less variables, you can use compatible package to co ```js const { theme } = require('ant-design-vue/lib'); -const { convertLegacyToken } = require('@ant-design/compatible/lib'); +const convertLegacyToken = require('ant-design-vue/lib/theme/convertLegacyToken'); const { defaultAlgorithm, defaultSeed } = theme; @@ -174,20 +169,6 @@ Remove `babel-plugin-import` from package.json and modify `.babelrc`: ] ``` -### Replace Day.js locale - -Replace moment.js locale with day.js locale: - -```diff -- import moment from 'moment'; -+ import dayjs from 'dayjs'; -- import 'moment/locale/zh-cn'; -+ import 'dayjs/locale/zh-cn'; - -- moment.locale('zh-cn'); -+ dayjs.locale('zh-cn'); -``` - ### Legacy browser support Ant Design Vue v4 using `:where` css selector to reduce CSS-in-JS hash priority. You can use `StyleProvider` to cancel this function. Please ref [Compatible adjustment](/docs/vue/customize-theme#compatible-adjustment). From 1e2fc8bf2692761d30a69d7597c77ec3e5d991b3 Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:42:53 +0800 Subject: [PATCH 08/12] Update migration-v4.zh-CN.md --- site/src/vueDocs/migration-v4.zh-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/vueDocs/migration-v4.zh-CN.md b/site/src/vueDocs/migration-v4.zh-CN.md index 5450d92bf6..c76ba63c51 100644 --- a/site/src/vueDocs/migration-v4.zh-CN.md +++ b/site/src/vueDocs/migration-v4.zh-CN.md @@ -16,7 +16,7 @@ ### 技术调整 -- 弃用 less,采用 CSS-in-JS,更好地支持动态主题。底层使用 [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) 作为解决方案。 +- 弃用 less,采用 CSS-in-JS,更好地支持动态主题。 - 所有 less 文件全部移除,less 变量不再支持透出。 - 产物中不再包含 css 文件。由于 CSS-in-JS 支持按需引入,原本的 `ant-design-vue/dist/antd.css` 也已经移除,如果需要重置一些基本样式请引入 `ant-design-vue/dist/reset.css`。 - 如果需要组件重置样式,又不想引入 `ant-design-vue/dist/reset.css` 从而导致污染全局样式的话,可以尝试在应用最外层使用[App 组件](/components/app-cn),解决原生元素没有 ant-design-vue 规范样式的问题。 From 2e35ce7b89e883594dd9561831f7db5d1b53090d Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:43:40 +0800 Subject: [PATCH 09/12] Update getting-started.en-US.md --- site/src/vueDocs/getting-started.en-US.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/vueDocs/getting-started.en-US.md b/site/src/vueDocs/getting-started.en-US.md index 08530f578b..b67fffe0aa 100644 --- a/site/src/vueDocs/getting-started.en-US.md +++ b/site/src/vueDocs/getting-started.en-US.md @@ -37,7 +37,7 @@ And, setup your vue project configuration. #### Install ```bash -$ npm i --save ant-design-vue@next +$ npm i --save ant-design-vue@4.x ``` #### Component Registration From 945b86598c43c92d65923199ac9b6a2462ae12fa Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:44:16 +0800 Subject: [PATCH 10/12] Update getting-started.zh-CN.md --- site/src/vueDocs/getting-started.zh-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/vueDocs/getting-started.zh-CN.md b/site/src/vueDocs/getting-started.zh-CN.md index 05b27da5e9..c0f97e5e7a 100644 --- a/site/src/vueDocs/getting-started.zh-CN.md +++ b/site/src/vueDocs/getting-started.zh-CN.md @@ -39,7 +39,7 @@ $ vue create antd-demo #### 安装 ```bash -$ npm i --save ant-design-vue@next +$ npm i --save ant-design-vue@4.x ``` #### 注册 From 9b1e170ad2e1699ca5a4380c87622186c1d6c240 Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:44:46 +0800 Subject: [PATCH 11/12] Update introduce.en-US.md --- site/src/vueDocs/introduce.en-US.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/src/vueDocs/introduce.en-US.md b/site/src/vueDocs/introduce.en-US.md index 9f27536639..771985c882 100644 --- a/site/src/vueDocs/introduce.en-US.md +++ b/site/src/vueDocs/introduce.en-US.md @@ -49,11 +49,11 @@ You can subscribe to this feed for new version notifications: https://github.com **We recommend using npm or yarn to install**,it not only makes development easier,but also allow you to take advantage of the rich ecosystem of Javascript packages and tooling. ```bash -$ npm install ant-design-vue@next --save +$ npm install ant-design-vue@4.x --save ``` ```bash -$ yarn add ant-design-vue@next +$ yarn add ant-design-vue@4.x ``` If you are in a bad network environment,you can try other registries and tools like [cnpm](https://github.com/cnpm/cnpm). From 59d669226dd8b4fbfb9309223694030466b0ea8a Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Fri, 21 Apr 2023 15:45:22 +0800 Subject: [PATCH 12/12] Update introduce.zh-CN.md --- site/src/vueDocs/introduce.zh-CN.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/src/vueDocs/introduce.zh-CN.md b/site/src/vueDocs/introduce.zh-CN.md index a561c99e63..8b231d653e 100644 --- a/site/src/vueDocs/introduce.zh-CN.md +++ b/site/src/vueDocs/introduce.zh-CN.md @@ -49,11 +49,11 @@ **我们推荐使用 npm 或 yarn 的方式进行开发**,不仅可在开发环境轻松调试,也可放心地在生产环境打包部署使用,享受整个生态圈和工具链带来的诸多好处。 ```bash -$ npm install ant-design-vue@next --save +$ npm install ant-design-vue@4.x --save ``` ```bash -$ yarn add ant-design-vue@next +$ yarn add ant-design-vue@4.x ``` 如果你的网络环境不佳,推荐使用 [cnpm](https://github.com/cnpm/cnpm)。