2022.09.10 更新
dev 分支已切换到 4.0.0-rc 版本,v3 版本在 3.x 分支继续维护。
2022.09.04 更新
已发布 4.0.0-rc.0 版本
Vant 4.0 beta 版本已发布,欢迎体验~
安装
通过以下方式安装 Vant 4.0 beta 版本:
npm i vant@beta
文档
Vant 4.0 文档已部署上线,访问地址:https://vant-contrib.gitee.io/vant/v4/
深色模式
将 ConfigProvider 组件的 theme
属性设置为 dark
,可以开启深色模式。
深色模式会全局生效,使页面上的所有 Vant 组件变为深色风格。
<van-config-provider theme="dark">...</van-config-provider>
同时,Vant 文档也支持切换到深色模式:

组件重构
Picker 组件重构
在之前的版本中,Picker 组件的 API 设计存在一些不合理的设计,比如:
- columns 数据格式定义不合理,容易产生误解
- 数据流不清晰,暴露了过多的实例方法来对数据进行操作
为了解决上述问题,我们在 v4 版本中对 Picker 组件进行了重构。
主要变更
- 支持通过
v-model
绑定当前选中的值,移除 default-index
属性
- 重新定义了
columns
属性的结构
- 移除了操作内部数据的实例方法,仅保留
confirm
方法
- 新增
getSelectedOptions
实例方法
- 调整了
confirm
、cancel
、change
事件的参数
- 重命名
item-height
属性为 option-height
- 重命名
visible-item-count
属性为 visible-option-num
详细用法请参见 Picker 组件文档。
DatetimePicker 组件重构
DatetimePicker 组件被拆分为:
- TimePicker: 用于时间选择。
- DatePicker: 用于日期选择。
同时,这两个组件也基于新版 Picker 组件进行重构,并优化了部分 API 设计。
在后续的测试版本中,会提供基于这两个组件提供一个新的 DatetimePicker 组件。
主要变更
v-model
绑定的值调整为数组格式
- 新增
columns-type
属性,用于控制选项类型和顺序
- 移除
type
属性和 columns-order
属性
- 移除
getPicker
方法
- 调整
confirm
、cancel
、change
事件的参数,与 Picker 组件保持一致
Area 组件重构
Area 组件是基于 Picker 组件进行封装的,因此本次升级也对 Area 组件进行了内部逻辑的重构,并优化了部分 API 设计。
主要变更
- 支持通过
v-model
绑定当前选中的值
- 移除
reset
方法,现在可以通过修改 v-model
来进行重置
- 移除
is-oversea-code
属性
- 调整
confirm
、cancel
、change
事件的参数,与 Picker 组件保持一致
- 重命名
value
属性为 modelValue
- 重命名
item-height
属性为 option-height
- 重命名
visible-item-count
属性为 visible-option-num
详细用法请参见 Area 组件文档。
API 调整
事件命名调整
从 Vant 4 开始,所有的事件均采用 Vue 官方推荐的驼峰格式进行命名。
// Vant 3
emit('click-input');
// Vant 4
emit('clickInput');
这项改动不影响原有的模板代码,Vue 会自动在模板中对事件名进行格式转换:
<!-- 以下代码可以照常运行,无须做任何更改 -->
<van-field @click-input="onClick" />
如果你在 JSX 中使用 Vant 组件,需要将监听的事件名调整为驼峰格式,新的监听方式更加符合 JSX 本身的规范:
// Vant 3
<Field onClick-input={onClick} />
// Vant 4
<Field onClickInput={onClick} />
其他 API 调整
在 Vant 4.0 版本中,以下 API 进行了不兼容更新:
Tabs
- 移除了
click
和 disabled
事件,请使用 click-tab
事件代替
AddressEdit
change-area
事件的参数调整为 PickerOption[]
类型
- 移除未在文档中标注的
getArea
实例方法
样式变量调整
移除 Less 变量
目前 Vant 已经支持了基于 CSS 变量的主题定制能力,因此后续将不再提供基于 Less 的主题定制方式。
如果你的项目正在使用旧版的 Less 主题定制,请使用 ConfigProvider 全局配置 组件进行替换。
简化 CSS 变量名
考虑到 代码体积 和 使用便捷性,我们对部分 CSS 变量的名称进行了简化,在变量名中使用更简短的单词,涉及以下变更:
animation-duration -> duration
animation-timing-function-enter -> ease-out
animation-timing-function-leave -> ease-in
background-color -> background
background-color-light -> background-2
border-radius -> radius
border-width-base -> border-width
box-shadow -> shadow
font-family -> font
font-weight-bold -> font-bold
price-integer-font -> price-font
text-link -> link
transition-duration -> duration
由于涉及的 CSS 变量较多,建议在代码仓库中进行全局匹配和替换。
统一主色调
在之前的版本中,Vant 组件有两种色彩风格,一部分采用红色作为主色调,另一部分采用蓝色。为了保持色彩规范的统一,我们在 Vant 4 中对组件的主色调进行了统一,所有组件均采用蓝色作为主色调。
以下组件的默认色值风格由红色调整为蓝色:
- AddressEdit
- AddressList
- Card
- Calendar
- Cascader
- ContactList
- ContactEdit
- CouponList
- Dialog
- DropdownMenu
- IndexBar
- Sidebar
- Steps
- Tabs
- TreeSelect
其他样式改动
--van-font-bold
的默认值由 500
调整为 600
- ActionBar: 调整
--van-action-bar-icon-text-color
变量的默认值为 --van-text-color
- AddressList: 重命名
--van-address-list-item-radio-icon-color
为 --van-address-list-radio-color
- Button: 默认圆角大小从
2px
调整为 4px
- Button: 默认按钮的边框颜色调整为
--van-gray-4
- Button: 调整
font-smoothing
,默认使用粗体文字
- Cell: 只设置
value
时,内容不再会靠左对齐
- Card: 调整
--van-card-background
变量的默认值为 --van-background
- Card: 调整
--van-card-price-color
变量的默认值为 --van-text-color
- Card: 调整
--van-card-desc-color
变量的默认值为 --van-text-color-2
- ContactList: 重命名
--van-contact-list-item-radio-icon-color
为 --van-contact-list-radio-color
- CouponList: 重命名
--van-coupon-corner-checkbox-icon-color
为 --van-coupon-checkbox-color
- Field: 调整
--van-field-label-color
变量的默认值为 --van-text-color
- Switch: 移除
--van-switch-border
变量
- Switch: 调整
--van-switch-size
变量的默认值为 26px
- Switch: 调整
--van-switch-background
变量的默认值为 rgba(120, 120, 128, 0.16)
- Tabbar: 调整
--van-tabbar-item-text-color
变量的默认值为 --van-text-color
- GridItem: 调整
--van-grid-item-text-color
变量的默认值为 --van-text-color
👀 discuss