Skip to content

Latest commit

 

History

History
132 lines (97 loc) · 8.1 KB

migration-v3.en-US.md

File metadata and controls

132 lines (97 loc) · 8.1 KB

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 ChangeLog 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 dayjs instead.
  • Tree, TreeSelect
    • 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.
    • Deprecated replaceFields, use fieldNames 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: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 TreeSelect DatePicker TimePicker Calendar Form Table, other components also have corresponding function updates, you can check ChangeLog for further details.

  • Tree TreeSelect

    • 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.

  • AutoComplete

    • no longer support optionLabelProp. Please set Option value directly.
    • options definition align with Select. Please use options instead of dataSource.

  • 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: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, Replace with momentjs.
    • UI interaction adjustment, align with antd 4.x interaction specifications.

  • 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, 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} = useInjectFormItemContext() 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:

      <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:

      <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 useInjectFormItemContext in the custom component, It is equivalent to merging multiple form items into one.

      <script>
  // custom component
  import { Form } from 'ant-design-vue';
  export default {
    name: 'custom-name',
    setup() {
      const formItemContext = Form.useInjectFormItemContext();
    },
  };
</script>
      <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.

      <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 for feedback. We will respond as soon as possible and improve this document accordingly.