docs: v4 vuedocs (#6468)
* fix introduce doc * fix getting-started doc * add migration-v4 doc * fix docs * Update migration-v4.zh-CN.md * Update migration-v4.zh-CN.md * Update migration-v4.en-US.md * Update migration-v4.zh-CN.md * Update getting-started.en-US.md * Update getting-started.zh-CN.md * Update introduce.en-US.md * Update introduce.zh-CN.md --------- Co-authored-by: tangjinzhou <415800467@qq.com>pull/6514/head
果冻橙
GitHub
parent
0683ede0fb
commit
118ae9a50b
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ And, setup your vue project configuration.
|
|||
#### Install
|
||||
|
||||
```bash
|
||||
$ npm i --save ant-design-vue
|
||||
$ npm i --save ant-design-vue@4.x
|
||||
```
|
||||
|
||||
#### 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
|
||||
```
|
||||
`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
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ $ vue create antd-demo
|
|||
#### 安装
|
||||
|
||||
```bash
|
||||
$ npm i --save ant-design-vue
|
||||
$ npm i --save ant-design-vue@4.x
|
||||
```
|
||||
|
||||
#### 注册
|
||||
|
|
@ -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;
|
|||
</script>
|
||||
```
|
||||
|
||||
## 兼容性
|
||||
|
||||
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
|
||||
```
|
||||
`ant-design-vue` 默认支持基于 ES modules 的 tree shaking，直接引入 `import { Button } from 'ant-design-vue';` 就会有按需加载的效果。
|
||||
|
||||
## 配置主题和字体
|
||||
|
||||
|
|
|
|||
|
|
@ -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@4.x --save
|
||||
```
|
||||
|
||||
```bash
|
||||
$ yarn add ant-design-vue
|
||||
$ 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).
|
||||
|
|
@ -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 [](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 [](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:
|
|||
<script src="https://unpkg.com/dayjs/plugin/weekOfYear.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/weekYear.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/advancedFormat.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/quarterOfYear.js"></script>
|
||||
```
|
||||
|
||||
## 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 modularized ant-design-vue
|
||||
|
||||
- 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()],
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
`ant-design-vue` supports ES modules tree shaking by default.
|
||||
|
||||
## Links
|
||||
|
||||
|
|
@ -154,7 +112,7 @@ import 'ant-design-vue/dist/antd.css'; // or 'ant-design-vue/dist/antd.less'
|
|||
|
||||
## 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!
|
||||
|
||||
|
|
|
|||
|
|
@ -49,11 +49,11 @@
|
|||
**我们推荐使用 npm 或 yarn 的方式进行开发**，不仅可在开发环境轻松调试，也可放心地在生产环境打包部署使用，享受整个生态圈和工具链带来的诸多好处。
|
||||
|
||||
```bash
|
||||
$ npm install ant-design-vue --save
|
||||
$ npm install ant-design-vue@4.x --save
|
||||
```
|
||||
|
||||
```bash
|
||||
$ yarn add ant-design-vue
|
||||
$ yarn add ant-design-vue@4.x
|
||||
```
|
||||
|
||||
如果你的网络环境不佳，推荐使用 [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`。你也可以通过 [](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`。你也可以通过 [](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
|
|||
<script src="https://unpkg.com/dayjs/plugin/weekOfYear.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/weekYear.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/advancedFormat.js"></script>
|
||||
<script src="https://unpkg.com/dayjs/plugin/quarterOfYear.js"></script>
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
|
@ -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。
|
||||
|
||||
## 链接
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,178 @@
|
|||
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.
|
||||
- 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 `<ConfigProvider locale />` 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
|
||||
<template>
|
||||
<a-select - dropdownClassName="my-select-popup" + popupClassName="my-select-popup" />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'App',
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
- 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
|
||||
<template>
|
||||
-
|
||||
<a-modal :visible="visible">content</a-modal>
|
||||
+
|
||||
<a-modal :open="visible">content</a-modal>
|
||||
|
||||
-
|
||||
<a-tag :visible="visible">tag</a-tag>
|
||||
+
|
||||
<a-tag v-if="visible">tag</a-tag>
|
||||
|
||||
<a-table
|
||||
:data="[]"
|
||||
:columns="[
|
||||
{
|
||||
title: 'Name',
|
||||
dataIndex: 'name',
|
||||
- filterDropdownVisible: visible,
|
||||
+ filterDropdownOpen: visible,
|
||||
},
|
||||
]"
|
||||
/>
|
||||
|
||||
-
|
||||
<a-slider :tooltipVisible="visible" />
|
||||
+
|
||||
<a-slider :tooltip="{ open: visible }" />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'App',
|
||||
setup() {
|
||||
const visible = ref(true);
|
||||
return {
|
||||
visible,
|
||||
};
|
||||
},
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
- `getPopupContainer`: All `getPopupContainer` are guaranteed to return a unique div.
|
||||
- Drawer `style` & `class` are migrated to Drawer panel node, the original properties are replaced by `rootClassName` and `rootStyle`.
|
||||
|
||||
#### 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 ant-design-vue@4
|
||||
```
|
||||
|
||||
### 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-vue/lib/theme/convertLegacyToken');
|
||||
|
||||
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"],
|
||||
]
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
本文档将帮助你从 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，更好地支持动态主题。
|
||||
- 所有 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 中已经废弃（使用 `<ConfigProvider locale />` 替代），我们在 4.x 里彻底移除了相关目录 `ant-design-vue/es/locale-provider`、`ant-design-vue/lib/locale-provider`。
|
||||
- 不再支持 `babel-plugin-import`，CSS-in-JS 本身具有按需加载的能力，不再需要插件支持。
|
||||
|
||||
### 兼容性调整
|
||||
|
||||
- 不再支持 IE 浏览器。
|
||||
|
||||
#### 组件 API 调整
|
||||
|
||||
- 组件弹框的 classname API 统一为 `popupClassName`，`dropdownClassName` 等类似 API 都会被替换。
|
||||
|
||||
- AutoComplete 组件
|
||||
- Cascader 组件
|
||||
- Select 组件
|
||||
- TreeSelect 组件
|
||||
- TimePicker 组件
|
||||
- DatePicker 组件
|
||||
- Mentions 组件
|
||||
|
||||
```html
|
||||
<template>
|
||||
<a-select - dropdownClassName="my-select-popup" + popupClassName="my-select-popup" />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'App',
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
- 组件弹框的受控可见 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
|
||||
<template>
|
||||
-
|
||||
<a-modal :visible="visible">content</a-modal>
|
||||
+
|
||||
<a-modal :open="visible">content</a-modal>
|
||||
|
||||
-
|
||||
<a-tag :visible="visible">tag</a-tag>
|
||||
+
|
||||
<a-tag v-if="visible">tag</a-tag>
|
||||
|
||||
<a-table
|
||||
:data="[]"
|
||||
:columns="[
|
||||
{
|
||||
title: 'Name',
|
||||
dataIndex: 'name',
|
||||
- filterDropdownVisible: visible,
|
||||
+ filterDropdownOpen: visible,
|
||||
},
|
||||
]"
|
||||
/>
|
||||
|
||||
-
|
||||
<a-slider :tooltipVisible="visible" />
|
||||
+
|
||||
<a-slider :tooltip="{ open: visible }" />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
export default defineComponent({
|
||||
name: 'App',
|
||||
setup() {
|
||||
const visible = ref(true);
|
||||
return {
|
||||
visible,
|
||||
};
|
||||
},
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
- `getPopupContainer`: 所有的 `getPopupContainer` 都需要保证返回的是唯一的 div。
|
||||
- Drawer `style` 和 `class` 迁移至 Drawer 弹层区域上，原属性替换为 `rootClassName` 和 `rootStyle`。
|
||||
|
||||
#### 组件重构与移除
|
||||
|
||||
- 移除 `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-vue/lib/theme/convertLegacyToken');
|
||||
|
||||
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"],
|
||||
]
|
||||
```
|
||||
|
||||
### 旧版浏览器兼容
|
||||
|
||||
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) 进行反馈。我们会尽快响应和相应改进这篇文档。
|
||||
Loading…
Reference in New Issue