介绍

Vant 提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以使用下面提供的方法。

示例工程

我们提供了一个基于 Vue Cli 3 的示例工程，仓库地址为 Vant Demo，其中包含了定制主题的基本配置，可以作为参考。

样式变量

Vant 使用了 Less 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。

下面是一些基本的样式变量，所有可用的颜色变量请参考 配置文件。

// Component Colors@text-color: #323233;@border-color: #ebedf0;@active-color: #f2f3f5;@background-color: #f7f8fa;@background-color-light: #fafafa;

定制方法

步骤一 引入样式源文件

定制主题时，需要引入组件对应的 Less 样式文件，支持按需引入和手动引入两种方式。

按需引入样式（推荐）

在 babel.config.js 中配置按需引入样式源文件，注意 babel6 不支持按需引入样式，请手动引入样式

module.exports = {  plugins: [    [      'import',      {        libraryName: 'vant',        libraryDirectory: 'es',        // 指定样式路径        style: name => `${name}/style/less`      },      'vant'    ]  ]};

手动引入样式

// 引入全部样式import 'vant/lib/index.less';// 引入单个组件样式import 'vant/lib/button/style/less';

步骤二 修改样式变量

使用 Less 提供的 modifyVars 即可对变量进行修改，下面是参考的 webpack 配置。

// webpack.config.jsmodule.exports = {  rules: [    {      test: /.less$/,      use: [        // ...其他 loader 配置        {          loader: 'less-loader',          options: {            modifyVars: {              // 直接覆盖变量              'text-color': '#111',              'border-color': '#eee'              // 或者可以通过 less 文件覆盖（文件路径为绝对路径）              'hack': `true; @import "your-less-file-path.less";`            }          }        }      ]    }  ]};

介绍

感谢你使用 Vant。

以下是关于向 Vant 提交反馈或代码的指南。在向 Vant 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下文字。

Issue 规范

• 遇到问题时，请先确认这个问题是否已经在 issue 中有记录或者已被修复
• 提 issue 时，请用简短的语言描述遇到的问题，并添加出现问题时的环境和复现步骤

参与开发

本地开发

按照下面的步骤操作，即可在本地开发 Vant 组件

# 克隆仓库git clone git@github.com:youzan/vant.git# 安装依赖cd vant && npm run bootstrap# 进入开发模式，浏览器访问 http://localhost:8080npm run dev

目录结构

• 仓库的组件代码位于 src 下，每个组件一个文件夹
• docs 目录下是文档网站的代码，本地开发时可以在目录下运行 npm run dev 开启文档网站

项目主要目录如下：

vant├─ build     # 构建├─ docs      # 文档├─ src       # 组件├─ packages  # 子包├─ test      # 单测└─ types     # 类型

添加新组件

添加新组件时，请按照下面的目录结构组织文件，并在 vant.config.js 中配置组件名称

src└─ button   ├─ demo             # 示例代码   ├─ test             # 单元测试   ├─ index.js         # 组件入口   ├─ index.less       # 组件样式   ├─ README.md        # 英文文档   └─ README.zh-CN.md  # 中文文档

提交 PR

Pull Request 规范

• 如果遇到问题，建议保持你的 PR 足够小。保证一个 PR 只解决一个问题或只添加一个功能
• 当新增组件或者修改原有组件时，记得增加或者修改测试代码，保证代码的稳定
• 在 PR 中请添加合适的描述，并关联相关的 Issue

Pull Request 流程

1. fork 主仓库，如果已经 fork 过，请同步主仓库的最新代码
2. 基于 fork 后仓库的 dev 分支新建一个分支，比如feature/button_color
3. 在新分支上进行开发，开发完成后，提 Pull Request 到主仓库的 dev 分支
4. Pull Request 会在 Review 通过后被合并到主仓库
5. 等待 Vant 发布版本，一般是每周一次

同步最新代码

提 Pull Request 前，请依照下面的流程同步主仓库的最新代码

# 添加主仓库到 remote，作为 fork 后仓库的上游仓库git remote add upstream https://github.com/youzan/vant.git# 拉取主仓库最新代码git fetch upstream# 切换至 dev 分支git checkout dev# 合并主仓库代码git merge upstream/dev

介绍

这里提供了 Vant 现有的设计资源，更多资源还在整理中。

组件

包含 Sketch 格式的组件设计规范、色彩规范。

下载

提示：目前 Sketch 中部分组件仍为旧版样式，我们正在梳理新版设计规范，尽请期待！

图标

包含 Sketch 格式的图标库资源。

下载

介绍

在参与 Vant 开发时，请遵守约定的单文件组件风格指南，指南内容节选自 Vue 官方风格指南。

组件数据

组件的 data 必须是一个函数。

// badexport default {  data: {    foo: 'bar'  }}// goodexport default {  data () {    return {      foo: 'bar'    }  }}

单文件组件文件名称

单文件组件的文件名应该要么始终是单词大写开头 (PascalCase)，要么始终是横线连接 (kebab-case)。

// badmycomponent.vuemyComponent.vue// goodmy-component.vueMyComponent.vue

紧密耦合的组件名

和父组件紧密耦合的子组件应该以父组件名作为前缀命名。

// badcomponents/|- TodoList.vue|- TodoItem.vue└─ TodoButton.vue// goodcomponents/|- TodoList.vue|- TodoListItem.vue└─ TodoListItemButton.vue

自闭合组件

在单文件组件中没有内容的组件应该是自闭合的。

<!-- bad --><my-component></my-component><!-- good --><my-component />

Prop 名大小写

在声明 prop 的时候，其命名应该始终使用 camelCase，而在模板中应该始终使用 kebab-case。

// badexport default {  props: {    'greeting-text': String  }};// goodexport default {  props: {    greetingText: String  }}

<!-- bad --><welcome-message greetingText="hi" /><!-- good --><welcome-message greeting-text="hi" />

Props 换行

多个 Props 的元素应该分多行撰写，每个 Props 一行，闭合标签单起一行。

<!-- bad --><my-component foo="a" bar="b" baz="c" /><!-- good --><my-component  foo="a"  bar="b"  baz="c"/>

指令缩写

指令缩写，用 : 表示 v-bind: ，用 @ 表示 v-on:

<!-- bad --><input  v-bind:value="value"  v-on:input="onInput"><!-- good --><input  :value="value"  @input="onInput">

Props 顺序

标签的 Props 应该有统一的顺序，依次为指令、属性和事件。

<my-component  v-if="if"  v-show="show"  v-model="value"  ref="ref"  :key="key"  :text="text"  @input="onInput"  @change="onChange"/>

组件选项的顺序

组件选项应该有统一的顺序。

export default {  name: '',  mixins: [],  components: {},  props: {},  data() {},  computed: {},  watch: {},  created() {},  mounted() {},  destroyed() {},  methods: {}};

组件选项中的空行

组件选项较多时，建议在属性之间添加空行。

export default {  computed: {    formattedValue() {      // ...    },    styles() {      // ...    }  },  methods: {    onInput() {      // ...    },    onChange() {      // ...    }  }};

单文件组件顶级标签的顺序

单文件组件应该总是让顶级标签的顺序保持一致，且标签之间留有空行。

<template>...</template><script>/* ... */</script><style>/* ... */</style>

介绍

Vant 默认采用中文作为语言，如果需要使用其他语言，可以参考下面的方案。

多语言切换

Vant 通过 Locale 组件实现多语言支持，使用 Locale.use 方法可以切换当前使用的语言。

import { Locale } from 'vant';import enUS from 'vant/lib/locale/lang/en-US';Locale.use('en-US', enUS);

修改默认文案

通过 Locale.add 方法可以实现文案的修改和扩展，示例如下：

import { Locale } from 'vant';const messages = {  'zh-CN': {    vanPicker: {      confirm: '关闭' // 将'确认'修改为'关闭'    }  }};Locale.add(messages);

配置文件

目前支持的语言:

在 这里 查看所有的 i18n 配置文件。

Sku 组件

语言包中默认不包含 Sku 业务组件的语言配置，因此如果有 Sku 组件的国际化需求，请自行配置国际化文案。

引入

import Vue from 'vue';import { Button } from 'vant';Vue.use(Button);

代码演示

按钮类型

支持default、primary、info、warning、danger五种类型，默认为default

<van-button type="default">默认按钮</van-button><van-button type="primary">主要按钮</van-button><van-button type="info">信息按钮</van-button><van-button type="warning">警告按钮</van-button><van-button type="danger">危险按钮</van-button>

朴素按钮

通过plain属性将按钮设置为朴素按钮，朴素按钮的文字为按钮颜色，背景为白色。

<van-button plain type="primary">朴素按钮</van-button><van-button plain type="info">朴素按钮</van-button>

细边框

设置hairline属性可以开启 0.5px 边框，基于伪类实现

<van-button plain hairline type="primary">细边框按钮</van-button><van-button plain hairline type="info">细边框按钮</van-button>

禁用状态

通过disabled属性来禁用按钮，禁用状态下按钮不可点击

<van-button disabled type="primary">禁用状态</van-button><van-button disabled type="info">禁用状态</van-button>

加载状态

通过loading属性设置按钮为加载状态，加载状态下默认会隐藏按钮文字，可以通过loading-text设置加载状态下的文字

<van-button loading type="primary" /><van-button loading type="primary" loading-type="spinner" /><van-button loading type="info" loading-text="加载中..." />

按钮形状

通过square设置方形按钮，通过round设置圆形按钮

<van-button square type="primary">方形按钮</van-button><van-button round type="info">圆形按钮</van-button>

图标按钮

通过icon属性设置按钮图标，支持 Icon 组件里的所有图标，也可以传入图标 URL

<van-button icon="star-o" type="primary" /><van-button icon="star-o" type="primary">按钮</van-button><van-button icon="https://img.yzcdn.cn/vant/logo.png" type="info">按钮</van-button>

按钮尺寸

支持large、normal、small、mini四种尺寸，默认为normal

<van-button type="primary" size="large">大号按钮</van-button><van-button type="primary" size="normal">普通按钮</van-button><van-button type="primary" size="small">小型按钮</van-button><van-button type="primary" size="mini">迷你按钮</van-button>

块级元素

按钮在默认情况下为行内块级元素，通过block属性可以将按钮的元素类型设置为块级元素

<van-button type="primary" block>块级元素</van-button>

页面导航

可以通过url属性进行 URL 跳转，或通过to属性进行路由跳转

<van-button type="primary" url="/vant/mobile.html">URL 跳转</van-button><van-button type="primary" to="index">路由跳转</van-button>

自定义颜色

通过color属性可以自定义按钮的颜色

<van-button color="#7232dd">单色按钮</van-button><van-button color="#7232dd" plain>单色按钮</van-button><van-button color="linear-gradient(to right, #4bb0ff, #6149f6)">渐变色按钮</van-button>

API

Props

Events

以下是一个简单示例：

<!DOCTYPE html><html lang="zh"><head>  <meta charset="UTF-8" />  <meta name="viewport" content="width=device-width, initial-scale=1.0" />  <meta http-equiv="X-UA-Compatible" content="ie=edge" />  <title>W3Cschool(51coolma.cn)</title>  <!-- 引入样式 -->  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vant@2.10/lib/index.css" rel="external nofollow" target="_blank"  />  <!-- 引入组件 -->  <script src="https://cdn.jsdelivr.net/npm/vue@2.6/dist/vue.min.js" rel="external nofollow" ></script>  <script src="https://cdn.jsdelivr.net/npm/vant@2.10/lib/vant.min.js" rel="external nofollow" ></script></head><body>  <div id="app">    <div>      <p>按钮类型</p>      <van-button type="primary">主要按钮</van-button>      <van-button type="info">信息按钮</van-button>      <van-button type="default">默认按钮</van-button>      <van-button type="danger">危险按钮</van-button>      <van-button type="warning">警告按钮</van-button>    </div>    <div>      <p>朴素按钮</p>      <van-button plain type="primary">朴素按钮</van-button>      <van-button plain type="info">朴素按钮</van-button>    </div>    <div>      <p>细边框</p>      <van-button plain hairline type="primary">细边框按钮</van-button>      <van-button plain hairline type="info">细边框按钮</van-button>    </div>    <div>      <p>禁用状态</p>      <van-button disabled type="primary">禁用状态</van-button>      <van-button disabled type="info">禁用状态</van-button>    </div>    <div>      <p>加载状态</p>      <van-button loading type="primary" />      <van-button loading type="primary" loading-type="spinner" />      <van-button loading type="info" loading-text="加载中..." />    </div>    <div>      <p>按钮形状</p>      <van-button square type="primary">方形按钮</van-button>      <van-button round type="info">圆形按钮</van-button>    </div>  </div></body><script>  var app = new Vue({    el: '#app',    data: {    },    methods: {    },    created() {    },  })</script></html>

引入

import Vue from 'vue';import { Cell, CellGroup } from 'vant';Vue.use(Cell);Vue.use(CellGroup);

代码演示

基础用法

Cell可以单独使用，也可以与CellGroup搭配使用。CellGroup可以为Cell提供上下外边框

<van-cell-group>  <van-cell title="单元格" value="内容" />  <van-cell title="单元格" value="内容" label="描述信息" /></van-cell-group>

单元格大小

通过size属性可以控制单元格的大小

<van-cell title="单元格" value="内容" size="large" /><van-cell title="单元格" value="内容" size="large" label="描述信息" />

展示图标

通过icon属性在标题左侧展示图标

<van-cell title="单元格" icon="location-o" />

只设置 value

只设置value时，内容会靠左对齐

<van-cell value="内容" />

展示箭头

设置is-link属性后会在单元格右侧显示箭头，并且可以通过arrow-direction属性控制箭头方向

<van-cell title="单元格" is-link /><van-cell title="单元格" is-link value="内容" /><van-cell title="单元格" is-link arrow-direction="down" value="内容" />

页面导航

可以通过url属性进行 URL 跳转，或通过to属性进行路由跳转

<van-cell title="URL 跳转" is-link url="/vant/mobile.html" /><van-cell title="路由跳转" is-link to="index" />

分组标题

通过CellGroup的title属性可以指定分组标题

<van-cell-group title="分组1">  <van-cell title="单元格" value="内容" /></van-cell-group><van-cell-group title="分组2">  <van-cell title="单元格" value="内容" /></van-cell-group>

使用插槽

如以上用法不能满足你的需求，可以使用插槽来自定义内容

<van-cell value="内容" is-link>  <!-- 使用 title 插槽来自定义标题 -->  <template slot="title">    <span class="custom-title">单元格</span>    <van-tag type="danger">标签</van-tag>  </template></van-cell><van-cell title="单元格" icon="shop-o">  <!-- 使用 right-icon 插槽来自定义右侧图标 -->  <van-icon    slot="right-icon"    name="search"    style="line-height: inherit;"  /></van-cell>

垂直居中

通过center属性可以让Cell的左右内容都垂直居中

<van-cell center title="单元格" value="内容" label="描述信息" />

API

CellGroup Props

Cell Props

Cell Events

CellGroup Slots

Cell Slots

介绍

基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过icon属性引用

引入

import Vue from 'vue';import { Icon } from 'vant';Vue.use(Icon);

代码演示

基础用法

Icon的name属性支持传入图标名称或图片链接，所有可用的图标名称见右侧示例

<van-icon name="chat-o" /><van-icon name="https://b.yzcdn.cn/vant/icon-demo-1126.png" />

提示信息

设置dot属性后，会在图标右上角展示一个小红点。设置info属性后，会在图标右上角展示相应的徽标

<van-icon name="chat-o" dot /><van-icon name="chat-o" info="9" /><van-icon name="chat-o" info="99+" />

图标颜色

Icon的color属性用来设置图标的颜色

<van-icon name="chat-o" color="#1989fa" /><van-icon name="chat-o" color="#07c160" />

图标大小

Icon的size属性用来设置图标的尺寸大小，默认单位为px

<van-icon name="chat-o" size="40" /><van-icon name="chat-o" size="3rem" />

使用本地字体文件

Icon 组件默认引用有赞 CDN 提供的字体文件，并通过网络下载。如果需要在项目中使用本地字体文件，请引入下面的 CSS 文件，并在项目中配置url-loader

import 'vant/lib/icon/local.css';

自定义图标

如果需要在现有 Icon 的基础上使用更多图标，可以引入第三方 iconfont 对应的字体文件和 CSS 文件，之后就可以在 Icon 组件中直接使用

/* 引入第三方或自定义的字体图标样式 */@font-face {  font-family: 'my-icon';  src: url('./my-icon.ttf') format('truetype');}.my-icon {  font-family: 'my-icon';}.my-icon-extra::before {  content: 'e626';}

<!-- 通过 class-prefix 指定类名为 my-icon --><van-icon class-prefix="my-icon" name="extra" />

API

Props

Events

介绍

增强版的 img 标签，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示

引入

import Vue from 'vue';import { Image } from 'vant';Vue.use(Image);

代码演示

基础用法

基础用法与原生img标签一致，可以设置src、width、height、alt等原生属性

<van-image  width="100"  height="100"  src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" />

填充模式

通过fit属性可以设置图片填充模式，可选值见下方表格

<van-image  width="10rem"  height="10rem"  fit="contain"  src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" />

圆形图片

通过round属性可以设置图片变圆，注意当图片宽高不相等且fit为contain或scale-down时，将无法填充一个完整的圆形。

<van-image  round  width="10rem"  height="10rem"  src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" />

图片懒加载

设置lazy-load属性来开启图片懒加载，需要搭配 Lazyload 组件使用

<van-image  width="100"  height="100"  lazy-load  src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" />

import Vue from 'vue';import { Lazyload } from 'vant';Vue.use(Lazyload);

加载中提示

Image组件提供了默认的加载中提示，支持通过loading插槽自定义内容

<van-image src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >  <template v-slot:loading>    <van-loading type="spinner" size="20" />  </template></van-image>

加载失败提示

Image组件提供了默认的加载失败提示，支持通过error插槽自定义内容

<van-image src="https://img.yzcdn.cn/vant/cat.jpeg" rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow"  rel="external nofollow" >  <template v-slot:error>加载失败</template></van-image>

API

Props

图片填充模式

Events

Slots

介绍

Layout 提供了van-row和van-col两个组件来进行行列布局

引入

import Vue from 'vue';import { Col, Row } from 'vant';Vue.use(Col);Vue.use(Row);

代码演示

基本用法

Layout 组件提供了24列栅格，通过在Col上添加span属性设置列所占的宽度百分比此外，添加offset属性可以设置列的偏移宽度，计算方式与 span 相同

<van-row>  <van-col span="8">span: 8</van-col>  <van-col span="8">span: 8</van-col>  <van-col span="8">span: 8</van-col></van-row><van-row>  <van-col span="4">span: 4</van-col>  <van-col span="10" offset="4">offset: 4, span: 10</van-col></van-row><van-row>  <van-col offset="12" span="12">offset: 12, span: 12</van-col></van-row>

设置列元素间距

通过gutter属性可以设置列元素之间的间距，默认间距为 0

<van-row gutter="20">  <van-col span="8">span: 8</van-col>  <van-col span="8">span: 8</van-col>  <van-col span="8">span: 8</van-col></van-row>

Flex 布局

将 type 属性设置为 flex 可以启用 flex 布局，便于进行灵活的对齐

<!-- 左对齐 --><van-row type="flex">  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col></van-row><!-- 居中 --><van-row type="flex" justify="center">  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col></van-row><!-- 右对齐 --><van-row type="flex" justify="end">  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col></van-row><!-- 两端对齐 --><van-row type="flex" justify="space-between">  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col></van-row><!-- 每个元素的两侧间隔相等 --><van-row type="flex" justify="space-around">  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col>  <van-col span="6">span: 6</van-col></van-row>

API

Row Props

Col Props

Row Events

Col Events

实例演示

代码：

<body ontouchstart="">    <div>        <div class="demo-nav" style="">            <div class="demo-nav__title">Col</div>            <svg viewBox="0 0 1000 1000" class="demo-nav__back">                <path fill="#969799" fill-rule="evenodd" d="M296.114 508.035c-3.22-13.597.473-28.499 11.079-39.105l333.912-333.912c16.271-16.272 42.653-16.272 58.925 0s16.272 42.654 0 58.926L395.504 498.47l304.574 304.574c16.272 16.272 16.272 42.654 0 58.926s-42.654 16.272-58.926 0L307.241 528.058a41.472 41.472 0 0 1-11.127-20.023z"></path>            </svg>        </div>        <section class="van-doc-demo-section demo-col">            <div class="van-doc-demo-block">                <h2 class="van-doc-demo-block__title">基础用法</h2>                <div class="van-row"><div class="van-col van-col--8">span: 8</div>                <div class="van-col van-col--8">span: 8</div>                <div class="van-col van-col--8">span: 8</div>            </div>            <div class="van-row">                <div class="van-col van-col--4">span: 4</div>                <div class="van-col van-col--10 van-col--offset-4"> offset: 4, span: 10</div>            </div>            <div class="van-row">                <div class="van-col van-col--12 van-col--offset-12">offset: 12, span: 12</div>            </div>            <div class="van-doc-demo-block">                <h2 class="van-doc-demo-block__title">在列元素之间增加间距</h2>                <div class="van-row">                    <div class="van-col van-col--8" style="padding-right: 13.3333px;">span: 8</div>                    <div class="van-col van-col--8" style="padding-left: 6.66667px; padding-right: 6.66667px;">span: 8</div>                    <div class="van-col van-col--8" style="padding-left: 13.3333px; padding-right: 1.77636e-15px;">span: 8</div>                </div>            </div>            <div class="van-doc-demo-block">                <h2 class="van-doc-demo-block__title">Flex 布局</h2>                <div class="van-row van-row--flex">                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                </div>                <div class="van-row van-row--flex van-row--justify-center">                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                </div>                <div class="van-row van-row--flex van-row--justify-end">                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                </div>                <div class="van-row van-row--flex van-row--justify-space-between">                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                </div>                <div class="van-row van-row--flex van-row--justify-space-around">                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                    <div class="van-col van-col--6">span: 6</div>                </div>            </div>        </section>    </div><script src="https://b.yzcdn.cn/vant/async_chunks.a839cbb5.js" rel="external nofollow" ></script><script src="https://b.yzcdn.cn/vant/site-mobile.ea70a230.js" rel="external nofollow" ></script></body>

运行效果：

介绍

弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示

引入

import Vue from 'vue';import { Popup } from 'vant';Vue.use(Popup);

代码演示

基础用法

通过v-model控制弹出层是否展示

<van-cell is-link @click="showPopup">展示弹出层</van-cell><van-popup v-model="show">内容</van-popup>

export default {  data() {    return {      show: false    }  },  methods: {    showPopup() {      this.show = true;    }  }};

弹出位置

通过position属性设置弹出位置，默认居中弹出，可以设置为top、bottom、left、right

<van-popup  v-model="show"  position="top"  :style="{ height: '20%' }"/>

关闭图标

设置closeable属性后，会在弹出层的右上角显示关闭图标，并且可以通过close-icon属性自定义图标，使用close-icon-position属性可以自定义图标位置

<van-popup  v-model="show"  closeable  position="bottom"  :style="{ height: '20%' }"/><!-- 自定义图标 --><van-popup  v-model="show"  closeable  close-icon="close"  position="bottom"  :style="{ height: '20%' }"/><!-- 图标位置 --><van-popup  v-model="show"  closeable  close-icon-position="top-left"  position="bottom"  :style="{ height: '20%' }"/>

圆角弹窗

设置round属性后，弹窗会根据弹出位置添加不同的圆角样式

<van-popup  v-model="show"  round  position="bottom"  :style="{ height: '20%' }"/>

指定挂载位置

弹出层默认挂载到组件所在位置，可以通过get-container属性指定挂载位置

<!-- 挂载到 body 节点下 --><van-popup v-model="show" get-container="body" /><!-- 挂载到 #app 节点下 --><van-popup v-model="show" get-container="#app" /><!-- 通过函数指定挂载位置 --><van-popup v-model="show" :get-container="getContainer" />

export default {  methods: {    // 返回一个特定的 DOM 节点，作为挂载的父节点    getContainer() {      return document.querySelector('.my-container');    }  }}

注意：使用 get-container 属性的组件不能为根节点

API

Props

Events

介绍

Vant 中默认包含了一些常用样式，可以直接通过 className 的方式使用。

文字省略

当文本内容长度超过容器最大宽度时，自动省略多余的文本。

<!-- 最多显示一行 --><div class="van-ellipsis">这是一段最多显示一行的文字，多余的内容会被省略</div><!-- 最多显示两行 --><div class="van-multi-ellipsis--l2">这是一段最多显示两行的文字，多余的内容会被省略</div><!-- 最多显示三行 --><div class="van-multi-ellipsis--l3">这是一段最多显示三行的文字，多余的内容会被省略</div>

1px 边框

为元素添加 Retina 屏幕下的 1px 边框（即 hairline），基于伪类 transform 实现。

<!-- 上边框 --><div class="van-hairline--top"></div><!-- 下边框 --><div class="van-hairline--bottom"></div><!-- 左边框 --><div class="van-hairline--left"></div><!-- 右边框 --><div class="van-hairline--right"></div><!-- 上下边框 --><div class="van-hairline--top-bottom"></div><!-- 全边框 --><div class="van-hairline--surround"></div>

动画

可以通过 transition 组件使用内置的动画

<!-- 淡入 --><transition name="van-fade">  <div v-show="visible">Fade</div></transition><!-- 上滑进入 --><transition name="van-slide-up">  <div v-show="visible">Slide Up</div></transition><!-- 下滑进入 --><transition name="van-slide-down">  <div v-show="visible">Slide Down</div></transition><!-- 左滑进入 --><transition name="van-slide-left">  <div v-show="visible">Slide Left</div></transition><!-- 右滑进入 --><transition name="van-slide-right">  <div v-show="visible">Slide Right</div></transition>

介绍

日历组件用于选择日期或日期区间，2.4 版本开始支持此组件

引入

import Vue from 'vue';import { Calendar } from 'vant';Vue.use(Calendar);

代码演示

选择单个日期

下面演示了结合单元格来使用日历组件的用法，日期选择完成后会触发confirm事件

<van-cell title="选择单个日期" :value="date" @click="show = true" /><van-calendar v-model="show" @confirm="onConfirm" />

export default {  data() {    return {      date: '',      show: false    };  },  methods: {    formatDate(date) {      return `${date.getMonth() + 1}/${date.getDate()}`;    },    onConfirm(date) {      this.show = false;      this.date = this.formatDate(date);    }  }};

选择日期区间

设置type为range后可以选择日期区间，此时confirm事件返回的 date 为数组结构，数组第一项为开始时间，第二项为结束时间。

<van-cell title="选择日期区间" :value="date" @click="show = true" /><van-calendar v-model="show" type="range" @confirm="onConfirm" />

export default {  data() {    return {      date: '',      show: false    };  },  methods: {    formatDate(date) {      return `${date.getMonth() + 1}/${date.getDate()}`;    },    onConfirm(date) {      const [start, end] = date;      this.show = false;      this.date = `${this.formatDate(start)} - ${this.formatDate(end)}`;    }  }};

快捷选择

将show-confirm设置为false可以隐藏确认按钮，这种情况下选择完成后会立即触发confirm事件

<van-calendar v-model="show" :show-confirm="false" />

自定义颜色

通过color属性可以自定义日历的颜色，对选中日期和底部按钮生效

<van-calendar v-model="show" color="#07c160" />

自定义日期范围

通过min-date和max-date定义日历的范围

<van-calendar  v-model="show"  :min-date="minDate"  :max-date="maxDate"/>

export default {  data() {    return {      show: false,      minDate: new Date(2010, 0, 1),      maxDate: new Date(2010, 0, 31)    };  }};

自定义按钮文字

通过confirm-text设置按钮文字，通过confirm-disabled-text设置按钮禁用时的文字

<van-calendar  v-model="show"  type="range"  confirm-text="完成"  confirm-disabled-text="请选择结束时间"/>

自定义日期文案

通过传入formatter函数来对日历上每一格的内容进行格式化

<van-calendar  v-model="show"  type="range"  :formatter="formatter"/>

export default {  methods: {    formatter(day) {      const month = day.date.getMonth() + 1;      const date = day.date.getDate();      if (month === 5) {        if (date === 1) {          day.topInfo = '劳动节';        } else if (date === 4) {          day.topInfo = '五四青年节';        } else if (date === 11) {          day.text = '今天';        }      }      if (day.type === 'start') {        day.bottomInfo = '入住';      } else if (day.type === 'end') {        day.bottomInfo = '离店';      }      return day;    }  }}

自定义弹出位置

通过position属性自定义弹出层的弹出位置，可选值为top、left、right

<van-calendar  v-model="show"  :round="false"  position="right"/>

日期区间最大范围

选择日期区间时，可以通过max-range属性来指定最多可选天数，选择的范围超过最多可选天数时，会弹出相应的提示文案

<van-calendar  type="range"  :max-range="3"  :style="{ height: '500px' }"/>

平铺展示

将poppable设置为false，日历会直接展示在页面内，而不是以弹层的形式出现

<van-calendar  title="日历"  :poppable="false"  :show-confirm="false"  :style="{ height: '500px' }"/>

API

Props

Day 数据结构

日历中的每个日期都对应一个 Day 对象，通过formatter属性可以自定义 Day 对象的内容

Events

Slots

方法

通过 ref 可以获取到 Calendar 实例并调用实例方法，详见 组件实例方法

常见问题

在 iOS 系统上初始化组件失败？

如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。

对此问题的详细解释：stackoverflow。

引入

import Vue from 'vue';import { Checkbox, CheckboxGroup } from 'vant';Vue.use(Checkbox);Vue.use(CheckboxGroup);

代码演示

基础用法

通过v-model绑定复选框的勾选状态

<van-checkbox v-model="checked">复选框</van-checkbox>

export default {  data() {    return {      checked: true    };  }};

禁用状态

通过设置disabled属性可以禁用复选框

<van-checkbox v-model="checked" disabled>复选框</van-checkbox>

禁用文本点击

设置icon-disabled属性后，点击复选框图标以外的内容不会触发切换

<van-checkbox v-model="checked" icon-disabled>复选框</van-checkbox>

自定义形状

将shape属性设置为square，复选框的形状会变成方形

<van-checkbox v-model="checked" shape="square">复选框</van-checkbox>

自定义颜色

通过checked-color属性可以自定义选中状态下的图标颜色

<van-checkbox v-model="checked" checked-color="#07c160">复选框</van-checkbox>

自定义大小

通过icon-size属性可以自定义图标的大小

<van-checkbox v-model="checked" icon-size="24px">复选框</van-checkbox>

自定义图标

通过 icon 插槽自定义图标，可以通过slotProps判断是否为选中状态

<van-checkbox v-model="checked">  自定义图标  <img    slot="icon"    slot-scope="props"    :src="props.checked ? activeIcon : inactiveIcon"  ></van-checkbox>

export default {  data() {    checked: true,    activeIcon: 'https://img.yzcdn.cn/vant/user-active.png',    inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png'  }}

复选框组

复选框可以与复选框组一起使用，选中值是一个数组，通过v-model绑定在CheckboxGroup上，数组中的值为选中的复选框的name

<van-checkbox-group v-model="result">  <van-checkbox name="a">复选框 a</van-checkbox>  <van-checkbox name="b">复选框 b</van-checkbox>  <van-checkbox name="c">复选框 c</van-checkbox></van-checkbox-group>

export default {  data() {    return {      result: ['a', 'b']    };  }};

设置最大可选数

通过max属性可以限制最大可选数

<van-checkbox-group v-model="result" :max="2">  <van-checkbox name="a">复选框 a</van-checkbox>  <van-checkbox name="b">复选框 b</van-checkbox>  <van-checkbox name="c">复选框 c</van-checkbox></van-checkbox-group>

全选与反选

通过CheckboxGroup实例上的toggleAll方法可以实现全选与反选

<van-checkbox-group v-model="result" ref="checkboxGroup">  <van-checkbox name="a">复选框 a</van-checkbox>  <van-checkbox name="b">复选框 b</van-checkbox>  <van-checkbox name="c">复选框 c</van-checkbox></van-checkbox-group><van-button type="primary" @click="checkAll">全选</van-button><van-button type="info" @click="toggleAll">反选</van-button>

export default {  data() {    return {      result: []    }  },  methods: {    checkAll() {      this.$refs.checkboxGroup.toggleAll(true);    },    toggleAll() {      this.$refs.checkboxGroup.toggleAll();    }  }}

搭配单元格组件使用

此时你需要再引入Cell和CellGroup组件，并通过Checkbox实例上的 toggle 方法触发切换

<van-checkbox-group v-model="result">  <van-cell-group>    <van-cell      v-for="(item, index) in list"      clickable      :key="item"      :title="`复选框 ${item}`"      @click="toggle(index)"    >      <van-checkbox        :name="item"        ref="checkboxes"        slot="right-icon"      />    </van-cell>  </van-cell-group></van-checkbox-group>

export default {  methods: {    toggle(index) {      this.$refs.checkboxes[index].toggle();    }  }}

API

Checkbox Props

CheckboxGroup Props

Checkbox Events

CheckboxGroup Events

Checkbox Slots

CheckboxGroup 方法

通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法，详见 组件实例方法

Checkbox 方法

通过 ref 可以获取到 Checkbox 实例并调用实例方法，详见 组件实例方法

介绍

时间选择器，支持日期、年月、时分等维度，通常与 弹出层 组件配合使用

引入

import Vue from 'vue';import { DatetimePicker } from 'vant';Vue.use(DatetimePicker);

代码演示

选择完整时间

<van-datetime-picker  v-model="currentDate"  type="datetime"  :min-date="minDate"  :max-date="maxDate"/>

export default {  data() {    return {      minDate: new Date(2020, 0, 1),      maxDate: new Date(2025, 10, 1),      currentDate: new Date()    };  }};

选择日期（年月日）

<van-datetime-picker  v-model="currentDate"  type="date"  :min-date="minDate"  :max-date="maxDate"/>

export default {  data() {    return {      minDate: new Date(2020, 0, 1),      maxDate: new Date(2025, 10, 1),      currentDate: new Date()    };  }};

选择日期（年月）

通过传入formatter函数，可以对选项文字进行格式化处理

<van-datetime-picker  v-model="currentDate"  type="year-month"  :min-date="minDate"  :max-date="maxDate"  :formatter="formatter"/>

export default {  data() {    return {      minDate: new Date(2020, 0, 1),      maxDate: new Date(2025, 10, 1),      currentDate: new Date()    };  },  methods: {    formatter(type, val) {      if (type === 'year') {        return `${val}年`;      } else if (type === 'month') {        return `${val}月`      }      return val;    }  }}

选择时间

<van-datetime-picker  v-model="currentTime"  type="time"  :min-hour="10"  :max-hour="20"/>

export default {  data() {    return {      currentTime: '12:00'    };  }};

选项过滤器

通过传入filter函数，可以对选项数组进行过滤，实现自定义时间间隔

<van-datetime-picker  v-model="currentTime"  type="time"  :filter="filter"/>

export default {  data() {    return {      currentTime: '12:00'    };  },  methods: {    filter(type, options) {      if (type === 'minute') {        return options.filter(option => option % 5 === 0);      }      return options;    }  }};

API

Props

DatePicker Props

当时间选择器类型为 date 或 datetime 时，支持以下 props

TimePicker Props

当时间选择器类型为 time 时，支持以下 props

Events

方法

通过 ref 可以获取到 DatetimePicker 实例并调用实例方法，详见 组件实例方法

常见问题

设置 min-date 或 max-date 后出现页面卡死的情况？

请注意不要在模板中直接使用类似min-date="new Date()"的写法，这样会导致每次渲染组件时传入一个新的 Date 对象，而传入新的数据会触发下一次渲染，从而陷入死循环。

正确的做法是将min-date作为一个数据定义在data函数中。

在 iOS 系统上初始化组件失败？

如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。

对此问题的详细解释：stackoverflow。

在桌面端无法操作组件？

参见在桌面端使用。

是否有年份或月份选择器？

如果仅需要选择年份或者月份，建议直接使用 Picker 组件。

介绍

表单中的输入框组件

引入

import Vue from 'vue';import { Field } from 'vant';Vue.use(Field);

代码演示

基础用法

可以通过v-model双向绑定输入框的值，通过placeholder设置占位提示文字

<!-- Field 是基于 Cell 实现的，可以使用 CellGroup 作为父元素来提供外边框。 --><van-cell-group>  <van-field v-model="value" placeholder="请输入用户名" /></van-cell-group>

export default {  data() {    return {      value: ''    };  }}

自定义类型

根据type属性定义不同类型的输入框，默认值为text

<!-- 输入任意文本 --><van-field v-model="text" label="文本" /><!-- 输入手机号，调起手机号键盘 --><van-field v-model="tel" type="tel" label="手机号" /><!-- 允许输入整数，调起数字键盘 --><van-field v-model="digit" type="digit" label="整数" /><!-- 允许输入数字，调起全键盘 --><van-field v-model="number" type="number" label="数字" /><!-- 输入密码 --><van-field v-model="password" type="password" label="密码" />

export default {  data() {    return {      tel: '',      text: '',      digit: '',      number: '',      password: ''    };  }}

Tips: digit 类型从 2.4.2 版本开始支持

禁用输入框

通过readonly将输入框设置为只读状态，通过disabled将输入框设置为禁用状态

<van-cell-group>  <van-field label="文本" value="输入框只读" readonly />  <van-field label="文本" value="输入框已禁用" disabled /></van-cell-group>

显示图标

通过left-icon和right-icon配置输入框两侧的图标，通过设置clearable在输入过程中展示清除图标

<van-cell-group>  <van-field    v-model="value1"    label="文本"    left-icon="smile-o"    right-icon="warning-o"    placeholder="显示图标"  />  <van-field    v-model="value2"    clearable    label="文本"    left-icon="music-o"    placeholder="显示清除图标"  /></van-cell-group>

export default {  data() {    return {      value1: '',      value2: '123'    };  }};

错误提示

设置required属性表示这是一个必填项，可以配合error或error-message属性显示对应的错误提示

<van-cell-group>  <van-field    v-model="username"    error    required    label="用户名"    placeholder="请输入用户名"  />  <van-field    v-model="phone"    required    label="手机号"    placeholder="请输入手机号"    error-message="手机号格式错误"  /></van-cell-group>

插入按钮

通过 button 插槽可以在输入框尾部插入按钮

<van-field  v-model="sms"  center  clearable  label="短信验证码"  placeholder="请输入短信验证码">  <van-button slot="button" size="small" type="primary">发送验证码</van-button></van-field>

格式化输入内容

通过formatter属性可以对输入的内容进行格式化

<van-field  v-model="value"  label="文本"  :formatter="formatter"  placeholder="格式化输入内容"/>

export default {  data() {    return {      value: ''    };  },  methods: {    formatter(value) {      // 过滤输入的数字      return value.replace(/d/g, '');    }  }}

高度自适应

对于 textarea，可以通过autosize属性设置高度自适应

<van-field  v-model="message"  rows="1"  autosize  label="留言"  type="textarea"  placeholder="请输入留言"/>

显示字数统计

设置maxlength和show-word-limit属性后会在底部显示字数统计

<van-field  v-model="message"  rows="2"  autosize  label="留言"  type="textarea"  maxlength="50"  placeholder="请输入留言"  show-word-limit/>

输入框内容对齐

通过input-align属性可以设置输入框内容的对齐方式，可选值为center、right

<van-field  v-model="value"  :label="文本"  :placeholder="输入框内容右对齐"  input-align="right"/>

API

Props

Events

除下列事件外，Field 默认支持 Input 标签所有的原生事件

方法

通过 ref 可以获取到 Field 实例并调用实例方法，详见 组件实例方法

Slots

介绍

数字键盘，提供两种样式风格，可以与密码输入框或自定义的输入框组件配合使用

引入

import Vue from 'vue';import { NumberKeyboard } from 'vant';Vue.use(NumberKeyboard);

代码演示

默认样式

<van-button @touchstart.stop="show = true">  弹出默认键盘</van-button><van-number-keyboard  :show="show"  extra-key="."  close-button-text="完成"  @blur="show = false"  @input="onInput"  @delete="onDelete"/>

import { Toast } from 'vant';export default {  data() {    return {      show: true    }  },  methods: {    onInput(value) {      Toast(value);    },    onDelete() {      Toast('删除');    }  }}

自定义样式

<van-number-keyboard  :show="show"  theme="custom"  extra-key="."  close-button-text="完成"  @blur="show = false"  @input="onInput"  @delete="onDelete"/>

双向绑定

可以通过v-model绑定键盘当前输入值

<van-field  readonly  clickable  :value="value"  @touchstart.native.stop="show = true"/><van-number-keyboard  v-model="value"  :show="show"  :maxlength="6"  @blur="show = false"/>

export default {  data() {    return {      show: false,      value: ''    }  }}

左下角按键内容

通过extra-key属性可以设置左下角按键内容

<van-button plain type="primary" @touchstart.stop="show = true'">  弹出身份证号码键盘</van-button><van-number-keyboard  :show="show"  close-button-text="完成"  extra-key="X"  @blur="show = false"  @input="onInput"  @delete="onDelete"/>

键盘标题

通过title属性可以设置键盘标题

<van-button plain type="info" @touchstart.stop="show = true'">  弹出自定义标题键盘</van-button><van-number-keyboard  :show="show"  close-button-text="完成"  title="键盘标题"  extra-key="."  @blur="show = false"  @input="onInput"  @delete="onDelete"/>

API

Props

Events

Slots

常见问题

在桌面端无法操作组件？

参见在桌面端使用。

介绍

带网格的输入框组件，可以用于输入支付密码、短信验证码等，通常与数字键盘组件配合使用

引入

import Vue from 'vue';import { PasswordInput, NumberKeyboard } from 'vant';Vue.use(PasswordInput);Vue.use(NumberKeyboard);

代码演示

基础用法

<!-- 密码输入框 --><van-password-input  :value="value"  info="密码为 6 位数字"  :focused="showKeyboard"  @focus="showKeyboard = true"/><!-- 数字键盘 --><van-number-keyboard  :show="showKeyboard"  @input="onInput"  @delete="onDelete"  @blur="showKeyboard = false"/>

export default {  data() {    return {      value: '123',      showKeyboard: true    };  },  methods: {    onInput(key) {      this.value = (this.value + key).slice(0, 6);    },    onDelete() {      this.value = this.value.slice(0, this.value.length - 1);    }  }}

自定义长度

<van-password-input  :value="value"  :length="4"  :gutter="15"  :focused="showKeyboard"  @focus="showKeyboard = true"/>

明文展示

<van-password-input  :value="value"  :mask="false"  :focused="showKeyboard"  @focus="showKeyboard = true"/>

错误提示

通过error-info属性可以设置错误提示信息，例如当输入六位时提示密码错误

<!-- 密码输入框 --><van-password-input  :value="value"  :error-info="errorInfo"  :focused="showKeyboard"  @focus="showKeyboard = true"/><!-- 数字键盘 --><van-number-keyboard  :show="showKeyboard"  @input="onInput"  @delete="onDelete"  @blur="showKeyboard = false"/>

export default {  data() {    return {      value: '123',      showKeyboard: true,      errorInfo: ''    };  },  methods: {    onInput(key) {      this.value = (this.value + key).slice(0, 6);      if (this.value.length === 6) {        this.errorInfo = '密码错误';      } else {        this.errorInfo = '';      }    },    onDelete() {      this.value = this.value.slice(0, this.value.length - 1);    }  }}

API

Props

Events

介绍

提供多个选项集合供用户选择，支持单列选择和多列级联，通常与 弹出层 组件配合使用

引入

import Vue from 'vue';import { Picker } from 'vant';Vue.use(Picker);

代码演示

基础用法

Picker 组件通过columns属性配置选项数据，columns是一个包含字符串或对象的数组

<van-picker :columns="columns" @change="onChange" />

import { Toast } from 'vant';export default {  data() {    return {      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']    };  },  methods: {    onChange(picker, value, index) {      Toast(`当前值：${value}, 当前索引：${index}`);    }  }};

默认选中项

单列选择时，可以通过default-index属性设置初始选中项的索引

<van-picker :columns="columns" :default-index="2" />

展示顶部栏

设置show-toolbar属性后会展示顶部操作栏，点击确认按钮触发confirm事件，点击取消按钮触发cancel事件

<van-picker  show-toolbar  title="标题"  :columns="columns"  @cancel="onCancel"  @confirm="onConfirm"/>

import { Toast } from 'vant';export default {  data() {    return {      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']    }  },  methods: {    onConfirm(value, index) {      Toast(`当前值：${value}, 当前索引：${index}`);    },    onCancel() {      Toast('取消');    }  }};

多列选择

通过columns属性可以配置多列选择

<van-picker show-toolbar title="标题" :columns="columns" />

export default {  data() {    return {      columns: [        // 第一列        {          values: ['周一', '周二', '周三', '周四', '周五'],          defaultIndex: 2        },        // 第二列        {          values: ['上午', '下午', '晚上'],          defaultIndex: 1        }      ]    };  }};

级联选择

使用columns的children字段可以实现选项级联的效果（从 2.4.5 版本开始支持）

<van-picker show-toolbar title="标题" :columns="columns" />

export default {  data() {    return {      columns: [{        text: '浙江',        children: [{          text: '杭州',          children: [{ text: '西湖区' }, { text: '余杭区' }]        }, {          text: '温州',          children: [{ text: '鹿城区' }, { text: '瓯海区' }]        }]      }, {        text: '福建',        children: [{          text: '福州',          children: [{ text: '鼓楼区' }, { text: '台江区' }]        }, {          text: '厦门',          children: [{ text: '思明区' }, { text: '海沧区' }]        }]      }]    };  }};

禁用选项

选项可以为对象结构，通过设置 disabled 来禁用该选项

<van-picker :columns="columns" />

export default {  data() {    return {      columns: [        { text: '杭州', disabled: true },        { text: '宁波' },        { text: '温州' }      ]    };  }};

动态设置选项

通过 Picker 上的实例方法可以更灵活地控制选择器，比如使用setColumnValues方法实现多列联动

<van-picker :columns="columns" @change="onChange" />

const citys = {  '浙江': ['杭州', '宁波', '温州', '嘉兴', '湖州'],  '福建': ['福州', '厦门', '莆田', '三明', '泉州']};export default {  data() {    return {      columns: [        { values: Object.keys(citys) },        { values: citys['浙江'] }      ]    };  },  methods: {    onChange(picker, values) {      picker.setColumnValues(1, citys[values[0]]);    }  }};

加载状态

若选择器数据是异步获取的，可以通过 loading 属性显示加载提示

<van-picker :columns="columns" :loading="loading" />

export default {  data() {    return {      columns: [],      loading: true    };  },  created() {    setTimeout(() => {      this.loading = false;      this.columns = ['选项'];    }, 1000);  }};

搭配弹出层使用

在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果

<van-field  readonly  clickable  label="城市"  :value="value"  placeholder="选择城市"  @click="showPicker = true"/><van-popup v-model="showPicker" position="bottom">  <van-picker    show-toolbar    :columns="columns"    @cancel="showPicker = false"    @confirm="onConfirm"  /></van-popup>

export default {  data() {    return {      value: '',      showPicker: false,      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']    }  },  methods: {    onConfirm(value) {      this.value = value;      this.showPicker = false;    }  }};

API

Props

Events

当选择器有多列时，事件回调参数会返回数组

Slots

Column 数据结构

当传入多列数据时，columns为一个对象数组，数组中的每一个对象配置每一列，每一列有以下key

方法

通过 ref 可以获取到 Picker 实例并调用实例方法，详见 组件实例方法

常见问题

在桌面端无法操作组件？

参见在桌面端使用。

引入

import Vue from 'vue';import { RadioGroup, Radio } from 'vant';Vue.use(Radio);Vue.use(RadioGroup);

代码演示

基础用法

通过 v-model 绑定值当前选中项的 name

<van-radio-group v-model="radio">  <van-radio name="1">单选框 1</van-radio>  <van-radio name="2">单选框 2</van-radio></van-radio-group>

export default {  data() {    return {      radio: '1'    }  }};

水平排列

​​将 direction 属性设置为 horizontal 后，单选框组会变成水平排列​​

<van-radio-group v-model="radio" direction="horizontal">  <van-radio name="1">单选框 1</van-radio>  <van-radio name="2">单选框 2</van-radio></van-radio-group>

禁用状态

通过 disabled 属性禁止选项切换，在 Radio 上设置 disabled 可以禁用单个选项

<van-radio-group v-model="radio" disabled>  <van-radio name="1">单选框 1</van-radio>  <van-radio name="2">单选框 2</van-radio></van-radio-group>

禁用文本点击

设置 label-disabled 属性后，点击单选框图标以外的内容不会触发切换

<van-radio-group v-model="radio">  <van-radio name="1" icon-disabled>单选框 1</van-radio>  <van-radio name="2" icon-disabled>单选框 2</van-radio></van-radio-group>

自定义形状

通过 square 属性设置选中状态的图标颜色

<van-radio-group v-model="radio">  <van-radio name="1" shape="square">单选框 1</van-radio>  <van-radio name="2" shape="square">单选框 2</van-radio></van-radio-group>

自定义颜色

通过 checked-color 属性设置选中状态的图标颜色

<van-radio-group v-model="radio">  <van-radio name="1" checked-color="#07c160">单选框 1</van-radio>  <van-radio name="2" checked-color="#07c160">单选框 2</van-radio></van-radio-group>

自定义大小

通过 icon-size 属性可以自定义图标的大小

<van-radio-group v-model="radio">  <van-radio name="1" icon-size="24px">单选框 1</van-radio>  <van-radio name="2" icon-size="24px">单选框 2</van-radio></van-radio-group>

自定义图标

通过 icon 插槽自定义图标，并通过 slotProps 判断是否为选中状态

<van-radio-group v-model="radio">  <van-radio name="1">    单选框 1    <template #icon="props">      <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" />    </template>  </van-radio>  <van-radio name="2">    单选框 2    <template #icon="props">      <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" />    </template>  </van-radio></van-radio-group><style>  .img-icon {    height: 20px;  }</style>

export default {  data() {    return {      radio: '1',      activeIcon: 'https://img.yzcdn.cn/vant/user-active.png',      inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png',    };  },};

与 Cell 组件一起使用

此时你需要再引入 Cell 和 CellGroup 组件

<van-radio-group v-model="radio">
  <van-cell-group>
    <van-cell title="单选框 1" clickable @click="radio = '1'">
      <template #right-icon>
        <van-radio name="1" />
      </template>
    </van-cell>
    <van-cell title="单选框 2" clickable @click="radio = '2'">
      <template #right-icon>
        <van-radio name="2" />
      </template>
    </van-cell>
  </van-cell-group>
</van-radio-group>

API

Radio Props

RadioGroup Props

RadioGroup Events

Radio Slots

引入

import Vue from 'vue';import { Rate } from 'vant';Vue.use(Rate);

代码演示

基础用法

<van-rate v-model="value" />

export default {  data() {    return {      value: 3    };  }}

自定义图标

<van-rate  v-model="value"  icon="like"  void-icon="like-o"/>

自定义样式

<van-rate  v-model="value"  :size="25"  color="#ee0a24"  void-icon="star"  void-color="#eee"/>

半星

<van-rate  v-model="value"  allow-half  void-icon="star"  void-color="#eee"/>

export default {  data() {    return {      value: 2.5    };  }}

自定义数量

<van-rate v-model="value" :count="6" />

禁用状态

<van-rate v-model="value" disabled />

只读状态

<van-rate v-model="value" readonly />

监听 change 事件

<van-rate v-model="value" @change="onChange" />

export default {  method: {    onChange(value) {      Toast('当前值：'+ value);    }  }}

API

Props

Events

引入

import Vue from 'vue';import { Search } from 'vant';Vue.use(Search);

代码演示

基础用法

v-model 用于控制搜索框中的文字，background 可以自定义搜索框外部背景色

<van-search v-model="value" placeholder="请输入搜索关键词" />

事件监听

Search 组件提供了search和cancel事件，search事件在点击键盘上的搜索/回车按钮后触发，cancel事件在点击搜索框右侧取消按钮时触发

<form action="/">  <van-search    v-model="value"    show-action    placeholder="请输入搜索关键词"    @search="onSearch"    @cancel="onCancel"  /></form>

import { Toast } from 'vant';export default {  data() {    return {      value: ''    };  },  methods: {    onSearch(val) {      Toast(val);    },    onCancel() {      Toast('取消');    }  }}

Tips: 在 van-search 外层增加 form 标签，且 action 不为空，即可在 iOS 输入法中显示搜索按钮

搜索框内容对齐

通过 input-align 属性设置搜索框内容的对齐方式，可选值为center、right

<van-search  v-model="value"  placeholder="请输入搜索关键词"  input-align="center"/>

禁用搜索框

通过disabled属性禁用搜索框

<van-search  v-model="value"  disabled  placeholder="请输入搜索关键词"/>

自定义背景色

通过background属性可以设置搜索框外部的背景色，通过shape属性设置搜索框的形状，可选值为round

<van-search  v-model="value"  shape="round"  background="#4fc08d"  placeholder="请输入搜索关键词"/>

自定义按钮

使用action插槽可以自定义右侧按钮的内容。使用插槽后，cancel事件将不再触发

<van-search  v-model="value"  show-action  placeholder="请输入搜索关键词"  @search="onSearch">  <div slot="action" @click="onSearch">搜索</div></van-search>

API

Props

Events

Slots

引入

import Vue from 'vue';import { Slider } from 'vant';Vue.use(Slider);

代码演示

基本用法

<van-slider v-model="value" @change="onChange" />

import { Toast } from 'vant';export default {  data() {    return {      value: 50    };  },  methods: {    onChange(value) {      Toast('当前值：' + value);    }  }};

指定选择范围

<van-slider v-model="value" :min="-50" :max="50" />

禁用

<van-slider v-model="value" disabled />

指定步长

<van-slider v-model="value" :step="10" />

自定义样式

<van-slider  v-model="value"  bar-height="4px"  active-color="#ee0a24"/>

自定义按钮

<van-slider v-model="value" active-color="#ee0a24">  <div slot="button" class="custom-button">    {{ value }}  </div></van-slider><style>.custom-button {  width: 26px;  color: #fff;  font-size: 10px;  line-height: 18px;  text-align: center;  background-color: #ee0a24;  border-radius: 100px;}</style>

垂直方向

Slider 垂直展示时，高度为 100% 父元素高度

<div :style="{ height: '100px' }">  <van-slider v-model="value" vertical /></div>

API

Props

Events

Slots

介绍

步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字

引入

import Vue from 'vue';import { Stepper } from 'vant';Vue.use(Stepper);

代码演示

基础用法

通过v-model绑定输入值，可以通过change事件监听到输入值的变化

<van-stepper v-model="value" />

export default {  data() {    return {      value: 1    }  }}

步长设置

通过step属性设置每次点击增加或减少按钮时变化的值，默认为1

<van-stepper v-model="value" step="2" />

限制输入范围

通过min和max属性限制输入值的范围

<van-stepper v-model="value" min="5" max="8" />

限制输入整数

设置integer属性后，输入框将限制只能输入整数

<van-stepper v-model="value" integer />

禁用状态

通过设置disabled属性来禁用步进器，禁用状态下无法点击按钮或修改输入框

<van-stepper v-model="value" disabled />

禁用输入框

通过设置disabled-input属性来禁用输入框，此时按钮仍然可以点击

<van-stepper v-model="value" disabled-input />

固定小数位数

通过设置decimal-length属性可以保留固定的小数位数

<van-stepper v-model="value" step="0.2" :decimal-length="1" />

自定义大小

通过input-width属性设置输入框宽度，通过button-size属性设置按钮大小和输入框高度

<van-stepper v-model="value" input-width="40px" button-size="32px" />

异步变更

如果需要异步地修改输入框的值，可以设置async-change属性，并在change事件中手动修改value

<van-stepper  :value="value"  async-change  @change="onChange"/>

import { Toast } from 'vant';export default {  data() {    return {      value: 1    }  },  methods: {    onChange(value) {      Toast.loading({ forbidClick: true });      setTimeout(() => {        Toast.clear();        // 注意此时修改 value 后会再次触发 change 事件        this.value = value;      }, 500);    }  }}

API

Props

Events

引入

import Vue from 'vue';import { Switch } from 'vant';Vue.use(Switch);

代码演示

基础用法

通过v-model绑定开关的选中状态，true表示开，false表示关

<van-switch v-model="checked" />

export default {  data() {    return {      checked: true    };  }};  

禁用状态

通过disabled属性来禁用开关，禁用状态下开关不可点击

<van-switch v-model="checked" disabled />

加载状态

通过loading属性设置开关为加载状态，加载状态下开关不可点击

<van-switch v-model="checked" loading />

自定义大小

通过size属性自定义开关的大小

<van-switch v-model="checked" size="24px" />

自定义颜色

active-color属性表示打开时的背景色，inactive-color表示关闭时的背景色

<van-switch v-model="checked" active-color="#07c160" inactive-color="#ee0a24" />

异步控制

需要异步控制开关时，可以使用value属性和input事件代替v-model，并在input事件回调函数中手动处理开关状态

<van-switch :value="checked" @input="onInput" />

export default {  data() {    return {      checked: true    };  },  methods: {    onInput(checked) {      Dialog.confirm({        title: '提醒',        message: '是否切换开关？'      }).then(() => {        this.checked = checked;      });    }  }}; 

搭配单元格使用

<van-cell center title="标题">  <van-switch v-model="checked" slot="right-icon" size="24" /></van-cell>

API

Props

Events

引入

import Vue from 'vue';import { Uploader } from 'vant';Vue.use(Uploader);

代码演示

基础用法

文件上传完毕后会触发after-read回调函数，获取到对应的file对象

<van-uploader :after-read="afterRead" />

export default {  methods: {    afterRead(file) {      // 此时可以自行将文件上传至服务器      console.log(file);    }  }};

图片预览

通过v-model可以绑定已经上传的图片列表，并展示图片列表的预览图

<van-uploader v-model="fileList" multiple />

export default {  data() {    return {      fileList: [        { url: 'https://img.yzcdn.cn/vant/leaf.jpg' },        // Uploader 根据文件后缀来判断是否为图片文件        // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明        { url: 'https://cloud-image', isImage: true }      ]    }  }};

限制上传数量

通过max-count属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域

<van-uploader  v-model="fileList"  multiple  :max-count="2"/>

export default {  data() {    return {      fileList: []    }  }};

自定义上传样式

通过插槽可以自定义上传区域的样式

<van-uploader>  <van-button icon="photo" type="primary">上传图片</van-button></van-uploader>

上传前校验

通过传入beforeRead函数可以在上传前进行校验，返回true表示校验通过，返回false表示校验失败。支持返回Promise进行异步校验

<van-uploader :before-read="beforeRead" />

import { Toast } from 'vant';export default {  methods: {    // 返回布尔值    beforeRead(file) {      if (file.type !== 'image/jpeg') {        Toast('请上传 jpg 格式图片');        return false;      }      return true;    },    // 返回 Promise    asyncBeforeRead(file) {      return new Promise((resolve, reject) => {        if (file.type !== 'image/jpeg') {          Toast('请上传 jpg 格式图片');          reject();        } else {          resolve();        }      });    }  }}

API

Props

Events

Slots

回调参数

before-read、after-read、before-delete 执行时会传递以下回调参数：

ResultType 可选值

result-type字段表示文件读取结果的类型，上传大文件时，建议使用 file 类型，避免卡顿。

方法

通过 ref 可以获取到 Uploader 实例并调用实例方法，详见 组件实例方法

引入

import Vue from 'vue';import { ActionSheet } from 'vant';Vue.use(ActionSheet);

代码演示

基础用法

ActionSheet通过actions数组来定义展示的选项，数组的每一项是一个对象，对象属性见文档下方表格。

<van-action-sheet v-model="show" :actions="actions" @select="onSelect" />

import { Toast } from 'vant';export default {  data() {    return {      show: false,      actions: [        { name: '选项' },        { name: '选项' },        { name: '选项', subname: '描述信息' }      ]    };  },  methods: {    onSelect(item) {      // 默认情况下点击选项时不会自动收起      // 可以通过 close-on-click-action 属性开启自动收起      this.show = false;      Toast(item.name);    }  }}

展示取消按钮

设置cancel-text属性后，会在底部展示取消按钮，点击后关闭当前菜单

<van-action-sheet  v-model="show"  :actions="actions"  cancel-text="取消"  @cancel="onCancel"/>

import { Toast } from 'vant';export default {  data() {    return {      show: false    };  },  methods: {    onCancel() {      this.show = false;      Toast('cancel');    }  }}

展示描述信息

设置description属性后，会在选项上方显示描述信息

<van-action-sheet  v-model="show"  :actions="actions"  description="这是一段描述信息"/>

选项状态

可以将选项设置为加载状态或禁用状态，或者通过color设置选项颜色

<van-action-sheet  v-model="show"  :actions="actions"  cancel-text="取消"  @cancel="onCancel"/>

export default {  data() {    return {      show: false,      actions: [        { name: '选项', color: '#07c160' },        { loading: true },        { name: '禁用选项', disabled: true }      ]    };  }}

自定义面板

通过插槽可以自定义菜单的展示内容，同时可以使用title属性展示标题栏

<van-action-sheet v-model="show" title="标题">  <div class="content">内容</div></van-action-sheet><style>.content {  padding: 16px 16px 160px;}</style>

API

Props

Action 数据结构

actions属性为一个对象数组，数组中的每个对象配置一列，对象可以包含以下值：

Events

常见问题

引入时提示 dependencies not found？

在 1.x 版本中，上拉菜单的组件名为Actionsheet，从 2.0 版本开始更名为ActionSheet，请注意区分。

介绍

弹出模态框，常用于消息提示、消息确认、在当前页面内完成特定的交互操作

弹出框组件支持函数调用和组件调用两种方式

函数调用

Dialog 是一个函数而不是组件，因此可以直接调用，展示对应的提示弹窗

import { Dialog } from 'vant';Dialog({ message: '提示' });

组件调用

通过组件调用 Dialog 时，可以通过下面的方式进行注册

import Vue from 'vue';import { Dialog } from 'vant';// 全局注册Vue.use(Dialog);// 局部注册export default {  components: {    [Dialog.Component.name]: Dialog.Component  }}

代码演示

消息提示

用于提示一些消息，只包含一个确认按钮

Dialog.alert({  title: '标题',  message: '弹窗内容'}).then(() => {  // on close});Dialog.alert({  message: '弹窗内容'}).then(() => {  // on close});

消息确认

用于确认消息，包含取消和确认按钮

Dialog.confirm({  title: '标题',  message: '弹窗内容'}).then(() => {  // on confirm}).catch(() => {  // on cancel});

异步关闭

function beforeClose(action, done) {  if (action === 'confirm') {    setTimeout(done, 1000);  } else {    done();  }}Dialog.confirm({  title: '标题',  message: '弹窗内容',  beforeClose});

全局方法

引入 Dialog 组件后，会自动在 Vue 的 prototype 上挂载 $dialog 方法，在所有组件内部都可以直接调用此方法

export default {  mounted() {    this.$dialog.alert({      message: '弹窗内容'    });  }}

组件调用

如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式

<van-dialog v-model="show" title="标题" show-cancel-button>  <img src="https://img.yzcdn.cn/vant/apple-3.jpg" rel="external nofollow" ></van-dialog>

export default {  data() {    return {      show: false    };  }}

API

方法

Options

通过函数调用 Dialog 时，支持传入以下选项：

Props

通过组件调用 Dialog 时，支持以下 Props：

Events

通过组件调用 Dialog 时，支持以下事件：

Slots

通过组件调用 Dialog 时，支持以下插槽：

引入

"usingComponents": {  "van-dropdown-menu": "@vant/weapp/dropdown-menu/index",  "van-dropdown-item": "@vant/weapp/dropdown-item/index"}

代码演示

基础用法

<van-dropdown-menu>  <van-dropdown-item value="{{ value1 }}" options="{{ option1 }}" />  <van-dropdown-item value="{{ value2 }}" options="{{ option2 }}" /></van-dropdown-menu>

Page({  data: {    option1: [      { text: '全部商品', value: 0 },      { text: '新款商品', value: 1 },      { text: '活动商品', value: 2 },    ],    option2: [      { text: '默认排序', value: 'a' },      { text: '好评排序', value: 'b' },      { text: '销量排序', value: 'c' },    ],    value1: 0,    value2: 'a',  },});

自定义菜单内容

通过插槽可以自定义DropdownItem的内容，此时需要使用实例上的toggle方法手动控制菜单的显示

<van-dropdown-menu>  <van-dropdown-item value="{{ value1 }}" options="{{ option1 }}" />  <van-dropdown-item id="item" title="{{ itemTitle }}">    <van-cell title="{{ switchTitle1 }}">      <van-switch        slot="right-icon"        size="24px"        style="height: 26px"        checked="{{ switch1 }}"        bind:change="onSwitch1Change"      />    </van-cell>    <van-cell title="{{ switchTitle2 }}">      <van-switch        slot="right-icon"        size="24px"        style="height: 26px"        checked="{{ switch2 }}"        bind:change="onSwitch2Change"      />    </van-cell>    <van-button type="info" block bind:click="onConfirm">      确定    </van-button>  </van-dropdown-item></van-dropdown-menu>

Page({  data: {    switchTitle1: '包邮',    switchTitle2: '团购',    itemTitle: '筛选',    option1: [      { text: '全部商品', value: 0 },      { text: '新款商品', value: 1 },      { text: '活动商品', value: 2 },    ],    value1: 0,  },  onConfirm() {    this.selectComponent('#item').toggle();  },  onSwitch1Change({ detail }) {    this.setData({ switch1: detail });  },  onSwitch2Change({ detail }) {    this.setData({ switch2: detail });  },});

自定义选中态颜色

通过active-color属性可以自定义菜单标题和选项的选中态颜色

<van-dropdown-menu active-color="#ee0a24">  <van-dropdown-item value="{{ value1 }}" options="{{ option1 }}" />  <van-dropdown-item value="{{ value2 }}" options="{{ option2 }}" /></van-dropdown-menu>

向上展开

将direction属性值设置为up，菜单即可向上展开

<van-dropdown-menu direction="up">  <van-dropdown-item value="{{ value1 }}" options="{{ option1 }}" />  <van-dropdown-item value="{{ value2 }}" options="{{ option2 }}" /></van-dropdown-menu>

禁用菜单

<van-dropdown-menu>  <van-dropdown-item value="{{ value1 }}" disabled options="{{ option1 }}" />  <van-dropdown-item value="{{ value2 }}" disabled options="{{ option2 }}" /></van-dropdown-menu>

API

DropdownMenu Props

DropdownItem Props

DropdownItem Events

DropdownItem Slots

DropdownItem 方法

通过 ref 可以获取到 DropdownItem 实例并调用实例方法，详见 组件实例方法

Option 数据结构

引入

import Vue from 'vue';import { Loading } from 'vant';Vue.use(Loading);

代码演示

加载类型

通过type属性可以设置加载图标的类型，默认为circular，可选值为spinner

<van-loading /><van-loading type="spinner" />

自定义颜色

通过color属性设置加载图标的颜色

<van-loading color="#1989fa" /><van-loading type="spinner" color="#1989fa" />

自定义大小

通过size属性设置加载图标的大小，默认单位为px

<van-loading size="24" /><van-loading type="spinner" size="24px" />

加载文案

可以使用默认插槽在图标的右侧插入加载文案

<van-loading size="24px">加载中...</van-loading>

垂直排列

设置vertical属性后，图标和文案会垂直排列

<van-loading size="24px" vertical>加载中...</van-loading>

API

Props

Slots

引入

import Vue from 'vue';import { Notify } from 'vant';Vue.use(Notify);

代码演示

基础用法

Notify('通知内容');

通知类型

支持primary、success、warning、danger四种通知类型，默认为danger

// 主要通知Notify({ type: 'primary', message: '通知内容' });// 成功通知Notify({ type: 'success', message: '通知内容' });// 危险通知Notify({ type: 'danger', message: '通知内容' });// 警告通知Notify({ type: 'warning', message: '通知内容' });

自定义通知

自定义消息通知的颜色和展示时长

Notify({  message: '自定义颜色',  color: '#ad0000',  background: '#ffe1e1'});Notify({  message: '自定义时长',  duration: 1000});

组件内调用

引入 Notify 组件后，会自动在 Vue 的 prototype 上挂载 $notify 方法，便于在组件内调用。

export default {  mounted() {    this.$notify('提示文案');  }}

API

方法

Options

介绍

创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作

引入

import Vue from 'vue';import { Overlay } from 'vant';Vue.use(Overlay);

代码演示

基础用法

<van-button type="primary" text="显示遮罩层" @click="show = true" /><van-overlay :show="show" @click="show = false" />

export default {  data() {    return {      show: false    }  }},

嵌入内容

通过默认插槽可以在遮罩层上嵌入任意内容

<van-overlay :show="show" @click="show = false">  <div class="wrapper" @click.stop>    <div class="block" />  </div></van-overlay><style>.wrapper {  display: flex;  align-items: center;  justify-content: center;  height: 100%;}.block {  width: 120px;  height: 120px;  background-color: #fff;}</style>

API

Props

Events

Slots

引入

import Vue from 'vue';import { PullRefresh } from 'vant';Vue.use(PullRefresh);

代码演示

基础用法

下拉刷新时会触发 refresh 事件，在事件的回调函数中可以进行同步或异步操作，操作完成后将 v-model 设置为 false，表示加载完成。

<van-pull-refresh v-model="isLoading" @refresh="onRefresh">  <p>刷新次数: {{ count }}</p></van-pull-refresh>

import { Toast } from 'vant';export default {  data() {    return {      count: 0,      isLoading: false    }  },  methods: {    onRefresh() {      setTimeout(() => {        Toast('刷新成功');        this.isLoading = false;        this.count++;      }, 1000);    }  }}

成功提示

通过success-text可以设置刷新成功后的顶部提示文案

<van-pull-refresh  v-model="isLoading"  success-text="刷新成功"  @refresh="onRefresh">  <p>刷新次数: {{ count }}</p></van-pull-refresh>

自定义提示

通过插槽可以自定义下拉刷新过程中的提示内容

<van-pull-refresh v-model="isLoading" :head-height="80" @refresh="onRefresh">  <!-- 下拉提示，通过 scale 实现一个缩放效果 -->  <img    class="doge"    slot="pulling"    slot-scope="props"    src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow"  rel="external nofollow"     :style="{ transform: `scale(${props.distance / 80})` }"  >  <!-- 释放提示 -->  <img    class="doge"    slot="loosing"    src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow"  rel="external nofollow"   >  <!-- 加载提示 -->  <img    class="doge"    slot="loading"    src="https://img.yzcdn.cn/vant/doge-fire.jpg" rel="external nofollow"   >  <p>刷新次数: {{ count }}</p></van-pull-refresh><style>.doge {  width: 140px;  height: 72px;  margin-top: 8px;  border-radius: 4px;}</style>

API

Props

Events

Slots

常见问题

在桌面端无法操作组件？

参见在桌面端使用。

引入

import Vue from 'vue';import { SwipeCell } from 'vant';Vue.use(SwipeCell);

代码演示

基础用法

SwipeCell组件提供了left和right两个插槽，用于定义两侧滑动区域的内容

<van-swipe-cell>  <template slot="left">    <van-button square type="primary" text="选择" />  </template>  <van-cell :border="false" title="单元格" value="内容" />  <template slot="right">    <van-button square type="danger" text="删除" />    <van-button square type="primary" text="收藏"/>  </template></van-swipe-cell>

自定义内容

SwipeCell内容可以嵌套任意内容，比如嵌套一个商品卡片

<van-swipe-cell>  <van-card    num="2"    price="2.00"    desc="描述信息"    title="商品标题"    class="goods-card"    thumb="https://img.yzcdn.cn/vant/cat.jpeg"  />  <van-button    slot="right"    square    text="删除"    type="danger"    class="delete-button"  /></van-swipe-cell><style>.goods-card {  margin: 0;  background-color: @white;}.delete-button {  height: 100%;}</style>

异步关闭

通过传入before-close回调函数，可以自定义两侧滑动内容关闭时的行为

<van-swipe-cell :before-close="beforeClose">  <template slot="left">    <van-button square type="primary" text="选择" />  </template>  <van-cell :border="false" title="单元格" value="内容" />  <template slot="right">    <van-button square type="danger" text="删除" />  </template></van-swipe-cell>

export default {  methods: {    // position 为关闭时点击的位置    // instance 为对应的 SwipeCell 实例    beforeClose({ position, instance }) {      switch (position) {        case 'left':        case 'cell':        case 'outside':          instance.close();          break;        case 'right':          Dialog.confirm({            message: '确定删除吗？'          }).then(() => {            instance.close();          });          break;      }    }  }}

API

Props

Slots

Events

beforeClose 参数

beforeClose 的第一个参数为对象，对象中包含以下属性：

方法

通过 ref 可以获取到 SwipeCell 实例并调用实例方法，详见 组件实例方法

常见问题

在桌面端无法操作组件？

参见在桌面端使用。

引入

import Vue from 'vue';import { Toast } from 'vant';Vue.use(Toast);

代码演示

文字提示

Toast('提示内容');

加载提示

使用Toast.loading方法展示加载提示，通过forbidClick属性可以禁用背景点击，通过loadingType属性可以自定义加载图标类型。

Toast.loading({  message: '加载中...',  forbidClick: true});// 自定义加载图标Toast.loading({  message: '加载中...',  forbidClick: true,  loadingType: 'spinner'});

成功/失败提示

Toast.success('成功文案');Toast.fail('失败文案');

自定义图标

Toast({  message: '自定义图标',  icon: 'like-o'});Toast({  message: '展示图片',  icon: 'https://img.yzcdn.cn/vant/logo.png'});

动态更新提示

const toast = Toast.loading({  duration: 0, // 持续展示 toast  forbidClick: true,  message: '倒计时 3 秒'});let second = 3;const timer = setInterval(() => {  second--;  if (second) {    toast.message = `倒计时 ${second} 秒`;  } else {    clearInterval(timer);    // 手动清除 Toast    Toast.clear();  }}, 1000);

组件内调用

引入 Toast 组件后，会自动在 Vue 的 prototype 上挂载 $toast 方法，便于在组件内调用。

export default {  mounted() {    this.$toast('提示文案');  }}

单例模式

Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例

Toast.allowMultiple();const toast1 = Toast('第一个 Toast');const toast2 = Toast.success('第二个 Toast');toast1.clear();toast2.clear();

修改默认配置

通过Toast.setDefaultOptions函数可以全局修改 Toast 的默认配置

// 将所有 Toast 的展示时长设置为 2000 毫秒Toast.setDefaultOptions({ duration: 2000 });// 将所有 loading Toast 设置为背景不可点击 (2.2.10 版本开始支持)Toast.setDefaultOptions('loading', { forbidClick: true });// 重置所有 Toast 的默认配置Toast.resetDefaultOptions();// 重置 loading Toast 的默认配置 (2.2.10 版本开始支持)Toast.resetDefaultOptions('loading');

API

方法

Options

引入

import Vue from 'vue';import { Circle } from 'vant';Vue.use(Circle);

代码演示

基础用法

rate属性表示进度条的目标进度，v-model表示动画过程中的实时进度。当rate发生变化时，v-model会以speed的速度变化，直至达到rate设定的值。

<van-circle  v-model="currentRate"  :rate="30"  :speed="100"  :text="text"/>

export default {  data() {    return {      currentRate: 0    };  },  computed: {    text() {      return this.currentRate.toFixed(0) + '%'    }  }};

宽度定制

通过stroke-width属性来控制进度条宽度

<van-circle  v-model="currentRate"  :rate="rate"  :stroke-width="60"  text="宽度定制"/>

颜色定制

通过color属性来控制进度条颜色，layer-color属性来控制轨道颜色

<van-circle  v-model="currentRate"  :rate="rate"  layer-color="#ebedf0"  text="颜色定制"/>

渐变色

color属性支持传入对象格式来定义渐变色

<van-circle  v-model="currentRate"  :rate="rate"  :color="gradientColor"  text="渐变色"/>

export default {  data() {    return {      currentRate: 0,      gradientColor: {        '0%': '#3fecff',        '100%': '#6149f6'      }    };  }};

逆时针方向

将clockwise设置为false，进度会从逆时针方向开始

<van-circle  v-model="currentRate"  :rate="rate"  :clockwise="false"  text="逆时针方向"/>

大小定制

通过size属性设置圆环直径

<van-circle  v-model="currentRate"  :rate="rate"  size="120px"  text="大小定制"/>

API

Props

Slots

引入

import Vue from 'vue';import { Collapse, CollapseItem } from 'vant';Vue.use(Collapse);Vue.use(CollapseItem);

代码演示

基础用法

通过v-model控制展开的面板列表，activeNames为数组格式

<van-collapse v-model="activeNames">  <van-collapse-item title="标题1" name="1">内容</van-collapse-item>  <van-collapse-item title="标题2" name="2">内容</van-collapse-item>  <van-collapse-item title="标题3" name="3" disabled>内容</van-collapse-item></van-collapse>

export default {  data() {    return {      activeNames: ['1']    };  }};

手风琴

通过accordion可以设置为手风琴模式，最多展开一个面板，此时activeName为字符串格式

<van-collapse v-model="activeName" accordion>  <van-collapse-item title="标题1" name="1">内容</van-collapse-item>  <van-collapse-item title="标题2" name="2">内容</van-collapse-item>  <van-collapse-item title="标题3" name="3">内容</van-collapse-item></van-collapse>

export default {  data() {    return {      activeName: '1'    };  }};

自定义标题内容

<van-collapse v-model="activeNames">  <van-collapse-item name="1">    <div slot="title">标题1 <van-icon name="question-o" /></div>    内容  </van-collapse-item>  <van-collapse-item title="标题2" name="2" icon="shop-o">    内容  </van-collapse-item></van-collapse>

export default {  data() {    return {      activeNames: ['1']    };  }};

API

Collapse Props

Collapse Events

CollapseItem Props

CollapseItem Slots

引入

import Vue from 'vue';import { CountDown } from 'vant';Vue.use(CountDown);

代码演示

基本用法

time属性表示倒计时总时长，单位为毫秒

<van-count-down :time="time" />

export default {  data() {    return {      time: 30 * 60 * 60 * 1000    };  }}

自定义格式

通过format属性设置倒计时文本的内容

<van-count-down :time="time" format="DD 天 HH 时 mm 分 ss 秒" />

毫秒级渲染

倒计时默认每秒渲染一次，设置millisecond属性可以开启毫秒级渲染

<van-count-down millisecond :time="time" format="HH:mm:ss:SS" />

自定义样式

通过插槽自定义倒计时的样式，timeData对象格式见下方表格

<van-count-down :time="time">  <template v-slot="timeData">    <span class="item">{{ timeData.hours }}</span>    <span class="item">{{ timeData.minutes }}</span>    <span class="item">{{ timeData.seconds }}</span>  </template></van-count-down><style>.item {  display: inline-block;  width: 22px;  margin-right: 5px;  color: #fff;  font-size: 12px;  text-align: center;  background-color: #1989fa;}</style>

手动控制

通过 ref 获取到组件实例后，可以调用start、pause、reset方法

<van-count-down  ref="countDown"  millisecond  :time="3000"  :auto-start="false"  format="ss:SSS"  @finish="finish"/><van-grid clickable>  <van-grid-item text="开始" icon="play-circle-o" @click="start" />  <van-grid-item text="暂停" icon="pause-circle-o" @click="pause" />  <van-grid-item text="重置" icon="replay" @click="reset" /></van-grid>

import { Toast } from 'vant';export default {  methods: {    start() {      this.$refs.countDown.start();    },    pause() {      this.$refs.countDown.pause();    },    reset() {      this.$refs.countDown.reset();    },    finish() {      Toast('倒计时结束');    }  }}

API

Props

format 格式

Events

Slots