介绍
Vant 是一个轻量、可靠的移动端组件库,于 2017 年开源。
目前 Vant 官方提供了 Vue 2 版本、Vue 3 版本和微信小程序版本,并由社区团队维护 React 版本和支付宝小程序版本。
版本提示
你当前浏览的是 Vant 2.x 版本 的文档,适用于 Vue 2 开发。如果你在使用 Vue 3,请浏览 Vant 3 文档。
特性
- 🚀 性能极佳,组件平均体积小于 1KB(min+gzip)
- 🚀 65+ 个高质量组件,覆盖移动端主流场景
- 💪 使用 TypeScript 编写,提供完整的类型定义
- 💪 单元测试覆盖率超过 90%,提供稳定性保障
- 📖 提供完善的中英文文档和组件示例
- 📖 提供 Sketch 和 Axure 设计资源
- 🍭 支持 Vue 2、Vue 3 和微信小程序
- 🍭 支持主题定制,内置 700+ 个主题变量
- 🍭 支持按需引入和 Tree Shaking
- 🍭 支持服务器端渲染
- 🌍 支持国际化和语言包定制
脚手架
推荐使用 Rsbuild 来创建一个脚手架项目。
Rsbuild 是基于 Rspack 的构建工具,由 Vant 作者开发,具备一流的构建速度和开发体验,对 Vant 提供第一优先级支持。
你可以通过以下命令创建一个 Rsbuild 项目:
npm create rsbuild@latest
请访问 Rsbuild 仓库 了解更多信息。
快速上手
请参考快速上手章节。
贡献代码
修改代码请阅读我们的开发指南。
使用过程中发现任何问题都可以提 Issue 给我们,当然,我们也非常欢迎你给我们发 PR。
浏览器支持
Vant 2 支持现代浏览器以及 Android >= 4.0、iOS >= 8.0。
Vant 3 支持现代浏览器以及 Chrome >= 51、iOS >= 10.0(与 Vue 3 一致)。
官方生态
由 Vant 官方团队维护的项目如下:
项目 | 描述 |
---|---|
vant-weapp | Vant 微信小程序版 |
vant-demo | Vant 官方示例合集 |
vant-cli | 开箱即用的组件库搭建工具 |
vant-icons | Vant 图标库 |
vant-touch-emulator | 在桌面端使用 Vant 的辅助库 |
社区生态
由社区维护的项目如下,欢迎补充:
项目 | 描述 |
---|---|
3lang3/react-vant | 参照 Vant 打造的 React 移动端组件库 |
mxdi9i7/vant-react | 基于 React 和 TS 构建的移动端组件库 |
vant-aliapp | Vant 支付宝小程序版 |
taroify | Vant Taro 版 |
vant-theme | Vant 在线主题预览工具 |
@antmjs/vantui | 基于 Vant Weapp 开发的多端组件库,同时支持 Taro 和 React |
@formily/vant | 基于 Vant 和 Formily 开发的表单解决方案 |
链接
快速上手
介绍
通过本章节你可以了解到 Vant 的安装方法和基本使用姿势。
安装
通过 npm 安装
在现有项目中使用 Vant 时,可以通过 npm
或 yarn
进行安装:
# Vue 3 项目,安装最新版 Vant:
npm i vant -S
# Vue 2 项目,安装 Vant 2:
npm i vant@latest-v2 -S
脚手架
推荐使用 Rsbuild 来创建一个脚手架项目。
Rsbuild 是基于 Rspack 的构建工具,由 Vant 作者开发,具备一流的构建速度和开发体验,对 Vant 提供第一优先级支持。
你可以通过以下命令创建一个 Rsbuild 项目:
npm create rsbuild@latest
请访问 Rsbuild 仓库 了解更多信息。
通过 CDN 安装
使用 Vant 最简单的方法是直接在 html 文件中引入 CDN 链接,之后你可以通过全局变量 vant
访问到所有组件。
<!-- 引入样式文件 -->
<link rel="stylesheet" href="https://unpkg.com/vant@2.12/lib/index.css" />
<!-- 引入 Vue 和 Vant 的 JS 文件 -->
<script src="https://unpkg.com/vue@2.6/dist/vue.min.js"></script>
<script src="https://unpkg.com/vant@2.12/lib/vant.min.js"></script>
<script>
// 在 #app 标签下渲染一个按钮组件
new Vue({
el: '#app',
template: `<van-button>按钮</van-button>`,
});
// 调用函数组件,弹出一个 Toast
vant.Toast('提示');
// 通过 CDN 引入时不会自动注册 Lazyload 组件
// 可以通过下面的方式手动注册
Vue.use(vant.Lazyload);
</script>
免费 CDN
你可以通过以下免费 CDN 服务来使用 Vant:
注意:免费 CDN 一般用于制作原型或个人小型项目,不推荐在企业生产环境中使用免费 CDN。
对于企业开发者,建议使用以下方式:
- 通过 npm 引入,并通过构建工具进行打包
- 下载对应文件,并托管在你自己的服务器或 CDN 上
通过脚手架安装
在新项目中使用 Vant 时,推荐使用 Vue 官方提供的脚手架 Vue Cli 创建项目并安装 Vant。
# 安装 Vue Cli
npm install -g @vue/cli
# 创建一个项目
vue create hello-world
# 创建完成后,可以通过命令打开图形化界面,如下图所示
vue ui
在图形化界面中,点击 依赖
-> 安装依赖
,然后将 vant
添加到依赖中即可。
示例
示例工程
我们提供了丰富的示例工程,通过示例工程你可以了解如下内容:
- 基于 Vue Cli 和 Vant 搭建应用
- 基于 Nuxt 和 Vant 搭建应用
- 配置按需引入组件
- 配置基于 Rem 的适配方案
- 配置基于 Viewport 的适配方案
- 配置基于 TypeScript 的工程
- 配置自定义主题色方案
引入组件
方式一. 自动按需引入组件 (推荐)
babel-plugin-import 是一款 babel 插件,它会在编译过程中将 import 的写法自动转换为按需引入的方式。
# 安装插件
npm i babel-plugin-import -D
// 在.babelrc 中添加配置
// 注意:webpack 1 无需设置 libraryDirectory
{
"plugins": [
["import", {
"libraryName": "vant",
"libraryDirectory": "es",
"style": true
}]
]
}
// 对于使用 babel7 的用户,可以在 babel.config.js 中配置
module.exports = {
plugins: [
['import', {
libraryName: 'vant',
libraryDirectory: 'es',
style: true
}, 'vant']
]
};
// 接着你可以在代码中直接引入 Vant 组件
// 插件会自动将代码转化为方式二中的按需引入形式
import { Button } from 'vant';
Tips: 如果你在使用 TypeScript,可以使用 ts-import-plugin 实现按需引入。
方式二. 手动按需引入组件
在不使用插件的情况下,可以手动引入需要的组件。
import Button from 'vant/lib/button';
import 'vant/lib/button/style';
方式三. 导入所有组件
Vant 支持一次性导入所有组件,引入所有组件会增加代码包体积,因此不推荐这种做法。
import Vue from 'vue';
import Vant from 'vant';
import 'vant/lib/index.css';
Vue.use(Vant);
Tips: 配置按需引入后,将不允许直接导入所有组件。
常见问题
在 HTML 中无法正确渲染组件?
在 HTML 中使用 Vant 组件时,你可能会碰到部分示例代码无法正确渲染的情况,比如下面的用法:
<van-cell-group>
<van-cell title="单元格" value="内容" />
<van-cell title="单元格" value="内容" />
</van-cell-group>
这是因为 HTML 并不支持自闭合的自定义元素,也就是说 <van-cell />
这样的语法是不被识别的,使用完整的闭合标签可以避免这个问题:
<van-cell-group>
<van-cell title="单元格" value="内容"></van-cell>
<van-cell title="单元格" value="内容"></van-cell>
</van-cell-group>
在单文件组件、字符串模板和 JSX 中可以使用自闭合的自定义元素,因此不会出现这个问题。
进阶用法
介绍
通过本章节你可以了解到 Vant 的一些进阶用法,比如组件插槽用法、多种浏览器适配方式。
组件用法
组件注册
Vant 支持多种组件注册方式,请根据实际业务需要进行选择。
全局注册
全局注册后,你可以在 app 下的任意子组件中使用注册的 Vant 组件。
import Vue from 'vue';
import { Button } from 'vant';
// 方式一. 通过 Vue.use 注册
// 注册完成后,在模板中通过 <van-button> 或 <VanButton> 标签来使用按钮组件
Vue.use(Button);
// 方式二. 通过 Vue.component 注册
// 注册完成后,在模板中通过 <van-button> 标签来使用按钮组件
Vue.component(Button.name, Button);
局部注册
局部注册后,你可以在当前组件中使用注册的 Vant 组件。
import { Button } from 'vant';
export default {
components: {
[Button.name]: Button,
},
};
对于组件注册更详细的介绍,请参考 Vue 官方文档 - 组件注册。
组件插槽
Vant 提供了丰富的组件插槽,通过插槽可以对组件的某一部分进行个性化定制。如果你对 Vue 的插槽不太熟悉,可以阅读 Vue 官方文档中的插槽章节。下面是通过插槽来定制 Checkbox 图标的示例:
<van-checkbox v-model="checked">
<!-- 使用组件提供的 icon 插槽 -->
<!-- 将默认图标替换为个性化图片 -->
<template #icon="props">
<img :src="props.checked ? activeIcon : inactiveIcon" />
</template>
</van-checkbox>
export default {
data() {
return {
checked: true,
activeIcon: 'https://img01.yzcdn.cn/vant/user-active.png',
inactiveIcon: 'https://img01.yzcdn.cn/vant/user-inactive.png',
};
},
};
组件实例方法
Vant 中的许多组件提供了实例方法,调用实例方法时,我们需要通过 ref 来注册组件引用信息,引用信息将会注册在父组件的$refs
对象上。注册完成后,我们可以通过this.$refs.xxx
访问到对应的组件实例,并调用上面的实例方法。
<!-- 通过 ref 属性将组件绑定到 this.$refs.checkbox 上 -->
<van-checkbox v-model="checked" ref="checkbox"> 复选框 </van-checkbox>
export default {
data() {
return {
checked: false,
};
},
// 注意:组件挂载后才能访问到 ref 对象
mounted() {
this.$refs.checkbox.toggle();
},
};
浏览器适配
Viewport 布局
Vant 默认使用 px
作为样式单位,如果需要使用 viewport
单位 (vw, vh, vmin, vmax),推荐使用 postcss-px-to-viewport 进行转换。
postcss-px-to-viewport 是一款 PostCSS 插件,用于将 px 单位转化为 vw/vh 单位。
PostCSS PostCSS 示例配置
下面提供了一份基本的 PostCSS 示例配置,可以在此配置的基础上根据项目需求进行修改。
// postcss.config.js
module.exports = {
plugins: {
'postcss-px-to-viewport': {
viewportWidth: 375,
},
},
};
Tips: 在配置 postcss-loader 时,应避免 ignore node_modules 目录,否则将导致 Vant 样式无法被编译。
Rem 布局适配
如果需要使用 rem
单位进行适配,推荐使用以下两个工具:
- postcss-pxtorem 是一款 PostCSS 插件,用于将 px 单位转化为 rem 单位
- lib-flexible 用于设置 rem 基准值
PostCSS 示例配置
下面提供了一份基本的 PostCSS 示例配置,可以在此配置的基础上根据项目需求进行修改。
// postcss.config.js
module.exports = {
plugins: {
'postcss-pxtorem': {
rootValue: 37.5,
propList: ['*'],
},
},
};
其他设计稿尺寸
如果设计稿的尺寸不是 375,而是 750 或其他大小,可以将 rootValue
配置调整为:
// postcss.config.js
module.exports = {
plugins: {
// postcss-pxtorem 插件的版本需要 >= 5.0.0
'postcss-pxtorem': {
rootValue({ file }) {
return file.indexOf('vant') !== -1 ? 37.5 : 75;
},
propList: ['*'],
},
},
};
桌面端适配
Vant 是一个面向移动端的组件库,因此默认只适配了移动端设备,这意味着组件只监听了移动端的 touch
事件,没有监听桌面端的 mouse
事件。
如果你需要在桌面端使用 Vant,可以引入我们提供的 @vant/touch-emulator,这个库会在桌面端自动将 mouse
事件转换成对应的 touch
事件,使得组件能够在桌面端使用。
# 安装模块
npm i @vant/touch-emulator -S
// 引入模块后自动生效
import '@vant/touch-emulator';
底部安全区适配
iPhone X 等机型底部存在底部指示条,指示条的操作区域与页面底部存在重合,容易导致用户误操作,因此我们需要针对这些机型进行安全区适配。Vant 中部分组件提供了 safe-area-inset-top
或 safe-area-inset-bottom
属性,设置该属性后,即可在对应的机型上开启适配,如下示例:
<!-- 在 head 标签中添加 meta 标签,并设置 viewport-fit=cover 值 -->
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
/>
<!-- 开启顶部安全区适配 -->
<van-nav-bar safe-area-inset-top />
<!-- 开启底部安全区适配 -->
<van-number-keyboard safe-area-inset-bottom />