发布 Vant 3.0 🔥

在 2020 年上半年，我们的主要目标是发布 Vant 3.0 版本，主要包含以下更新：

• 基于 Vue 3.0 开发，使用 Composition API 重构所有组件，增强组件间的逻辑复用并减少包体积。
• 使用 TypeScript 重构所有代码，提供更完善的类型支持。
• 增加更多实用的基础组件，如 Form、Popover。
• 完善组件交互，如 Tab 增加滑动切换动画，ImagePreview 支持原生级的手势操作。
• 提供更好的文档、更丰富的示例，文档无止境。

由于 Vue 3.0 已经发布了第一个 alpha 版本，Vant 3.0 也将于近期正式启航。我们会在 next 分支进行 3.0 版本的开发工作，同时在 dev 分支持续维护 2.x 版本。

持续优化 Vant Cli 🌟

在 2019 年年底，我们悄悄发布了 Vant Cli，一个开箱即用的 Vue 组件库搭建工具（可以将它理解为面向组件库的 Vue Cli），其中包含了我们在开发 Vant 过程中所积累的工程化最佳实践。你可以使用 Vant Cli 搭建一套基于 Vant 的业务组件库，或是从零开始搭建一套 Vue 基础组件库。

Vant 从 2.3 版本开始接入了 Vant Cli 进行构建，同时 Vant Cli 也已在有赞内部的多套业务组件库中落地。

后续我们会持续优化 Vant Cli，主要目标是提供更丰富的配置项以及完善文档。希望它能够帮助大家更轻松地搭建一套完备的组件库。

Vant Weapp 迭代 & 探索 🏃

上个月我们刚刚发布了 Vant Weapp 1.0 版本，对齐了 Vant 2.0 的大部分功能，并基于 CSS Variables 提供了自定义主题的能力。

后续我们对 Vant Weapp 的规划是在 1.0 版本的基础上持续迭代，提高性能和稳定性，并跟进微信小程序框架的升级，探索小程序组件更多的可能性。

目前 Vant 已完成了对 Vue 3.0 的绝大部分适配工作，并发布了 Vant 3.0 RC 版本，欢迎大家在新项目中尝试 Vant 3.0。

背景知识

在使用 Vant 3.0 前，请先了解一下 Vue 3.0 的变更内容：Vue 3.0 官方文档

安装 Vant 3.0

#npm
npm i vant@next -S

# yarn
yarn add vant@next

安装完成后，请参考 Vant 3.0 的文档使用：

• Vant 3.0 在线文档
• Vant 3.0 更新日志
• Vant 3.0 迁移指南
• Vant 3.0 源代码

后续计划

我们计划在十二月发布 Vant 3.0 正式版，目前正在进行的工作有：

• 对外提供 Vant 内部使用的 Composition API 模块，封装为 @vant/use 库（已完成）
• 使用 Composition API 重构所有组件（已完成）
• 使用 TypeScript 重构所有组件
• 完善单元测试并修复发现的问题
• 增加新组件和更多 Feature

注意事项

1. Sku 组件还未完成 Vue 3 适配，因此在 Vant 3.0 RC 版本中暂时不可用
2. beta 版本迭代过程中可能会引入少量的不兼容改动，在升级时请仔细阅读更新日志

视觉规范升级

近期我们还发布了 Vant 视觉规范 3.0，详见：Vant 设计规范 3.0 发布

问题反馈

使用 Vant 3.0 过程中遇到问题时，请通过 issue 的形式进行反馈~

背景

近期有比较多的童鞋反馈在 iOS 10.2、10.3、11.2 等版本的机型上出现组件无法操作、触摸没反应等问题，经排查是 Vue 2.6 更新引入的事件冒泡问题。

在 Vue 2.6 版本中，如果系统版本是 iOS 10.2 ~ 11.2，会偶现事件无法冒泡的情况，导致 Vant 部分组件里的逻辑无法触发。

最新进度

从 2.4 版本开始，我们通过手动绑定事件的方式来规避这个问题，涉及以下组件：

• Area
• DatetimePicker
• ImagePreview
• Rate
• Slider
• Swipe
• SwipeCell
• NumberKeyboard
• Picker
• PullRefresh

解决方法

如果你遇到了类似的问题，升级到 Vant 2.4.0 以上版本即可解决

降级 Vue 版本到 2.5.22 亦可解决此问题：

npm i [email protected] [email protected] --save

相关 issue

https://github.com/vuejs/vue/issues/10964

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

require('postcss-pxtorem')({ rootValue: 75, //默认根目录字体大小(px) unitPrecision: 5, //保留小数位 propList: ['*'], // selectorBlackList: [''], //过滤的类名 replace: true, //默认直接替换属性 mediaQuery: false, minPixelValue: 6, //所有小于设置的样式都不被转换 }),

但是改了设计稿的宽度又对不上了，有什么好的解决方案

【2019.06.13 更新】 2.0 正式版已发布，点此查看

Vant 2.0 版本正在热火朝天的开发中，预计5月下旬会发布 beta 版本，6月发布正式版

主要更新内容有：

• 增加四个新组件
• 增加数十个 API
• 优化无障碍访问
• 全新的卡片风格文档，支持文档搜索
• 所有组件支持通过 less 变量自定义样式
• 调整了部分不合理的命名，废弃少量 API

欢迎大家提出意见或需求 ^_^

【2019.05.22 更新】 beta 版本已发布，点此查看更新日志

补充安装方法：

npm i vant@beta -S

设备 / 浏览器

iphone 8p

Vant 版本

2.4.7

Vue 版本

2.6.11

重现链接

https://codesandbox.io/s/vant-issue-moban-5d9nf

描述问题

Calendar组件设置min-date、max-date和default-date时，日历控件首次弹出日期全部显示空白 向上滑动一下后才能显示出来

main.js import Vue from 'vue' import App from './App.vue' import { Button } from 'vant' import { Popup } from 'vant' import 'vant/lib/index.css'; Vue.use(Button); Vue.use( Popup);

组件.vue里 组件可以显示 但是样式不显示

只能通过script的方式单独引入index.css 求问该如何解决

IMPORTANT: Please use the following link to create a new issue. If your issue was not created using the app above, it will be closed immediately.

注意：请按照下面的模板来新建 issue，不规范的 issue 会被立即关闭.

What problem does this feature solve? A clear description of what the problem is.

Describe the solution you'd like A clear and concise description of what you want to happen.

What does the proposed API look like? Describe how you propose to solve the problem and provide code samples of how the API would work once implemented.

我也看了之前别人提的类似的问题，可是还没有解决

      onLoad() {
        setTimeout(() => {
          if (this.search.page < this.totalPage) {
            this.search.page += 1;
            console.log("this.search.page: ",this.search.page);
            this.$http.post("/search/page",this.search).then(({data})=> {
              this.noitem = false;
              data.items.forEach(goods => {
                goods.skus = JSON.parse(goods.skus);
                goods.skus.forEach(sku => {
                  sku.price = this.formatPrice(sku.price);
                  sku.spuId = goods.id;
                  this.goodsList.push(sku);
                })
              });
            });
            // 加载状态结束
            this.loading = false;
            
          }else{
            this.finished = true;
          }
        }, 500);
      },

全部页面都给加载了

历经八个月时长的开发，Vant 3.0 终于和大家正式见面咯。在本次迭代中，我们的主要工作是基于 Vue 3 重构整个代码仓库和周边生态，并发布 Vant 3.0、Vant Cli 3.0 和 Vant Use 1.0。

回顾

按照惯例，我们先简单回顾一下 Vant 开源至今的成绩：

• 270 位开发者 参与了 Vant 和 VantWeapp 开发，并贡献了 4100 个 Pull Request
• 7300 个 issue 被关闭，99.3% 的 issue 得到解决或答复
• 站点月访问量 800 万次
• CDN 月下载量 3 亿次

更新内容

Vant 3.0：全面拥抱 Vue 3 💪

Vue 3 带来了许多激动人心的新特性，比如 Composition API、emits Option 和 Teleport。在 Vant 3.0 中，我们全面拥抱了 Vue 3 带来的各种变化，完成下列改造：

• 使用 Composition API 重构所有组件
• 使用 Composition API 重写所有文档和示例
• 组件增加 emits 选项，提供更好的事件提示
• 移除所有 mixins，提升代码可读性
• 所有弹窗类组件支持 teleport 属性

重构完成后，组件之间可以基于 Composition API 进行逻辑复用，代码的可压缩性也有所提升。与 Vant 2.12 版本进行对比，可以看到 Vant 3.0 的 JS 体积下降了 16.6%，Gzip 后体积下降至 67.5kb。

新组件：Vant 2、Vant 3 同步供应

Vant 3.0 中包含 3 个全新的组件，分别是：

• Badge 徽标：用于在右上角展示徽标数字或小红点。
• Popover 气泡弹出框：弹出式的气泡菜单组件。
• Cascader 级联选择器：用于多层级数据的选择，典型场景为省市区选择。

考虑到大部分开发者仍然在使用 Vue 2 进行开发，我们在 Vant 2 中同步实现了以上三个组件，大家可以升级到 Vant 2.12 版本进行使用。

Vant Use：新伙伴 👬

Vant Use 从 Vant 中沉淀出的 Composition API 库。除了提供常用的 Composition API 外，Vant Use 也会将某些组件的逻辑抽离出来，让开发者在使用组件逻辑的同时，能够完全自定义组件的展现形式。

下面是一个简单的例子，我们将 CountDown 组件的倒计时逻辑抽象为 useCountDown 方法，功能与 CountDown 组件基本等价，但使用起来更加灵活，我们可以自定义倒计时的 UI 样式，或者通过 computed 对倒计时进行预处理。

Vant Use 仍然处于早期阶段，在未来的演进过程中，我们会继续抽离 Vant 组件内部的通用逻辑，并下沉到 Vant Use 中。

Vant Cli 3.0：更新，更快 🚀

Vant Cli 是 Vant 底层的组件库构建工具，通过 Vant Cli 可以快速搭建一套功能完备的 Vue 组件库。在 Vant Cli 3.0 中，我们对所有底层依赖进行了大版本升级，在支持 Vue 3 的同时，提供更流畅的开发体验。

• 升级 Vue 3、VueRouter 4、VueLoader 16
• 升级 Webpack 5，开启持久缓存能力
• 升级 Docsearch 3，全新的搜索框样式
• 升级 TypeScript 4、ESLint 7

在创建 vant-cli 工程时，你可以自由选择基于 Vue 2 或者 Vue 3 进行组件库开发：

Vant Demo：2 个新的示例工程

Vant Demo 是 Vant 官方提供的示例工程合集，在本次迭代中，我们新增了 2 个示例工程，分别演示：

• 如何使用 Vue 3 + Vant 3 + Vue Cli 搭建应用
• 如何使用 Vue 3 + Vant 3 + Vite 搭建应用

许多喜欢尝鲜的小伙伴已经在使用 Vite 进行开发了，在使用 Vite 的过程中，经常令大家困惑的一点是，如何在 Vite 中进行按需引入 Vant 组件。在 Vue Cli 中，我们可以通过 babel-plugin-import 插件实现按需引入，但在 Vite 中无法使用该插件。

其实在 Vite 中无须考虑按需引入的问题。Vite 在构建代码时，会自动通过 Tree Shaking 移除未使用的 ESM 模块。而 Vant 3.0 内部所有模块都是基于 ESM 编写的，天然具备按需引入的能力。现阶段遗留的问题是，未使用的组件样式无法被 Tree Shaking 识别并移除，后续我们会考虑通过 Vite 插件的方式进行支持。

开始尝鲜

目前，Vant 官网默认展示 Vant 2 的 API 文档，你可以通过官网右上角的版本切换按钮访问 Vant 3 的文档，也可以 👉 点此访问。

同时，Vant 的 npm latest 标签也保持在 v2 版本，这意味着使用 npm install vant 命令仍会安装 Vant 2，而安装 Vant 3 需要使用 npm install vant@next 命令。在 Vue 的默认文档版本和 npm 标签切换为 v3 后，我们也会同步进行切换。

从现有 Vant 2 项目升级，请参考 🚀 升级指南。

下一步计划

未来 6 ~ 12 个月内，我们会保持 Vant 2 和 Vant 3 的功能同步更新。随着 Vue 3 的普及，我们会逐步降低 Vant 2 的维护频率，并将工作重心转移到 Vant 3 上。

另外，除了官方维护的 Vue 版本和微信小程序版本，Vant 也有由社区的小伙伴们发起和维护的 React 版本和支付宝小程序版本，欢迎大家一起参与建设 💪

不平凡的 2020 年即将过去，希望 Vant 能给大家的工作带来一点点的帮助，我们明年再会。

Before submitting a pull request, please make sure the following is done:

1. Read the contributing guide.
2. If you've added code that should be tested, add tests.
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes (npm test).

Title Format

type(ComponentName?)：commit message

Example：

• docs: fix typo in quickstart
• build: optimize build speed
• fix(Button): incorrect style
• feat(Button): add color prop

Allowed Types:

• fix
• feat
• docs
• perf
• test
• types
• build
• chore
• refactor
• breaking change

Previous fixes not covered all kinds of emojis, it only covered 2 code points emojis like 👍. So I fork runes2(with fixes of subdivision-flag emojis' support) into vant.

重现链接

https://vant-ui.github.io/vant/#/zh-CN/image-preview

Vant 版本

4.0.4

描述一下你遇到的问题。

当我滑动的时候进行放大操作，会出现下面这种情况，能不能当我滑动的时候放大的话，切换到放大的那个swiper，卡在中间感觉挺怪的 https://user-images.githubusercontent.com/43991889/209319133-ef34d2c8-7a52-4aad-b37f-dda2534d3b28.MP4

重现步骤

滑动的时候进行放大

设备/浏览器

No response

重现链接

https://codesandbox.io/s/vant-3-issue-template-forked-mzx0b6?file=/src/App.vue

Vant 版本

4.0.2

描述一下你遇到的问题。

此问题引用 https://github.com/youzan/vant/issues/11368 因为涉及多个组件所以重新开一个。

个别组件使用动态切换插槽不更新。此问题是 vue 插槽更新策略的问题 https://github.com/vuejs/core/blob/main/packages/runtime-core/src/componentSlots.ts#L207 。 如果值是 null / undefined 用 in 检测也会存在所以不会删除。有更改此行为的 pr 但没有任何回复。

所以这个不是这单个组件的问题，当然要在特定的用例下才会复现所以这并不常见，我复现了一个 https://codesandbox.io/s/vant-3-issue-template-forked-mzx0b6?file=/src/App.vue 用例。

所以要解决此类问题需要在使用 v-slots={{ a: () => <Cell>, b: null, c: undefined }} 命名接收插槽地方去排除 null / undefined 即可修复。我看到你已经通过判断内容修复了此问题，是否考虑应从根源解决和全部修复。

重现步骤

使用 v-if 切换插槽。

设备/浏览器

No response

重现链接

https://codesandbox.io/s/laughing-lake-fezfdk?file=/src/App.vue:798-814

Vant 版本

3.4.6

描述一下你遇到的问题。

1. 快速滚动屏幕
2. 在浏览器环境下popover会轻微的抖动
3. 在webview环境会剧烈的抖动

重现步骤

滚动屏幕， 仔细观察popover，会发现抖动

设备/浏览器

chrome，app的webview中，等等