github
/
ant-design-vue
mirror of https://github.com/vueComponent/ant-design-vue
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: add changelog

v2.3
tangjinzhou 2021-09-24 17:03:14 +08:00
parent a9cad66b58
commit 845cdca89f
13 changed files with 483 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
CHANGELOG.en-US.md
View File

@ -4,12 +4,115 @@
#### Release Schedule
- Weekly release: patch version for routine bugfix.
- Monthly release: minor version for new features.
- Weekly release: patch version at the end of every week for routine bugfix (anytime for urgent bugfix).
- Monthly release: minor version at the end of every month for new features.
- Major version release is not included in this schedule for breaking change and new features.
---
## 3.0.0-alpha.0
`2021-09-24`
🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥
- Open source documentation
- Removed the `lazy` attribute of Transfer, it does not have a real optimization effect.
- Removed the `combobox` mode of Select, please use `AutoComplete` instead.
- Deprecated Button.Group, please use `Space` instead.
- `Timeline.Item` new label
- `Steps` added `responsive`, `percent`
- `Collapse` added `ghost`, `collapsible`
- `Popconfirm` added `cancelButton`, `okButton`, and `esc` button hiding
- `ConfigProvider` added ConfigProvider.config to define the configuration of `Modal.xxx` `message` `notification`
- `Tree` `TreeSlelct`
- Added virtual scrolling, discarded using `a-tree-node` `a-tree-select-node` to build nodes, using `treeData` property instead to improve component performance
- Deprecated `scopedSlots` `slots` custom rendering node, and replace it with `v-slot:title` to improve ease of use, avoid slot configuration expansion, and also avoid slot conflicts
- `Table`
- Removed the `rowSelection.hideDefaultSelections` property of Table, please use `SELECTION_ALL` and `SELECTION_INVERT` in `rowSelection.selections` instead, [custom options](/components/table/#components-table-demo- row-selection-custom).
- Removed Column slots and replaced them with `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon` to improve ease of use , To avoid slot configuration expansion, but also to avoid the problem of slot conflicts
- Added expandFixed to control whether the expanded icon is fixed
- Added the showSorterTooltip header whether to display the tooltip for the next sort.
- Added sticky for setting sticky head and scroll bar
- Added rowExpandable to set whether to allow row expansion
- New slot headerCell is used to personalize the header cell
- Added slot bodyCell for personalized cell
- New slot customFilterDropdown is used to customize the filter menu, which needs to be used with `column.customFilterDropdown`
- Added slot customFilterIcon for custom filter icons
- New slot emptyText is used to customize the display content of empty data
- Added slot summary for the summary column
- `DatePicker` `TimePicker` `Calendar`
- By default, a more lightweight dayjs is used to replace momentjs. If your project is too large and uses a lot of momentjs methods, you can refer to the document [Custom Time Library](/docs/vue/replace-date-cn), Replace with momentjs.
- UI interaction adjustment, its antd 4.x interaction specification
- `Form` The main goal of this update is to improve performance. If you don't have custom form controls, you can almost ignore this part
- Since version 3.0, Form.Item no longer hijacks child elements, but automatically checks through provider/inject dependency injection. This method can improve component performance, and there is no limit to the number of child elements. The same is true for child elements. It can be a high-level component that is further encapsulated.
You can reference [Customized Form Controls](#components-form-demo-customized-form-controls)
But it also has some disadvantages:
1. If the custom component wants Form.Item to be verified and displayed, you need to inject `const {id, onFieldChange, onFieldBlur} = useFormItemContext()` and call the corresponding method.
2. A Form.Item can only collect the data of one form item. If there are multiple form items, it will cause collection confusion, for example,
```html
<a-form-item>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</a-form-item>
```
As above Form.Item does not know whether to collect `name="a"` or `name=`b``, you can solve this kind of problem in the following two ways:
The first is to use multiple `a-form-item`:
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item><a-input name="b"></a-input></a-form-item>
</a-form-item>
```
The second way is to wrap it with a custom component and call `useFormItemContext` in the custom component, It is equivalent to merging multiple form items into one.
```html
<script>
// custom component
import { Form } from 'ant-desing-vue';
export default {
name: 'custom-name',
setup() {
const formItemContext = Form.useFormItemContext();
},
};
</script>
```
```html
<a-form-item>
<custom-com>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</custom-com>
</a-form-item>
```
Third, the component library provides an `a-form-item-rest` component, which will prevent data collection. You can put form items that do not need to be collected and verified into this component. It is the same as the first This method is very similar, but it does not generate additional dom nodes.
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item-rest><a-input name="b"></a-input></a-form-item-rest>
</a-form-item>
```
## 2.2.8
`2021-09-17`

104
CHANGELOG.zh-CN.md
View File

@ -4,12 +4,112 @@
#### 发布周期
- 修订版本号：日常 bugfix 更新
- 次版本号：带有新特性的向下兼容的版本。
- 修订版本号：每周末会进行日常 bugfix 更新。（如果有紧急的 bugfix，则任何时候都可发布）
- 次版本号：每月发布一个带有新特性的向下兼容的版本。
- 主版本号：含有破坏性更新和新特性，不在发布周期内。
---
## 3.0.0-alpha.0
`2021-09-24`
🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥
- 文档开源，如果您的公司不能外网访问，可以私有化部署，但不可以传播，不可以商业化
- 移除了 Transfer 的 `lazy` 属性，它并没有起到真正的优化效果。
- 移除了 Select 的 `combobox` 模式，请使用 `AutoComplete` 替代。
- 废弃 Button.Group，请使用 `Space` 代替。
- `Timeline.Item` 新增 label
- `Steps` 新增 `responsive`、`percent`
- `Collapse` 新增 `ghost`、`collapsible`
- `Popconfirm` 新增 `cancelButton`、`okButton`, 以及 `esc` 按键隐藏
- `ConfigProvider` 新增 ConfigProvider.config，定义 `Modal.xxx` `message` `notification` 的配置
- `Tree` `TreeSlelct`
- 新增了虚拟滚动，废弃使用 `a-tree-node` `a-tree-select-node` 构建节点，使用 `treeData` 属性替代，提升组件性能
- 废弃 `scopedSlots` `slots` 自定义渲染节点，使用 `v-slot:title` 替换，提升易用性，避免插槽配置膨胀，同时也避免了插槽冲突问题
- `Table`
- 移除了 Table 的 `rowSelection.hideDefaultSelections` 属性，请在 `rowSelection.selections` 中使用 `SELECTION_ALL` 和 `SELECTION_INVERT` 替代，[自定义选择项](/components/table/#components-table-demo-row-selection-custom)。
- 移除了 Column slots，分别使用 `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon` 替换，提升易用性，避免插槽配置膨胀，同时也避免了插槽冲突问题
- 新增 expandFixed 控制展开图标是否固定
- 新增 showSorterTooltip 表头是否显示下一次排序的 tooltip 提示。
- 新增 sticky 用于设置粘性头部和滚动条
- 新增 rowExpandable 用于设置是否允许行展开
- 新增插槽 headerCell 用于个性化头部单元格
- 新增插槽 bodyCell 用于个性化单元格
- 新增插槽 customFilterDropdown 用于自定义筛选菜单，需要配合 `column.customFilterDropdown` 使用
- 新增插槽 customFilterIcon 用于自定义筛选图标
- 新增插槽 emptyText 用于自定义空数据时的显示内容
- 新增插槽 summary 用于总结栏
- `DatePicker` `TimePicker` `Calendar`
- 默认使用更加轻量级的 dayjs 替换 momentjs，如果你的项目过大，使用了大量的 momentjs 的方法，你可以参考文档[自定义时间库](/docs/vue/replace-date-cn)，替换成 momentjs。
- UI 交互调整，对其 antd 4.x 交互规范
- `Form` 这次更新主要目标是提升性能，如果你没有自定义表单控件，几乎可以忽略该部分
- 自 3.0 版本以后，Form.Item 不再劫持子元素，而是通过 provider / inject 依赖注入的方式进行自动校验，这种方式可以提高组件性能，子元素也不会限制个数，同样子元素也可以是进一步封装的高级组件。你可以参考[自定义表单控件示例](#components-form-demo-customized-form-controls)
但它同样会有一些缺点：
1、自定义组件如果希望 Form.Item 进行校验展示，你需要 `const {id, onFieldChange, onFieldBlur} = useFormItemContext()` 注入，并调用相应的方法。
2、一个 Form.Item 只能收集一个表单项的数据，如果有多个表单项，会导致收集错乱，例如，
```html
<a-form-item>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</a-form-item>
```
如上 Form.Item 并不知道需要收集 `name="a"` 还是 `name=`b``，你可以通过如下三种方式去解决此类问题：
第一种，使用多个 `a-form-item`:
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item><a-input name="b"></a-input></a-form-item>
</a-form-item>
```
第二种，使用自定义组件包裹，并在自定义组件中调用 `useFormItemContext`，相当于把多个表单项合并成了一个
```html
<script>
// 自定义组件
import { Form } from 'ant-desing-vue';
export default {
setup() {
const formItemContext = Form.useFormItemContext();
},
};
</script>
```
```html
<a-form-item>
<custom-com>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</custom-com>
</a-form-item>
```
第三种，组件库提供了一个 `a-form-item-rest` 组件，它会阻止数据的收集，你可以将不需要收集校验的表单项放到这个组件中即可，它和第一种方式很类似，但它不会产生额外的 dom 节点。
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item-rest><a-input name="b"></a-input></a-form-item-rest>
</a-form-item>
```
## 2.2.8
`2021-09-17`

1
components/affix/index.tsx
View File

@ -46,7 +46,6 @@ const affixProps = {
* 距离窗口顶部达到指定偏移量后触发
*/
offsetTop: PropTypes.number,
offset: PropTypes.number,
/** 距离窗口底部达到指定偏移量后触发 */
offsetBottom: PropTypes.number,
/** 固定状态改变时触发的回调函数 */

1
components/transfer/index.en-US.md
View File

@ -20,7 +20,6 @@ Alert component for feedback.
| disabled | Whether disabled transfer | boolean | false | |
| filterOption | A function to determine whether an item should show in search result list | (inputValue, option): boolean | | |
| footer | customize the progress dot by setting a scoped slot | slot="footer" slot-scope="props" | | |
| lazy | property of vc-lazy-load for lazy rendering items. Turn off it by set to `false`. | object\|boolean | `{ height: 32, offset: 32 }` | |
| listStyle | A custom CSS style used for rendering the transfer columns. | object | | |
| locale | i18n text including filter, empty text, item unit, etc | object | `{ itemUnit: 'item', itemsUnit: 'items', notFoundContent: 'The list is empty', searchPlaceholder: 'Search here' }` | |
| operations | A set of operations that are sorted from top to bottom. | string\[] | \['>', '<'] | |

3
components/transfer/index.tsx
View File

@ -92,7 +92,6 @@ export const transferProps = {
pagination: { type: [Object, Boolean] as PropType<PaginationType>, default: undefined },
onChange: PropTypes.func,
onSelectChange: PropTypes.func,
onSearchChange: PropTypes.func,
onSearch: PropTypes.func,
onScroll: PropTypes.func,
['onUpdate:targetKeys']: PropTypes.func,
@ -114,7 +113,7 @@ const Transfer = defineComponent({
'rightSelectAllLabel',
'footer',
],
emits: ['update:targetKeys', 'change', 'search', 'scroll', 'selectChange', 'searchChange'],
emits: ['update:targetKeys', 'change', 'search', 'scroll', 'selectChange'],
setup(props, { emit, attrs, slots, expose }) {
const { configProvider, prefixCls, direction } = useConfigInject('transfer', props);
const sourceSelectedKeys = ref([]);

1
components/transfer/index.zh-CN.md
View File

@ -21,7 +21,6 @@ cover: https://gw.alipayobjects.com/zos/alicdn/QAXskNI4G/Transfer.svg
| disabled | 是否禁用 | boolean | false | |
| filterOption | 接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | (inputValue, option): boolean | | |
| footer | 可以设置为一个 作用域插槽 | slot="footer" slot-scope="props" | | |
| lazy | Transfer 使用了 [vc-lazy-load]优化性能，这里可以设置相关参数。设为 `false` 可以关闭懒加载。 | object\|boolean | `{ height: 32, offset: 32 }` | |
| listStyle | 两个穿梭框的自定义样式 | object | | |
| locale | 各种语言 | object | `{ itemUnit: '项', itemsUnit: '项', notFoundContent: '列表为空', searchPlaceholder: '请输入搜索内容' }` | |
| operations | 操作文案集合，顺序从上至下 | string\[] | \['>', '<'] | |

4
components/tree-select/index.en-US.md
View File

@ -49,6 +49,7 @@ Tree selection control.
| treeNodeFilterProp | Will be used for filtering if `filterTreeNode` returns true | string | 'value' | |
| treeNodeLabelProp | Will render as content of select | string | 'title' | |
| value(v-model) | To set the current selected treeNode(s). | string\|string\[] | - | |
| title | custom title | slot | | 3.0.0 |
### Events
@ -78,9 +79,8 @@ Tree selection control.
| disabled | Disabled or not | boolean | false | |
| isLeaf | Leaf node or not | boolean | false | |
| key | Required property, should be unique in the tree | string \| number | - | |
| title | Content showed on the treeNodes | string\|slot | '---' | |
| title | Content showed on the treeNodes | string | '---' | |
| value | Will be treated as `treeNodeFilterProp` by default, should be unique in the tree | string | - | |
| scopedSlots | When using treeNodes, you can use this property to configure the properties that support the slot, such as `scopedSlots: { title: 'XXX'}` | object | - | |
## FAQ

2
components/tree-select/index.zh-CN.md
View File

@ -50,6 +50,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Ax4DA0njr/TreeSelect.svg
| treeNodeFilterProp | 输入项过滤对应的 treeNode 属性 | string | 'value' | |
| treeNodeLabelProp | 作为显示的 prop 设置 | string | 'title' | |
| value(v-model) | 指定当前选中的条目 | string/string\[] | - | |
| title | 自定义标题 | slot | | 3.0.0 |
### 事件
@ -81,4 +82,3 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Ax4DA0njr/TreeSelect.svg
| key | 此项必须设置（其值在整个树范围内唯一） | string \| number | - | |
| title | 树节点显示的内容 | string\|slot | '---' | |
| value | 默认根据此属性值进行筛选（其值在整个树范围内唯一） | string | - | |
| scopedSlots | 使用 treeData 时，可以通过该属性配置支持 slot 的属性，如 `scopedSlots: { title: 'XXX'}` | object | - | |

11
components/tree/index.en-US.md
View File

@ -17,7 +17,7 @@ Almost anything can be represented in a tree structure. Examples include directo
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| treeData | treeNode of tree, please use `treeNodes` before v1.1.4 | array | - | |
| treeData | treeNode of tree, please use `treeNodes` before v1.1.4 | [TreeNode[]](#TreeNode) | - | |
| replaceFields | Replace the title,key and children fields in treeNode with the corresponding fields in treeData | object | { children:'children', title:'title', key:'key' } | |
| autoExpandParent | Whether to automatically expand a parent treeNode | boolean | true | |
| blockNode | Whether treeNode fill remaining horizontal space | boolean | false | |
@ -37,7 +37,7 @@ Almost anything can be represented in a tree structure. Examples include directo
| showIcon | Shows the icon before a TreeNode's title. There is no default style; you must set a custom style for it if set to `true` | boolean | false | |
| switcherIcon | customize collapse/expand icon of tree node | slot | - | |
| showLine | Shows a connecting line | boolean | false | |
| title | Title | slot | | 2.0.0 |
| title | custom title | slot | | 2.0.0 |
### Events
@ -55,9 +55,7 @@ Almost anything can be represented in a tree structure. Examples include directo
| rightClick | Callback function for when the user right clicks a treeNode | function({event, node}) |
| select | Callback function for when the user clicks a treeNode | function(selectedKeys, e:{selected: bool, selectedNodes, node, event}) |
### TreeNode props
One of the Tree `treeNode` prop for describing the tree's node, TreeNode has the same API.
### TreeNode
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
@ -70,8 +68,7 @@ One of the Tree `treeNode` prop for describing the tree's node, TreeNode has the
| isLeaf | Determines if this is a leaf node(effective when `loadData` is specified) | boolean | false | |
| key | Used with (default)ExpandedKeys / (default)CheckedKeys / (default)SelectedKeys. P.S.: It must be unique in all of treeNodes of the tree! | string \| number | internal calculated position of treeNode | |
| selectable | Set whether the treeNode can be selected | boolean | true | |
| title | Title | string\|slot\|slot-scope | '---' | |
| slots | When using treeNodes, you can use this property to configure the properties that support the slot, such as `slots: { title: 'XXX'}` | object | - | |
| title | Title | string | '---' | |
### DirectoryTree props

11
components/tree/index.zh-CN.md
View File

@ -19,7 +19,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Xh-oWqg9k/Tree.svg
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- | --- |
| blockNode | 是否节点占据一行 | boolean | false | |
| treeData | treeNodes 数据，如果设置则不需要手动构造 TreeNode 节点（key 在整个树范围内唯一） | array\<{key, title, children, \[disabled, selectable]}> | -- | |
| treeData | treeNodes 数据，如果设置则不需要手动构造 TreeNode 节点（key 在整个树范围内唯一） | [TreeNode[]](#TreeNode) | -- | |
| replaceFields | 替换 treeNode 中 title,key,children 字段为 treeData 中对应的字段 | object | {children:'children', title:'title', key:'key' } | |
| autoExpandParent | 是否自动展开父节点 | boolean | true | |
| checkable | 节点前添加 Checkbox 复选框 | boolean | false | |
@ -38,7 +38,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Xh-oWqg9k/Tree.svg
| showIcon | 是否展示 TreeNode title 前的图标，没有默认样式，如设置为 true，需要自行定义图标相关样式 | boolean | false | |
| switcherIcon | 自定义树节点的展开/折叠图标 | slot | - | |
| showLine | 是否展示连接线 | boolean | false | |
| title | 标题 | slot | | 2.0.0 |
| title | 自定义标题 | slot | | 2.0.0 |
### 事件
@ -56,9 +56,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Xh-oWqg9k/Tree.svg
| rightClick | 响应右键点击 | function({event, node}) |
| select | 点击树节点触发 | function(selectedKeys, e:{selected: bool, selectedNodes, node, event}) |
### TreeNode props
结点描述数据对象，是 treeNodes 中的一项，TreeNode 使用相同的 API。
### TreeNode
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
@ -71,8 +69,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/Xh-oWqg9k/Tree.svg
| isLeaf | 设置为叶子节点(设置了`loadData`时有效) | boolean | false | |
| key | 被树的 (default)ExpandedKeys / (default)CheckedKeys / (default)SelectedKeys 属性所用。注意：整个树范围内的所有节点的 key 值不能重复！ | string \| number | 内部计算出的节点位置 | |
| selectable | 设置节点是否可被选中 | boolean | true | |
| title | 标题 | string\|slot\|slot-scope | '---' | |
| slots | 使用 treeNodes 时，可以通过该属性配置支持 slot 的属性，如 `slots: { title: 'XXX'}` | object | - | |
| title | 标题 | string | '---' | |
### DirectoryTree props

10
site/src/router/index.js
View File

@ -88,6 +88,16 @@ const routes = [
meta: { enTitle: 'V1 to V2', title: '从 v1 到 v2', category: 'docs' },
component: () => import('../vueDocs/migration-v2.en-US.md'),
},
{
path: 'vue/migration-v3-cn',
meta: { enTitle: 'V2 to V3', title: '从 v2 到 v3', category: 'docs' },
component: () => import('../vueDocs/migration-v3.zh-CN.md'),
},
{
path: 'vue/migration-v3',
meta: { enTitle: 'V2 to V3', title: '从 v2 到 v3', category: 'docs' },
component: () => import('../vueDocs/migration-v3.en-US.md'),
},
{
path: 'vue/replace-date-cn',
meta: { enTitle: 'Custom Date Library', title: '自定义时间库', category: 'docs' },

128
site/src/vueDocs/migration-v3.en-US.md Normal file
View File

@ -0,0 +1,128 @@
This document will help you upgrade from ant-design-vue `2.x` version to ant-design-vue `3.x` version.
The 2.x version is a compatible version developed for compatibility with Vue 3. It does not bring many new features, and most of the API changes are only for better compatibility with Vue 3. The 3.x version has greatly improved performance, ease of use, and functions. After the 3.x version is stable, we will archive the 2.x version. It is recommended that you upgrade to the 3.x version as soon as possible. Although there are many changes, they are basically compatible. You can upgrade gradually according to the warnings given by the console.
## Upgrade preparation
1. Please upgrade to the latest version of 2.x first, and remove/modify related APIs according to the warning information on the console. It is recommended to check the historical Change Log of 2.x first, which will not be detailed here.
2. Upgrade the project to Vue 3.2 and above.
## 3.0 What are the incompatible changes
### Design specification adjustment
- The font color is changed from `rgba(0, 0, 0, 0.65)` to `rgba(0, 0, 0, 0.85)`.
- The selected color of some components is uniformly changed to `@blue-1: #E6F7FF`, and the corresponding color of `hover` is changed to `@gray-2: #FAFAFA`.
- Error color value adjustment, changed from `@red-5: #F5222D` to `@red-5: #FF4D4F`.
- DatePicker interactive redo, the panel and the input box are separated, the range selection can now select the start and end time separately.
#### Removed API
- Removed the `lazy` attribute of Transfer, it does not have a real optimization effect.
- Removed the `combobox` mode of Select, please use `AutoComplete` instead.
- Deprecated Button.Group, please use `Space` instead.
- `DatePicker` `TimePicker` `Calendar` remove momentjs, please use momentjs instead
- `Tree`, `TreeSlelct`
- Deprecated the use of `a-tree-node` and `a-tree-select-node` to construct nodes, use the `treeData` property instead
- Deprecated `scopedSlots` `slots` custom rendering node, use `v-slot:title` instead
- `Table`
- Removed the `rowSelection.hideDefaultSelections` property of Table, please use `SELECTION_ALL` and `SELECTION_INVERT` in `rowSelection.selections` instead, [custom options](/components/table/#components-table-demo- row-selection-custom).
- Removed Column slots and replaced them with `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon`
#### Component refactoring
In order to make the components have better performance and maintainability, we have used TS + Composition Api to refactor almost all components. There are still very few components that have not been refactored. Such components will be refactored gradually in the future, and the rest There will be no destructive updates to the components, so there is no need to worry about future upgrade costs.
Major updates after the 3.0 version refactoring include `Tree` `TreeSlelct` `DatePicker` `TimePicker` `Calendar` `Form` `Table`, other components also have corresponding function updates, you can check ChangeLog for further details
- `Tree` `TreeSlelct`
- Added virtual scrolling, discarded using `a-tree-node` `a-tree-select-node` to build nodes, using `treeData` property instead to improve component performance
- Deprecated `scopedSlots` `slots` custom rendering node, and replace it with `v-slot:title` to improve ease of use, avoid slot configuration expansion, and also avoid slot conflicts
- `Table`
- Removed the `rowSelection.hideDefaultSelections` property of Table, please use `SELECTION_ALL` and `SELECTION_INVERT` in `rowSelection.selections` instead, [custom options](/components/table/#components-table-demo- row-selection-custom).
- Removed Column slots and replaced them with `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon` to improve ease of use , To avoid slot configuration expansion, but also to avoid the problem of slot conflicts
- Added expandFixed to control whether the expanded icon is fixed
- Added the showSorterTooltip header whether to display the tooltip for the next sort.
- Added sticky for setting sticky head and scroll bar
- Added rowExpandable to set whether to allow row expansion
- New slot headerCell is used to personalize the header cell
- Added slot bodyCell for personalized cell
- New slot customFilterDropdown is used to customize the filter menu, which needs to be used with `column.customFilterDropdown`
- Added slot customFilterIcon for custom filter icons
- New slot emptyText is used to customize the display content of empty data
- Added slot summary for the summary column
- `DatePicker` `TimePicker` `Calendar`
- By default, a more lightweight dayjs is used to replace momentjs. If your project is too large and uses a lot of momentjs methods, you can refer to the document [Custom Time Library](/docs/vue/replace-date-cn), Replace with momentjs.
- UI interaction adjustment, its antd 4.x interaction specification
- `Form` The main goal of this update is to improve performance. If you don't have custom form controls, you can almost ignore this part
- Since version 3.0, Form.Item no longer hijacks child elements, but automatically checks through provider/inject dependency injection. This method can improve component performance, and there is no limit to the number of child elements. The same is true for child elements. It can be a high-level component that is further encapsulated.
You can reference [Customized Form Controls](#components-form-demo-customized-form-controls)
But it also has some disadvantages:
1. If the custom component wants Form.Item to be verified and displayed, you need to inject `const {id, onFieldChange, onFieldBlur} = useFormItemContext()` and call the corresponding method.
2. A Form.Item can only collect the data of one form item. If there are multiple form items, it will cause collection confusion, for example,
```html
<a-form-item>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</a-form-item>
```
As above Form.Item does not know whether to collect `name="a"` or `name=`b``, you can solve this kind of problem in the following two ways:
The first is to use multiple `a-form-item`:
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item><a-input name="b"></a-input></a-form-item>
</a-form-item>
```
The second way is to wrap it with a custom component and call `useFormItemContext` in the custom component, It is equivalent to merging multiple form items into one.
```html
<script>
// custom component
import { Form } from 'ant-desing-vue';
export default {
name: 'custom-name',
setup() {
const formItemContext = Form.useFormItemContext();
},
};
</script>
```
```html
<a-form-item>
<custom-com>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</custom-com>
</a-form-item>
```
Third, the component library provides an `a-form-item-rest` component, which will prevent data collection. You can put form items that do not need to be collected and verified into this component. It is the same as the first This method is very similar, but it does not generate additional dom nodes.
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item-rest><a-input name="b"></a-input></a-form-item-rest>
</a-form-item>
```
## Encounter problems
V3 has made a lot of detailed improvements and refactorings. We have collected all known incompatible changes and related effects as much as possible, but there may still be some scenarios that we have not considered. If you encounter problems during the upgrade process, please go to [GitHub issues](https://vuecomponent.github.io/issue-helper/) for feedback. We will respond as soon as possible and improve this document accordingly.

126
site/src/vueDocs/migration-v3.zh-CN.md Normal file
View File

@ -0,0 +1,126 @@
本文档将帮助你从 ant-design-vue `2.x` 版本升级到 ant-design-vue `3.x` 版本。
2.x 版本是为了兼容 Vue 3 开发的兼容版本，他并没有带来很多新的特性，大多数的 API 改变也只是为了更好的兼容 Vue 3。 3.x 版本在性能、易用性、功能上都有了很大的提升，3.x 版本稳定后，我们会归档 2.x 版本，建议您尽快升级 3.x 版本。虽然有很多改动，但基本都做了兼容，你可以按照控制台给出的警告逐步升级。
## 升级准备
1. 请先升级到 2.x 的最新版本，按照控制台 warning 信息移除/修改相关的 API，建议优先查看 2.x 的历史 Change Log，在这里就不再详述。
2. 升级项目 Vue 3.2 以上。
3. 您和 3.0 只有这份文档的距离，相信我，今日加的班，是为了明天摸更多的鱼。
## 3.0 有哪些不兼容的变化
### 设计规范调整
- 字体颜色从 `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 交互重做，面板和输入框分离，范围选择现可单独选择开始和结束时间。
#### 移除的 API
- 移除了 Transfer 的 `lazy` 属性，它并没有起到真正的优化效果。
- 移除了 Select 的 `combobox` 模式，请使用 `AutoComplete` 替代。
- 废弃 Button.Group，请使用 `Space` 代替。
- `DatePicker` `TimePicker` `Calendar` 移除 momentjs，请使用 momentjs 替换
- `Tree`、`TreeSlelct`
- 废弃使用 `a-tree-node` `a-tree-select-node` 构建节点，使用 `treeData` 属性替代
- 废弃 `scopedSlots` `slots` 自定义渲染节点，使用 `v-slot:title` 替换
- `Table`
- 移除了 Table 的 `rowSelection.hideDefaultSelections` 属性，请在 `rowSelection.selections` 中使用 `SELECTION_ALL` 和 `SELECTION_INVERT` 替代，[自定义选择项](/components/table/#components-table-demo-row-selection-custom)。
- 移除了 Column slots，分别使用 `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon` 替换
#### 组件重构
为了让组件拥有更好的性能和可维护性，我们几乎使用 TS + Composition Api 重构了所有组件，目前还有极个别的组件没有重构，这类组件会在接下来逐步重构，剩余的组件不会有破坏性更新，所以不用担心未来的升级成本。
3.0 版本重构后较大的更新有 `Tree` `TreeSlelct` `DatePicker` `TimePicker` `Calendar` `Form` `Table`，其它组件也有相应功能的更新，你可以查看 ChangeLog 进一步了解详情
- `Tree` `TreeSlelct`
- 新增了虚拟滚动，废弃使用 `a-tree-node` `a-tree-select-node` 构建节点，使用 `treeData` 属性替代，提升组件性能
- 废弃 `scopedSlots` `slots` 自定义渲染节点，使用 `v-slot:title` 替换，提升易用性，避免插槽配置膨胀，同时也避免了插槽冲突问题
- `Table`
- 移除了 Table 的 `rowSelection.hideDefaultSelections` 属性，请在 `rowSelection.selections` 中使用 `SELECTION_ALL` 和 `SELECTION_INVERT` 替代，[自定义选择项](/components/table/#components-table-demo-row-selection-custom)。
- 移除了 Column slots，分别使用 `v-slot:headerCell` `v-slot:headerCell` `v-slot:bodyCell` `v-slot:customFilterDropdown` `v-slot:customFilterIcon` 替换，提升易用性，避免插槽配置膨胀，同时也避免了插槽冲突问题
- 新增 expandFixed 控制展开图标是否固定
- 新增 showSorterTooltip 表头是否显示下一次排序的 tooltip 提示。
- 新增 sticky 用于设置粘性头部和滚动条
- 新增 rowExpandable 用于设置是否允许行展开
- 新增插槽 headerCell 用于个性化头部单元格
- 新增插槽 bodyCell 用于个性化单元格
- 新增插槽 customFilterDropdown 用于自定义筛选菜单，需要配合 `column.customFilterDropdown` 使用
- 新增插槽 customFilterIcon 用于自定义筛选图标
- 新增插槽 emptyText 用于自定义空数据时的显示内容
- 新增插槽 summary 用于总结栏
- `DatePicker` `TimePicker` `Calendar`
- 默认使用更加轻量级的 dayjs 替换 momentjs，如果你的项目过大，使用了大量的 momentjs 的方法，你可以参考文档[自定义时间库](/docs/vue/replace-date-cn)，替换成 momentjs。
- UI 交互调整，对其 antd 4.x 交互规范
- `Form` 这次更新主要目标是提升性能，如果你没有自定义表单控件，几乎可以忽略该部分
- 自 3.0 版本以后，Form.Item 不再劫持子元素，而是通过 provider / inject 依赖注入的方式进行自动校验，这种方式可以提高组件性能，子元素也不会限制个数，同样子元素也可以是进一步封装的高级组件。你可以参考[自定义表单控件示例](#components-form-demo-customized-form-controls)
但它同样会有一些缺点：
1、自定义组件如果希望 Form.Item 进行校验展示，你需要 `const {id, onFieldChange, onFieldBlur} = useFormItemContext()` 注入，并调用相应的方法。
2、一个 Form.Item 只能收集一个表单项的数据，如果有多个表单项，会导致收集错乱，例如，
```html
<a-form-item>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</a-form-item>
```
如上 Form.Item 并不知道需要收集 `name="a"` 还是 `name=`b``，你可以通过如下三种方式去解决此类问题：
第一种，使用多个 `a-form-item`:
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item><a-input name="b"></a-input></a-form-item>
</a-form-item>
```
第二种，使用自定义组件包裹，并在自定义组件中调用 `useFormItemContext`，相当于把多个表单项合并成了一个
```html
<script>
// 自定义组件
import { Form } from 'ant-desing-vue';
export default {
setup() {
const formItemContext = Form.useFormItemContext();
},
};
</script>
```
```html
<a-form-item>
<custom-com>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</custom-com>
</a-form-item>
```
第三种，组件库提供了一个 `a-form-item-rest` 组件，它会阻止数据的收集，你可以将不需要收集校验的表单项放到这个组件中即可，它和第一种方式很类似，但它不会产生额外的 dom 节点。
```html
<a-form-item>
<a-input name="a"></a-input>
<a-form-item-rest><a-input name="b"></a-input></a-form-item-rest>
</a-form-item>
```
## 遇到问题
v3 做了非常多的细节改进和重构，我们尽可能收集了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，请到 [GitHub issues](https://vuecomponent.github.io/issue-helper/) 进行反馈。我们会尽快响应和相应改进这篇文档。