|
1 | | -# Upgrading from v2 to v3 |
| 1 | +# Upgrade from v2 to v3. |
2 | 2 |
|
3 | | -This document will help you upgrade from NutUI React `2.x` to NutUI React `3.x` version. |
| 3 | +This document will assist you in upgrading from NutUI React 2.x to NutUI React 3.x. |
4 | 4 |
|
5 | 5 | ## Upgrade Steps |
6 | 6 |
|
7 | | -1. H5 Install NutUI React version 3.x |
| 7 | +1. H5 Installation of NutUI React 3.x Version |
8 | 8 |
|
9 | 9 | ```shell |
10 | 10 | npm install @nutui/nutui-react |
11 | 11 | ``` |
12 | 12 |
|
13 | | -2. Taro installs NutUI React version 3.x |
| 13 | +2. Taro Installation of NutUI React 3.x Version |
14 | 14 |
|
15 | 15 | ```shell |
16 | 16 | npm install @nutui/nutui-react-taro |
17 | 17 | ``` |
18 | 18 |
|
19 | | -3. Handling incompatible updates |
| 19 | +3. Handling Incompatible Updates |
20 | 20 |
|
21 | | -There are some incompatible updates from NutUI React 1.x to NutUI React 2.x. You need to read the incompatible updates carefully and deal with them in turn. |
| 21 | +There are some incompatible updates from NutUI React 2.x to NutUI React 3.x. It is essential to carefully read the details of the incompatible updates and address them sequentially. |
22 | 22 |
|
23 | | -You can manually check your code against the list below to make changes, or we provide a codemod cli tool @nutui/nutui-react-codemod to help you upgrade to v2 quickly. Please commit your local code changes before running codemod cli. |
| 23 | +4. Theme variable renaming: |
24 | 24 |
|
25 | | -4. Theme variables are renamed: |
26 | | - For example, primary-color is renamed to color-primary; note that if you are using a custom theme, especially if you are using the ConfigProvider component, you are not using `nutuiBrandColor`, remember to rename it to `nutuiColorPrimary`. |
| 25 | +## Compatible updates |
27 | 26 |
|
28 | | -## Compatibility Updates |
| 27 | +1. Component Style Handling |
29 | 28 |
|
30 | | -1. Component style handling |
31 | | - |
32 | | -Added support for importing css files on demand, while retaining the ability to import scss files on demand. On-demand css import can be realized by babel-import-plugin plugin: |
| 29 | +Support for on-demand importing of CSS files has been added, while retaining the ability to import SCSS files on demand. On-demand CSS importing can be achieved using the babel-import-plugin: |
33 | 30 |
|
34 | 31 | The H5 configuration is as follows: |
35 | 32 |
|
36 | | -```js |
37 | | -// Webpack .babelrc or babel.config.js configuration |
| 33 | +```json |
| 34 | +// Webpack .babelrc or babel.config.js |
38 | 35 | plugins: [ |
39 | 36 | [ |
40 | | - “import”. |
| 37 | + "import", |
41 | 38 | { |
42 | | - libraryName: “@nutui/nutui-react”, libraryDirectory: “dist/esm”, { |
43 | | - libraryDirectory: “dist/esm”, { |
| 39 | + libraryName: "@nutui/nutui-react", |
| 40 | + libraryDirectory: "dist/esm", |
44 | 41 | style: 'css', |
45 | 42 | camel2DashComponentName: false, |
46 | | - }. |
47 | | - “nutui-react”. |
| 43 | + "customName": (name, file) => { |
| 44 | + return `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}` |
| 45 | + } |
| 46 | + }, |
| 47 | + "nutui-react", |
48 | 48 | ] |
49 | 49 | ] |
50 | 50 | ``` |
51 | 51 |
|
52 | | -Taro is configured as follows: |
| 52 | +Taro config： |
53 | 53 |
|
54 | 54 | ```json |
55 | | -// Configured in Webpack .babelrc or babel.config.js |
| 55 | +// Webpack .babelrc or babel.config.js |
56 | 56 | plugins: [ |
57 | 57 | [ |
58 | | - “import”. |
| 58 | + "import", |
59 | 59 | { |
60 | | - libraryName: “@nutui/nutui-react-taro”, libraryDirectory: “dist/esm”, { |
61 | | - libraryDirectory: “dist/esm”, { |
| 60 | + libraryName: "@nutui/nutui-react-taro", |
| 61 | + libraryDirectory: "dist/esm", |
62 | 62 | style: 'css', |
63 | 63 | camel2DashComponentName: false, |
64 | | - }. |
65 | | - “nutui-react-taro”. |
| 64 | + "customName": (name, file) => { |
| 65 | + return `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}` |
| 66 | + } |
| 67 | + }, |
| 68 | + "nutui-react-taro", |
66 | 69 | ] |
67 | 70 | ] |
68 | 71 | ``` |
69 | 72 |
|
70 | | -2. better type exporting and adding `JSDoc` annotations to types |
71 | | -3. Adjustment of component categorization |
72 | | - In terms of component classification, we have reviewed the 1.x classification based on the information structure from the interaction dimension, together with the interaction design side, and subclassed and reclassified them, with the goal of more closely matching the distribution of interaction scenarios and making it easy to find components. The main distribution is: |
| 73 | +## New Components |
| 74 | + |
| 75 | +- SideBar |
| 76 | +- PickerView |
| 77 | + |
| 78 | +## Incompatible Updates |
| 79 | + |
| 80 | +If your project uses these components, please read the documentation carefully and proceed with the upgrade. |
| 81 | + |
| 82 | +## Component API Adjustments |
| 83 | + |
| 84 | +### Basic |
| 85 | + |
| 86 | +#### Button |
| 87 | + |
| 88 | +- Removed style variable `--nutui-button-default-font-weight` |
| 89 | + |
| 90 | +[//]: # '#### Cell' |
| 91 | +[//]: # '#### CellGroup' |
| 92 | +[//]: # '#### ConfigProvider' |
| 93 | +[//]: # '#### Icon' |
| 94 | +[//]: # '#### Image' |
| 95 | +[//]: # '#### Overlay' |
| 96 | +[//]: # '#### Popup' |
| 97 | + |
| 98 | +### Layout |
| 99 | + |
| 100 | +[//]: # '#### Divider' |
| 101 | + |
| 102 | +#### Grid |
| 103 | + |
| 104 | +- The default value of the square attribute has been adjusted to true. |
| 105 | +- Added new theme variables. |
| 106 | + - `--nutui-grid-border-width` Control border width. |
| 107 | + - `--nutui-grid-border-radius` Control corner radius. |
| 108 | + - |
| 109 | + |
| 110 | +[//]: # '#### Layout' |
| 111 | +[//]: # '#### Sticky' |
| 112 | + |
| 113 | +### Navigation |
| 114 | + |
| 115 | +[//]: # '#### Elevator' |
| 116 | +[//]: # '#### FixedNav' |
| 117 | + |
| 118 | +#### Indicator |
| 119 | + |
| 120 | +- Added a new type attribute with optional values of 'anchor' or 'slide', defaulting to anchor. |
| 121 | +- Added a new color attribute with optional values of primary or 'white', defaulting to primary. |
| 122 | +- The default value of the total attribute has been adjusted to 2. |
| 123 | + |
| 124 | +[//]: # '#### Menu' |
| 125 | + |
| 126 | +#### NavBar |
| 127 | + |
| 128 | +- Removed the titleAlign attribute; it can be replaced with title and children. |
| 129 | +- Added a title attribute, which is displayed centered by default. |
| 130 | +- If children is present in the component, it will adopt the left alignment layout specified by titleAlign. |
| 131 | + |
| 132 | +#### Pagination |
| 133 | + |
| 134 | +- The type of the itemRender attribute has been adjusted to: (page: any, index: number) => ReactNode. |
| 135 | + |
| 136 | +#### SideNavBar |
| 137 | + |
| 138 | +- Note: This component does not comply with mobile standards and has been deprecated. Please use SideBar instead. |
| 139 | + |
| 140 | +[//]: # '#### Tabbar' |
| 141 | +[//]: # '#### TabbarItem' |
| 142 | +[//]: # '#### Tabs' |
| 143 | +[//]: # '#### Tabs.Tabpane' |
| 144 | + |
| 145 | +### Data |
| 146 | + |
| 147 | +[//]: # '#### Calendar' |
| 148 | +[//]: # '#### Cascader' |
| 149 | +[//]: # '#### Checkbox' |
| 150 | +[//]: # '#### Checkbox.Group' |
| 151 | +[//]: # '#### DatePicker' |
| 152 | +[//]: # '#### Form' |
| 153 | +[//]: # '#### Form.Item' |
| 154 | +[//]: # '#### Input' |
| 155 | +[//]: # '#### InputNumber' |
| 156 | +[//]: # '#### NumberKeyboard' |
| 157 | +[//]: # '#### Picker' |
| 158 | +[//]: # '#### Radio' |
| 159 | +[//]: # '### Radio.Group' |
| 160 | +[//]: # '#### Range' |
| 161 | + |
| 162 | +#### Rate |
| 163 | + |
| 164 | +- Added a size attribute to control the size of the icon. |
| 165 | +- Added a showScore attribute to display the rating text. |
| 166 | + |
| 167 | +[//]: # '#### SearchBar' |
| 168 | +[//]: # '#### ShortPassword' |
| 169 | + |
| 170 | +#### TextArea |
| 171 | + |
| 172 | +- Added a plain attribute to mark it as a plain text type. The default value is false, indicating it is a container type. |
| 173 | +- Added a status attribute, with possible values of default | error, to define the state of the input box. |
| 174 | +- Removed some basic style variables and recommended using foundational style variables, such as $textarea-font, $textarea-limit-color, and $textarea-disabled-color. |
| 175 | + |
| 176 | +#### Uploader |
| 177 | + |
| 178 | +- Removed internal handling of AJAX-related network logic in the component. |
| 179 | +- Removed network configuration-related props: url, headers, data, xhrState, withCredentials, and timeout. |
| 180 | +- Removed trigger functions related props: onStart, onProgress, onFailure, and beforeXhrUpload. |
| 181 | +- Added the onOverCount attribute to trigger when the file count exceeds the limit. |
| 182 | +- Added the onUploadQueueChange attribute to trigger when the image upload queue changes. |
| 183 | +- Simplified the use of the FileItem type, making all attributes optional except for url. |
| 184 | +- Adjusted the default value of the maxCount attribute in multi-select mode to Number.MAX_VALUE. |
| 185 | +- Introduced a new upload method. |
| 186 | +- Changed the types of defaultValue and value from FileType to FileItem. |
| 187 | + |
| 188 | +### Feedback |
| 189 | + |
| 190 | +[//]: # '#### ActionSheet' |
| 191 | + |
| 192 | +#### BackTop |
| 193 | + |
| 194 | +- Taro |
| 195 | + - Provided HarmonyOS capabilities by adding the scrollRes attribute. |
| 196 | + |
| 197 | +#### Dialog |
| 198 | + |
| 199 | +- Modified the layout style of the operation buttons to have a vertical arrangement. |
| 200 | +- When there is only one main action button, its style expands to fill the available space. |
| 201 | +- Added style variables for setting the size of bottom icons; changed the default value of the right-side button to 16 px. |
| 202 | + |
| 203 | +[//]: # '#### Drag' |
| 204 | + |
| 205 | +#### InfiniteLoading |
| 206 | + |
| 207 | +- The target attribute is used to obtain the element that is being listened to. |
| 208 | + |
| 209 | +[//]: # '#### Notify' |
| 210 | +[//]: # '#### PullToRefresh' |
| 211 | +[//]: # '#### Swipe' |
| 212 | + |
| 213 | +#### Switch |
| 214 | + |
| 215 | +- Changed the type of the activeText attribute to ReactNode. |
| 216 | +- Changed the type of the inactiveText attribute to ReactNode. |
| 217 | + |
| 218 | +[//]: # '#### Toast' |
| 219 | + |
| 220 | +[//]: ### 展示组件 |
| 221 | + |
| 222 | +[//]: # '#### Animate' |
| 223 | +[//]: # '#### AnimatingNumbers' |
| 224 | + |
| 225 | +#### Audio |
| 226 | + |
| 227 | +- Note: This component is not planned to be supported on Taro multi-end. Please use the API instead. |
| 228 | + |
| 229 | +[//]: # '#### Avatar' |
| 230 | +[//]: # '#### AvatarGroup' |
| 231 | + |
| 232 | +#### Badge |
| 233 | + |
| 234 | +- Added a new size attribute for the dot size, which takes effect when dot is set to true. |
| 235 | +- Removed the color attribute (badge background color) and implemented it using the CSS variable --nutui-badge-background-color. |
| 236 | + |
| 237 | +[//]: # '#### CircleProgress' |
| 238 | +[//]: # '#### Collapse' |
| 239 | +[//]: # '#### CollapseItem' |
| 240 | + |
| 241 | +#### CountDown |
| 242 | + |
| 243 | +- Added a new type attribute to set the variant type. |
| 244 | + |
| 245 | +[//]: # '#### Ellipsis' |
| 246 | + |
| 247 | +#### Empty |
| 248 | + |
| 249 | +- Removed the theme variable --nutui-empty-title-margin-top. |
| 250 | +- Removed the theme variable --nutui-empty-description-margin-top. |
| 251 | + |
| 252 | +[//]: # '#### ImagePreview' |
| 253 | +[//]: # '#### NoticeBar' |
| 254 | +[//]: # '#### Popover' |
| 255 | + |
| 256 | +#### Price |
73 | 257 |
|
74 | | -- Basic components, remove the `Popup` component, and subdivide `Popup` into operation feedback-guidance tips section; |
75 | | -- Layout components, remain unchanged; |
76 | | -- Navigation components: move `Pagination` and `Indicator` to the display component (considering the light operation of paging on mobile); move `Menu` menu to the data entry class-selector subclass (considering the light operation of paging on mobile); move `Menu` to the data entry class-selector subclass (considering the light operation of paging on mobile). |
| 258 | +- Modified the size attribute to include an 'xlarge' option. |
| 259 | +- Added a new color attribute for price types. |
77 | 260 |
|
78 | | -Translated with DeepL.com (free version) |
| 261 | +[//]: # '#### Progress' |
| 262 | +[//]: # '#### Skeleton' |
| 263 | +[//]: # '#### Steps' |
| 264 | +[//]: # '#### Step' |
| 265 | +[//]: # '#### Swiper' |
| 266 | +[//]: # '#### Table' |
| 267 | +[//]: # '#### Tag' |
| 268 | +[//]: # '#### TrendArrow' |
| 269 | +[//]: # '#### Video' |
| 270 | +[//]: # '#### VirtualList' |
| 271 | +[//]: # '#### WaterMark' |
| 272 | +[//]: # '### 特色组件' |
| 273 | +[//]: # '#### Address' |
| 274 | +[//]: # '#### Barrage' |
| 275 | +[//]: # '#### Card' |
| 276 | +[//]: # '#### Signature' |
| 277 | +[//]: # '#### TimeSelect' |
0 commit comments