Skip to content

Latest commit

 

History

History
888 lines (688 loc) · 37.3 KB

migrate-from-v1.md

File metadata and controls

888 lines (688 loc) · 37.3 KB

从 v1 升级到 v2

本文档将帮助您从 NutUI React 1.x 升级到 NutUI React 2.x 版本。

升级步骤

  1. H5 安装 NutUI React 2.x 版本
npm install @nutui/nutui-react
  1. Taro 安装 NutUI React 2.x 版本
npm install @nutui/nutui-react-taro
  1. 处理不兼容更新

从 NutUI React 1.x 到 NutUI React 2.x 存在一些不兼容更新,需要仔细阅读不兼容更新内容,并依次处理。

你可以手动对照下面的列表逐条检查代码进行修改,另外,我们也提供了一个 codemod cli 工具 @nutui/nutui-react-codemod 以帮助你快速升级到 v2 版本。在运行 codemod cli 前,请先提交你的本地代码修改。

  1. 主题变量更名: 如,primary-color 更名为 color-primary;注意在使用自定义主题,特别是使用 ConfigProvider 组件的情况下,有没有使用 nutuiBrandColor,这时记得更名为 nutuiColorPrimary

兼容更新

  1. 组件样式处理

新增了按需引入 css 文件的支持,同时保留了按需引入 scss 文件的能力。可通过 babel-import-plugin 插件实现按需引入 css:

H5配置如下:

// Webpack .babelrc 或 babel.config.js中配置
plugins: [
  [
    "import",
    {
      libraryName: "@nutui/nutui-react",
      libraryDirectory: "dist/esm",
      style: 'css',
      camel2DashComponentName: false,
    },
    "nutui-react",
  ]
]

Taro配置如下:

// Webpack .babelrc 或 babel.config.js中配置
plugins: [
  [
    "import",
    {
      libraryName: "@nutui/nutui-react-taro",
      libraryDirectory: "dist/esm",
      style: 'css',
      camel2DashComponentName: false,
    },
    "nutui-react-taro",
  ]
]
  1. 更完善的类型导出以及对类型增加 JSDoc 注释
  2. 组件分类的调整 在组件分类上,我们从交互维度上,和交互设计侧共同对 1.x 分类进行了基于信息结构的评审,并进行了子类梳理,完成重新分类,目标是更贴合交互场景的分布,易于查找组件。主要分布在:
  • 基础组件,将 Popup 组件移除,将 Popup 细分到操作反馈-引导提示部分;
  • 布局组件,保持不变;
  • 导航组件:将分页相关组件 PaginationIndicator 移动到展示组件(考虑移动端的分页轻操作);Menu 菜单移动到数据录入类-选择器子类(考虑 Menu 主要是作为筛选器);将 BackTop 移至导航组件,作为锚点组件的一部分;
  • 展示组件:将 BadgeNoticeBarPopover 移至操作反馈-引导提示类,EmptySkeleton 移至操作反馈-加载状态结果反馈中;WaterMarkTrendArrow 作为特性增强类组件放在特色组件中,待由该类组件的使用场景和范围确认是否变更分类;同时新增 Audio,将其同 VideoImagePreviewSwiper 一同归为展示-多媒体类;
  • 操作反馈类,新增 SkeletonEmpty(加载结果反馈类),PopoverNotifyNoticeBarPopup (引导提示类)6个组件;同时去除 BackTop(导航组件-锚点类)、Switch(数据录入-选择器)、Audio``(展示-多媒体);在此基础上,未来会考虑增加 ResultPage,整合错误状态、空状态等反馈状态,该组件在考虑中;同时考虑增加加载状态 Loading 组件。版本待定。
  • 数据录入类,主要分为两大类-输入及选择器。在输入中增加 Signature,该组件在 Form 表单中的应用范围日渐广泛,从特色组件中移入到数据录入部分;选择器中增加 SwitchMenu,及 Address。其中 SignatureAddress 都是考虑其常用性,从特色中迁移到数据录入部分。
  • 特色组件,保留 BarrageCardTimeSelect,新增 WaterMarkTrendArrow

不兼容更新

NutUI Icons 调整

1.x 版本我们在实际开发过程中会发现 Button 只是引用了一个很小的 Loading Icon,但是全量引用了 IconFont 字体 ,会导致开发者的项目文件增大。我们在 NutUI React 2.x 中为解决此问题,重新定义了 Icon 组件,将所有的 Icons 抽离成单独的图标组件库 @nutui/icons-react(Taro 适配下为 @nutui/icons-react-taro) ,使其可以进行按需加载使用。 因此一些组件之前关于 Icon 的相关 Props 将被移除,需要使用插槽或者传递一个 Component 组件的 Props 进行使用。 受影响的组件如下:

  • Avatar
  • Button
  • ImagePreview
  • Collapse
  • InfiniteLoading
  • Popup
  • Steps
  • Switch
  • Toast
  • Progress
  • NoticeBar
  • SearchBar
  • Navbar
  • Menu
  • Tabbar
  • Checkbox
  • InputNumber
  • Input
  • Radio
  • Rate
  • Uploader
  • Popover
  • Grid
  • TrendArrow

如果你的项目中使用了这些组件,请仔细阅读文档并进行升级。

组件名称调整

  • GridItem -> Grid.Item
  • TabbarItem -> Tabbar.Item
  • CollapseItem -> Collapse.Item
  • SwiperItem -> Swiper.Item
  • CellGroup -> Cell.Group
  • MenuItem -> Menu.Item
  • Infiniteloading -> InfiniteLoading

组件 API 调整

在 2.0 版本中,我们重点对组件 API 进行了评审和修订,使属性和方法命名更贴合常用的命名习惯及 React 语言规范,目标希望开发者在使用组件时得心应手。我们的思路大体如下:

属性定义

本次升级重点关注属性的命名方面,从 1.x 的 610 个属性精简为 410 个,更精简、更规范;同时增强属性的类型范围,提升自定义能力。

  • 对同一属性进行统一描述,比如:
    • 缩写类会改为全拼,如 descdescSlotdescription 统一为 description
    • 能使用名词或形容词的优先使用该类词性,一个词能说明白的不用两个词。
      • wrapwrapable 统一为 wrap
      • 如将 isXxx 统一为 xxx,如 isVisibleisDeletable 等,可直接使用 visibledeletable 等,形容词化
      • showXxx 尽量统一为 xxx,名词化。【部分属性待优化。】
      • roundRadius 改为 radiuscolumnNum 改为 columns
    • onClickXxx 统一为 onXxxClick
    • modelValue 统一为 value,并增加支持 defaultValue,支持受控与非受控模式
    • 对于标识位置、对齐等类的属性,将属性名变更为其上一层的属性定义,如 center会改为 alignvertical,改为 direction,像标记距离的,如 topbottomdistance 等,会改为 threshold
    • 不规范的定义如 okBtnokText 这种,会改为 confirmXxx
  • 扩充属性的类型。如 title 的类型从 string 扩充为 React.ReactNode,增强自定义内容;其中有涉及合并属性的,统一用最简命名来定义属性;如 titletitleSlot 合并为 title,再扩充属性类型。
  • 对于 xxClassxxStyle类的属性,移除,可使用 classNamestyle 来实现。
  • 移除与样式有关的属性,除基础组件的样式属性及部分实现起来较为复杂的样式属性外,大多数样式属性被移除,可通过样式变量来实现。
  • 将普遍认同可内置的属性或不怎么使用的属性,直接内置,去掉属性设置。

组件实现

基础组件

Button

  • 移除 plain,通过 fill="outline" 实现
  • 增加 ref,对外暴露组件内 button 元素
  • CSS 变量中,对 type 类型对应的色值的定义,不在暴露到文档中,建议使用默认值,或修改主题变量
  • 增加 fill 模式类型,dashed,修改 fill 默认值为 outline
  • 增加 rightIcon,可满足同时设置左右两个icon的情况。
  • 修改 sizelarge 时的默认 width100% 的值,如果使用通栏的 button,可搭配 block 来使用。

Cell

  • subTitle 重命名为 description,类型修改为 React.Node
  • desc 重命名为 extra,类型修改为 React.Node
  • roundRadius 重命名为 radius
  • center 重命名为 align,默认值修改为flex-start,可选值为 flex-startcenterflex-end
  • 移除 iconisLinkurllinkSlotreplacedescTextAlign,通过用户自定义节点实现,参考文档demo示例

CellGroup

  • 新增 divider,单元格之间是否有分割线
  • desc 重命名为 description
  • titledescription 类型修改为 React.Node
  • 移除 titleSlotdescSlot,通过 titledescription 实现

ConfigProvider

Icon

Image

  • 移除 round,通过 radius 实现圆或圆角
  • 移除 loadingImgslotLoading,通过 loading 属性实现,当 loading 属性设置为 ReactNodetrue 时,表示展示 loading 状态
  • 移除 showErrorslotError,通过 error 属性实现,当 error 属性设置为 ReactNodetrue 时,表示展示 error 状态
  • 移除 loadingImg,可通过 loading 设置 ReactNode
  • 移除 errorImg,可通过 error 设置 ReactNode
  • showError 重命名为 error,类型修改为 boolean|ReactNode
  • showLoading 重命名为 loading,类型修改为 boolean|ReactNode

Overlay

  • overlayClass 重命名为 className
  • overlayStyle 重命名为 style
  • closeOnClickOverlay 重命名为 closeOnOverlayClick
  • 更改 lockScroll 默认值为 true
  • 新增 afterCloseafterShow,用于完全关闭后触发的回调和完全展示后触发的回调

Popup

  • popClass 重命名为 className,统一将组件的样式类名使用 className,不再指定特殊名字,减轻用户使用的记忆成本
  • overlayClass 重命名为 overlayClassName,继承自Overlay
  • closeOnClickOverlay 重命名为 closeOnOverlayClick
  • onOpenedonClosed 重命名为 afterShowafterClose,继承自Overlay,用于完全关闭后触发的回调和完全展示后触发的回调
  • destroyOnClose 的描述进行了修订,改为:“组件不可见时,卸载内容”,并把其默认值改为了false
  • onClickCloseIcononClickOverlay 两个方法,增加布尔判断,如返回false 或 未定义返回值时,将不再关闭 Popup;默认值为 true;在demo中已增加相应示例;同时,两者的名字变更为 onCloseIconClickonOverlayClick
  • closeIcon 类型从 string 改为 ReactNode,以前的 closeIcon='mask-close' 需改为 closeIcon={<MaskClose />}
  • onOverlayClickonCloseIconClick 不会自动触发 onClose 了,如需触发关闭事件,需主动调用 onClose 回调函数
  • 新增 description 属性,支持标题下展示描述内容。
  • 调整 positionbottom 时的默认样式,默认支持圆角,此刻不需要再设置 round 属性。

布局组件

Divider

  • 移除 dashed, 通过 style 属性实现
  • 移除 hairline, 默认为 true
  • CSS 变量调整:$divider-before-margin-right$divider-after-margin-left 统一为 $divider-spacing$divider-vertical-border-left 变更为 $divider-border-color,增加 $divider-side-width

Grid

  • 移除 fontSize,可自行控制传入的组件字体大小
  • 移除 border,作为默认样式
  • columnNum 重命名为 columns
  • GridItem 使用方式修改为 Grid.Item

Layout

Sticky

  • 移除 topbottom, 重命名为 threshold

导航组件

Elevator

  • acceptKey 重命名为 floorKey
  • indexList 重命名为 list
  • isSticky 重命名为 sticky
  • onClickIndex 重命名为 onIndexClick
  • onClickItem 重命名为 onItemClick
  • 新增showKeys,是否展示右侧导航
  • CSS 变量部分,对命名做了简化。

FixedNav

  • unActiveText 重命名为 inactiveText
  • navList 重命名为 list
  • slotBtn 重命名为 content
  • onSelected 重命名为 onSelect
  • 移除 fixednavClass,通过 className 实现
  • 移除 slotList,通过 children 实现
  • 该组件已废弃 BEM 规范,记得把 __ 改为 -

Indicator

  • 移除 block,暴露自定义节点
  • 移除 align,暴露自定义节点
  • vertical 重命名为direction,默认值为 horizontal,可选 vertical
  • 移除 fillZero,暴露自定义节点
  • size 重命名为 total
  • 增加非数字展示,并设置为默认状态

Menu

  • 移除 fontClassName
  • 移除 iconClassPrefix
  • closeOnClickOverlay 重命名为 closeOnOverlayClick
  • titleIcon 重命名为 icon
  • optionsIcon 重命名为 icon
  • 增加 closeOnClickAway

NavBar

  • desc 重命名为 right,类型修改为 React.Node
  • 新增 left,左侧内容,渲染在返回区域的右侧
  • 新增 back,返回区域内容
  • onClickBack 重命名为 onBackClick
  • 移除 title,通过 children 实现
  • 移除 leftText leftShow,通过 backleft实现
  • safeAreaInsetTop 重命名为 safeArea
  • border 废弃
  • 移除 onClickTitle onClickRight onClickIcon,通过在lefttitleright自定义事件实现,参考文档demo示例

Pagination

  • 新增 lite 模式,只展示页码,不支持事件交互
  • 新增 defaultValue 非受控值
  • modelValue 重命名为 value,受控值
  • prevText 重命名为 prev,类型修改为 ReactNode
  • nextText 重命名为 next,类型修改为 ReactNode
  • forceEllipses 重命令为 ellipse
  • showPageSize 重命名为 itemSize
  • itemsPerpage 重命名为 pageSize
  • totalitems 重命名为 total
  • pageNodeRender 重命名为 itemRender
  • 移除 pageCount,通过 totalpageSize 组合实现

SideNavBar

  • offset 重命名为 indent

Tabbar

  • unactiveColor 重命名为 inactiveColor
  • tabTitle 重命名为 title,类型修改为 ReactNode
  • bottom 重命名为 fixed
  • safeAreaInsetBottom 重命名为 safeArea
  • visible 重命名为 defaultValue,非受控
  • activeVisible 重命名为 value,受控

TabbarItem

  • 使用方式修改为 Tabbar.Item
  • icon 类型改为 ReactNode,移除其他 icon 关联属性
  • 移除 href,通过 onSwitch 事件控制链接与路由跳转
  • 移除 num,支持传入所有 Badge Props
  • 移除 color,使用父元素的 activeColor,保持同样的 active 状态

Tabs

  • 增加 litecardbuttondivider 模式。
  • 移除 background,通过 classNamestyle 控制
  • 移除 titleScroll, 默认支持滚动
  • 移除 ellipsis,默认 flex:1
  • 移除 size,通过 css 变量 --nutui-tabs-titles-item-font-size 实现
  • animatedTime 重命名为 duration
  • titleGutter 重命名为 css 样式变量实现
  • titleNode 重命名为 title
  • color 重命名为 activeColor
  • type 重命名为 activeType
  • leftAlign 重命名为 align
  • onClick 类型改为 (index: string | number) => void
  • onChange 类型改为 (index: string | number) => void
  • 增加 defaultValue
  • 增加 activeType 类型 simple,实现选项卡的简约选择,只修改字号和字重,不处理字色。

Tabs.Tabpane

  • paneKey 重命名为 value

数据录入

Calendar

  • poppable 重命名为 popup
  • isAutoBackFill 重命名为 autoBackfill
  • toDateAnimation 重命名为 scrollAnimation
  • startText 类型改为 ReactNode
  • endText 类型改为 ReactNode
  • confirmText 类型改为 ReactNode
  • onBtn 重命名为 renderHeaderButtons
  • onDay 重命名为 renderDay
  • onTopInfo 重命名为 renderDayTop
  • onBottomInfo 重命名为 renderDayBottom
  • onSelected 重命名为 onDayClick
  • onChoose 重命名为 onConfirm
  • onYearMonthChange 重命名为 onPageChange
  • 新增 firstDayOfWeek,支持按照周进行选择,指定周起止日,如0-6

Cascader

  • 新增 defaultValue,其中 defaultValue 用于非受控,原 value 用于受控。两者的类型都改为 (number | string | undefined)[]
  • checkedIcon 重命名为 activeIcon
  • poppable 重命名为 popup
  • lazyLoad 重命名为 onLoad,当启动懒加载 lazy 时,动态加载数据
  • convertConfig 重命名为 format,配置转换规则
  • 合并 textKey valueKey childrenKey 三个属性为对象属性 optionKey
  • 移除 tabsColor, 该属性为设置 Tabs 当前选中的 tab 的下划线色值,但该值最好与文字部分搭配使用,统一处理 CSS 变量。

Checkbox

  • 新增 defaultChecked,用于非受控,checked 用于受控
  • 新增 value,用于 group 模式
  • textPosition 重命名为 labelPosition
  • iconName 重命名为 icon,类型为 ReactNode
  • iconAcitveName 重命名为 activeIcon
  • iconIndeterminateName 重命名为 iconIndeterminateIcon
  • 移除 iconSize
  • 部分 className 命名变更,废弃 nutui-checkbox__xx 命名方式,直接使用 nutui-checkbox-xx,并对选中状态命名修订为 nutui-checkbox-icon-checked
  • 增加半选的禁用状态

Checkbox.Group

  • 新增 defaultValue,用于非受控,value 用于受控
  • textPosition 重命名为 labelPosition
  • toggleAll 重命名为 toggle
  • toggleReverse 重命名为 reverse
  • 部分 className 命名变更,废弃 nutui-checkbox__xx 命名方式,直接使用 nutui-checkbox-xx,并对选中状态命名修订为 nutui-checkbox-icon-checked

DatePicker

  • modelValue 重命名为 value,并增加 defaultValue
  • isShowChinese 重命名为 showChinese
  • minDate 重命名为 startDate
  • maxDate 重命名为 endDate
  • onConfirmDatePicker 重命名为 onConfirm
  • onCloseDatePicker 重命名为 onClose
  • 因为依赖组件Picker的变更,方法 onConfirmDatePickeronChange的参数进行了调整,从(selectedValue, selectedOptions) 改为 (selectedOptions, selectedValue)

Form

  • 增加 footer,类型为 ReactNode,用于表单底部区域,通常用于设置提交、重置按钮
  • 增加 initialValues,用于设置表单初始值,同时用于表单的重置
  • 增加 name 属性

Form.Item

  • 移除 labelWidth, 通过 --nutui-form-item-label-width 控制宽度
  • 增加 required,用于必选样式控制
  • 增加 trigger,用于设置数据更新的时机
  • 增加 valuePropName,用于收集子组件受控的属性映射
  • 增加 getValueFromEvent,用于在收集数据中进行数据转换
  • 增加 onclick 用于收集子组件的 ref

Input

InputNumber

  • 增加 allowEmpty, 用于允许内容是否为空
  • 新增 defaultValue,用于非受控,value 用于受控
  • decimalPlaces 重命名为 digits
  • isAsync 重命名为 async
  • 移除 inputWidth, 通过--nutui-inputnumber-input-width控制输入框的宽度
  • 移除 buttonSize, 通过–nutui-inputnumber-button-width–nutui-inputnumber-button-height控制按钮的宽度和高度
  • taro 新增 formatter 属性, 用于指定输入框展示值的格式
  • 移除 errorMessage
  • 移除 showWordLimit
  • autofocus 重命名为 autoFocus
  • type="textarea" 建议改为使用 TextArea 组件实现

NumberKeyboard

  • randomKeys 重命名为 random
  • customKey 重命名为 custom
  • title 类型变更为 ReactNode
  • 新增 onConfirm 事件
  • 移除 popClass 定义,默认支持透传 Popup 属性

Picker

  • isVisible 重命名为 visible
  • listData 重命名为 options
  • defaultValueData 重命名为 defaultValue
  • 增加受控 value
  • swipeDuration 重命名为 duration
  • onCloseUpdate 重命名为 afterClose
  • 方法 onConfirmonCloseafterCloseonChange的参数进行了调整,从(selectedValue, selectedOptions) 改为 (selectedOptions, selectedValue)

Radio

  • 移除 iconSize,可通过 Icon 的 css 变量设置
  • iconName 重命名为 icon,类型修改为 ReactNode
  • 增加 labelPosition,用于设置 label 的位置
  • 增加 checkeddefaultChecked ,用于受控和非受控
  • onChange 类型修改为 (checked: boolean) => void
  • 部分 className 命名变更,废弃 nutui-radio__xx 命名方式,直接使用 nutui-radio-xx,并对选中状态命名修订为 nutui-radio-icon-checked

Radio.Group

  • textPosition 重命名为 labelPosition
  • 增加 defaultValue ,用于非受控
  • onChange 类型修改为 (value: string| number) => void
  • 部分 className 命名变更,废弃 nutui-radio__xx 命名方式,直接使用 nutui-radio-xx,并对选中状态命名修订为 nutui-radio-icon-checked

Range

  • maxDesc 重命名为 maxDescription,类型改为 ReactNode
  • minDesc 重命名为 minDescription,类型改为 ReactNode
  • curValueDesc 重命名为 currentDescription,类型改为 (value) => ReactNode
  • 移除 hiddenRange,通过 max/minDescriptionnull 实现
  • 移除 hiddenTag,通过 currentDescriptionnull 实现
  • 移除 activeColorinactiveColorbuttonColor,通过 css 变量实现
  • onDragStart 重命名为 onStart
  • onDragEnd 重命名为 onEnd
  • modelValue 重命为 value,增加 defaultValue 非受控方式

Rate

  • minimizeValue 重命名为 min
  • readonly 重命名为 readOnly
  • 移除 spacing,通过 css 样式变量实现
  • 移除 activeColorvoidColoriconSize,通过 checkedIconuncheckedIcon 实现
  • 增加受控 value 与非受控 defaultValue,移除 modelValue

SearchBar

  • onClickInput 重命名为 onInputClick
  • 移除 clearSize,样式默认
  • 移除 background,使用 CSS 变量 --nutui-searchbar-background 实现
  • 移除 inputBackground,使用 CSS 变量 --nutui-searchbar-input-background 实现
  • 移除 align,使用 CSS 变量 --nutui-searchbar-input-text-align
  • 新增 leftright,为 ReactNode 节点,可自定义内容
  • 移除 leftoutIconlabel,使用 left 实现
  • 移除 rightoutIconactionText,使用 right 实现
  • 移除 leftinIcon,使用 leftIn 实现
  • 移除 rightinIcon,使用 rightIn 实现,同时兼顾和 clearIcon 的交互,当设置rightIn时,默认展示 rightIn,当触发输入后,展示 clearIcon。同时增加 backable 来标记是否展示左侧返回Icon
  • 移除 onCancel,使用 right 来实现事件处理
  • 移除 onClickLeftinIcon,用户可使用 left 来实现事件处理
  • 移除 onClickLeftoutIcon,用户可使用 left 来实现事件处理
  • 移除 onClickRightinIcon,用户可使用 right 来实现事件处理
  • 移除 onClickRightoutIcon,用户可使用 right 来实现事件处理

ShortPassword

  • desc 重命名为 description
  • noButton 重命名为 hideFooter
  • onOk 重命名为 onConfirm
  • errorMsg 重命名为 error
  • 移除 closeOnClickOverlay,默认支持透传 Popup 属性
  • titledescriptiontipserror 类型修改为 ReactNode
  • modelValue 重命名为 value,受控模式
  • 新增 onFoucs 事件

TextArea

  • maxlength 重命名为 maxLength
  • readonly 重命名为 readOnly
  • limitShow 重命名为 showCount
  • autosize 重命名为 autoSize
  • 移除 textAlign,可通过 style 传入
  • defaultValue 改为非受控,增加受控值 value

Uploader

  • maximize 重命名为 maxFileSize
  • maximum 重命名为 maxCount
  • listType 重命名为 previewType
  • isDeletable 重命名为 deletable
  • isPreview 重命名为 preview
  • defaultImg 重命名为 previewUrl
  • defaultFileList 重命名为 defaultValue
  • uploadIconTip 重命名为 uploadLabel,类型变更为 ReactNode
  • onBeforeUpload 重命名为 beforeUpload
  • onBeforeXhrUpload 重命名为 beforeXhrUpload
  • onBeforeDelete 重命名为 beforeDelete
  • onRemove 重命名为 onDelete
  • 增加 fit,用于图片填充模式
  • 增加 value,用于受控传值
  • 移除 uploadIconSize,可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小
  • uploadIcon 类型从 string 调整为 ReactNode
  • onChange 参数类型从 {fileList: FileItem[], event: any} 调整为 FileItem[]

操作反馈

ActionSheet

  • title,类型变更为 ReactNode
  • description,类型变更为 ReactNode
  • cancelTxt,重命名为 cancelText,类型变更为 ReactNode
  • menuItems 重命名为 options
  • chooseTagValue 重命名为 value
  • onChoose 重命名为 onSelect
  • 增加 options 的定义
    • color 重命名为 danger
    • name,列表项的标题key
    • description,列表项的描述key
    • danger,列表项中提醒用户重点关注的操作
    • disabled,列表项中禁用项

BackTop

  • elId 重命名为 target
  • 移除 rightbottom,通过 style 传入,增加支持 lefttop
  • distance 重命名为 threshold
  • 移除 isAnimation,通过 duration 设置 0 实现无动画效果

Dialog

  • okText 重命名为 confirmText,规范命名。
  • mask 重命名为 overlay,组件库中统一使用 Overlay 组件作为遮罩层,并使用 overlay 作为是否展示遮罩层的属性值。
  • closeOnClickOverlay 重命名为 closeOnOverlayClick,组件库统一到该属性。
  • noOkBtn 重命名为 hideConfirmButton,初始值不变,依然表示是否隐藏确认按钮,主要是为了语义化更强。
  • noCancelBtn 重命名为 hideCancelButton,初始值不变,依然表示是否隐藏取消按钮,主要是为了语义化更强。
  • okBtnDisabled 重命名为 disableConfirmButton,初始值不变,依然表示是否禁用确认按钮,主要是为了语义化更强。
  • 移除 noFooter,使用 footer 统一处理,当 footer 为空时,及可替代该值。目前 noFooter 也需要手动声明是否为 noFooter;修改后需手动指出 footer={null}
  • 移除 textAlign,改用样式变量 --nutui-dialog-content-text-align 或 SCSS 变量 $dialog-content-text-align 控制,默认值为 center。
  • 移除 cancelAutoClose,改为 beforeCancelbeforeClose 来实现,在点击关闭或取消时,可先触发这两个方法,以确定是否要关闭弹框,如返回true,则关闭;否则不关闭。
  • onOk 重命名为 onConfirm,规范命名。
  • onClosed 重命名为 onClose,规范命名,关闭时触发。
  • onClickSelf 重命名为 onClick,语义不变,仍表示点击弹框自身时触发事件。
  • 增加 overlayStyleoverlayClassName,用来配置 Overlay 组件样式。
  • 增加 onOverlayClick,支持点击overlay时,触发事件。
  • onCancel 回调不会自动关闭弹层,需主动调用 Dialog.close(xx)

Drag

InfiniteLoading

  • useCapture 重命名为 capture
  • onScrollChange 重命名为 onScroll
  • isOpenRefresh 重命名为 pullRefresh
  • pullTxt 重命名为 pullingText,类型变更为 ReactNode
  • loadTxt 重命名为 loadingText,类型变更为 ReactNode
  • containerId 重命名为 target
  • 修订类名如 top-boxbottom-boxnut-infinite-top-tipsnut-infinite-bottom-tips

Notify

  • 移除 color ,通过css变量--nutui-notify-text-color实现
  • 移除background,通过css变量--nutui-notify-base-background-color实现
  • onClosed 重命名为 onClose

PullToRefresh

Swipe

  • 移除 leftWidth ,通过 leftAction 实现
  • 移除 rightWidth ,通过 rightAction 实现

Switch

  • 新增 defaultChecked,用于非受控,checked 用于受控
  • 移除 isAsync,通过 checked实现
  • 移除 activeColor ,通过css变量--nutui-switch-open-background-color实现
  • 移除 inactiveColor,通过css变量--nutui-switch-close-background-color实现

Toast

  • 移除H5版本 id
  • 移除 centerbottom,通过 position 实现
  • 移除 bgColor,通过 css 变量实现
  • 移除 customClass,通过 className 实现
  • 移除 covercoverColor ,通过css变量实现
  • 移除 loadingRotate,旋转状态通过 iconFont实现
  • 移除 textAlignCenter,通过css变量实现
  • 修改 closeOnClickOverlaycloseOnOverlayClick ,语义不变,是否在点击遮罩层后关闭提示
  • 新增 lockScroll ,用于背景是否锁定,默认值为 false

展示组件

Animate

  • type 属性类型更改为 AnimateType ,具体值详见文档
  • action 属性类型更改为 initial \| click

AnimatingNumbers

  • maxLen 重命名为 length
  • endNumber 重命名为 value,类型修改为 string|number
  • delaySpeed 重命名为 delay
  • easeSpeed 重命名为 duration

Audio

  • url 重命名为 src
  • autoplay 重命名为 autoPlay
  • onFastBack 重命名为 onBack
  • onPlayEnd 重命名为 onEnd

Avatar

  • url 重命名为 src
  • onActiveAvatar 重命名为 onClick
  • 新增 fit 属性,用于图片填充模式
  • 移除 iconSize,可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小

AvatarGroup

  • AvatarGroup maxCount 重命名为 max
  • AvatarGroup span 重命名为 gap
  • AvatarGroup zIndex 重命名为 level

Badge

  • 移除 zIndex,目前没有用到,也不生效,直接去掉。
  • 移除 icon,自定义 icon 可放在 value 中实现,扩充了 value 的类型。
  • 修改 max 的最大值为99(之前为10000),比较贴合实际场景。
  • 主题定制的 css 变量中,去掉和 dot 有关的其他值,只保留 width。其他值由 width 计算而来.
  • 主题定制,增加包含 icon 情况下的样式变量。

CircleProgress

  • progress 重命名为 percent
  • circleColor 重命名为 color
  • pathColor 重命名为 background

Collapse

  • 新增 defaultActiveName 非受控
  • activeName 改为受控方式
  • icon 重命名为 expandIcon,类型修改为 ReactNode
  • onChange 参数变更为 activeName, name, status
  • 新增一种样式,尝试修改 --nutui-collapse-item-border-bottom-nutui-collapse-item-header-border-bottom,可查看

CollapseItem

  • 使用方式调整为 Collapse.Item
  • subTitle 重命名为 extra,类型修改为 ReactNode
  • 新增 expnandIcon,优先级高于父组件对应值
  • 新增 rotate,优先级高于父组件对应值

CountDown

  • 新增 remainingTime,支持剩余毫秒时间倒计时。

Ellipsis

  • 新增 classNamestyle 属性的支持
  • 优化 H5 的代码,去掉 useEffect 渲染改用 useLayoutEffect

Empty

  • 新增 status 属性,用于默认图片错误类型
  • 新增 size 属性,用于区分全屏与半屏状态下图片的不同大小
  • 新增 title 属性,用于展示提示的标题部分
  • 新增 actions 属性,用于展示提示的操作部分,支持1个或2个操作
  • image 属性类型更改为 ReactNode
  • 新增 titlesizeactions 属性,支持标题的设置、图片大小的设置、可能的操作设置,操作设置默认以Button实现。

ImagePreview

  • show 重命名为 visible
  • autoplay 重命名为 autoPlay
  • initNo 重命名为 defaultValue,同时增加 value,为受控
  • paginationVisible 重命名为 indicator
  • paginationColor 重命名为 indicatorColor
  • contentClose 重命名为 closeOnContentClick
  • Taro 下支持视频

NoticeBar

  • direction 的可选值从 across 重命名为 horizontal
  • text 重命名为 content
  • closeMode 重命名为 closeable
  • leftIcon 类型扩充,支持 ReactNode
  • rightIcon 类型扩充,支持 ReactNode
  • color 移除,使用 CSS 变量,之前已支持
  • background 移除,使用 CSS 变量,之前已支持
  • wrapable 重命名为 wrap
  • standTime 重命名为 duration
  • onClickItem 重命名为 onItemClick
  • complexAm 废弃

Popover

  • 移除 theme 属性,可以通过css变量 --nutui-brand-color 控制暗黑模式
  • 新增 showArrow 属性,用于是否显示小箭头
  • 新增 closeOnActionClick 属性,用于是否在点击选项后关闭
  • 新增 closeOnOutsideClick 属性,用于是否在点击外部元素后关闭菜单
  • 新增 targetId 属性,用于自定义目标元素 id
  • 新增 onOpen 属性,用于点击菜单时触发
  • 新增 onClose 属性,用于关闭菜单时触发
  • 新增 action 属性,用于为对应的选项添加方法
  • onChoose 重命名为 onSelect
  • 继承Popup组件的 overlayStyleoverlayClassNameoverlaycloseOnOverlayClick 属性。

Price

  • decimalDigits 重命名为 digits
  • 移除 needSymbol,通过 symbol 判断是否需要加上 symbol 符号
  • 新增 line,是否展示划线价

Progress

  • percentage 重命名为 percent,受控
  • 移除 isShowPercentage,可以自定义传入文案
  • 移除 textWidth,可以自定义传入内容的宽度
  • strokeColor 重命名为 color
  • fillColor 重命名为 background
  • 移除 size,通过 strokeWidthprogress-height css 变量实现尺寸自定义
  • status 重命名为 animated,表示是否展示动画效果
  • 移除 textBackground,通过 css 实现
  • 移除 textColor,通过 css 实现
  • 移除 textInside,仅保留内显功能
  • 移除 textType、icon,通过 children 传入自定义 ReactNode,不再区分类型
  • 新增 lazy 属性,支持每次进入可视区时展示进度条动画
  • 新增 delay 属性,表示延迟数据加载时长

Skeleton

  • loading 重命名为 visible
  • row 重命名为 rows
  • 移除 width,通过 css 变量 skeleton-line-width 实现
  • 移除 height,通过 css 变量 skeleton-line-height 实现
  • 移除 round,通过 css 变量 skeleton-line-border-radius 实现

Steps

  • current 重命名为 value
  • onClickStep 重命名为 onStepClick
  • progressDot 重命名为 dot

Step

  • 移除 iconColor,可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 颜色
  • 移除 size,可通过 icon 属性传入自定义 icon 或借助 CSS Variables 修改 icon 大小
  • 移除 renderContent ,可通过 description 实现
  • title 类型修改为 ReactNode
  • content 重命名为 description,类型改为 ReactNode
  • icon 类型修改为 ReactNode
  • activeIndex 重命名为 value

Swiper

  • h5
    • 移除 paginationColor,通过 indicator 的 CSS 变量控制
    • 移除 paginationBgColor,通过 indicator 的 CSS 变量控制
    • 移除 pageContent,通过 indicator 实现
    • autoplay 重命名为 autoplay
    • initPage 重命名为 defaultValue
    • paginationVisible 重命名为 indicator,类型改为 ReactNode
    • isPreventDefault 重命名为 preventDefault
    • isStopPropagation 重命名为 stopPropagation
    • isCenter 重命名为 center
  • taro
    • 通过封装 Taro 的 SwiperSwiperItem 实现,支持的属性可参考 Taro Swiper 文档。

Table

  • onSorter 重命名为 onSort
  • 合并 summarynoData 的样式处理

Tag

  • color 重命名为 background
  • textColor 重命名为 color

TrendArrow

  • rate 重命名为 value
  • showSign 重命名为 symbol
  • showZero 重命名为 zero
  • arrowLeft 重命名为 left
  • syncTextColor 重命名为 sync
  • textColor 重命名为 color
  • upIconName 重命名为 riseIcon,类型修改为 React.Node
  • downIconName 重命名为 dropIcon,类型修改为 React.Node
  • 移除 iconSize,通过riseIcondropIcon自定义传入icon大小

Video

  • Taro 下新增video的适配

VirtualList

  • sourceData 重命名为 list
  • conatinerSize 重命名为 containerHeight
  • itemSize 重命名为 itemHeight
  • itemEqualSize 重命名为 itemEqual
  • horizontal 修改为 direction,默认值 vertical,可选值 horizontal

WaterMark

  • fontColor 重命名为 color

特色组件

Address

  • 该组件的 custom 改用 Cascader 组件重写;custom2也将使用 Cascader 完成,在 Cascader 中支持 Elevator,开发中。所以会废弃 provincecitycountrytown 这些属性,同时支持 Cascader 的属性。
  • modelValue 重命名为 visible
  • modelSelect 重命名为 defaultValue
  • onSelected 重命名为 onSelect
  • existAddress 重命名为 existList
  • selectedIcon 重命名为 selectIcon
  • closeBtnIcon 重命名为 closeIcon
  • backBtnIcon 重命名为 backIcon
  • isShowCustomAddress 重命名为 custom,用于已有地址列表与自定义列表的切换,修改默认为值 false
  • customAndExistTitle 废弃,与 custom 合并,当 custom 为 true 时,为默认文案,设置为某字符串时,展示字符串。
  • customAddressTitleexistAddressTitle 重命名为 title,不再区分状态,可通过onSwitch修改title
  • 精简布局和样式

Barrage

  • barrageList 重命名为 list
  • frequency 重命名为 interval
  • speeds 重命名为 duration
  • top 重命名为 gapY

Card

Signature

  • type 类型修改为 png|jpg
  • unSupportTpl 重命名为 unsupported,类型修改为 ReactNode
  • 新增 confirmclear ref 的方法,移除组件内部 button元素,通过自定义按钮元素,设置元素点击事件结合ref实现,参考文档demo示例

TimeSelect

  • 移除 height,通过 style 设置高度
  • title 类型修改为 ReactNode
  • onPannelChange 重命名为 onDateChange
  • 移除 datestimes,合并为 options,重新设计了数据结构
  • 增加 optionKey 用于自定义数据中的关键字
  • 移除 currentKey,新增 defaultValue 用于设置默认选项,支持时间选择