Vant 是有赞前端团队开源的移动端组件库，于 2017 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。
目前 Vant 官方提供了 Vue 2 版本、Vue 3 版本和微信小程序版本，并由社区团队维护 React 版本和支付宝小程序版本。
请参考 快速上手 章节
修改代码请阅读我们的 贡献指南
使用过程中发现任何问题都可以提 Issue 给我们，当然，我们也非常欢迎你给我们发 PR
现代浏览器以及 Android 4.0+, iOS 8.0+
有赞前端团队是由一群年轻、皮实、对技术饱含热情的小伙伴组成的，目前共有 100 多名前端工程师，分布在业务中台、电商、零售、美业、资产、赋能等业务线。
我们热爱分享和开源，崇尚用工程师的方式解决问题，因此造了很多工具来解决我们遇到的问题，目前我们维护的开源产品有：
我们正在寻找更多优秀的小伙伴，一起拓展前端技术的边界，期待你的加入！
| 项目 | 描述 |
|---|---|
| vant-demo | Vant 官方示例合集 |
| vant-weapp | 微信小程序组件库 |
| vant-cli | 开箱即用的组件库搭建工具 |
| vant-icons | Vant 图标库 |
| vant-touch-emulator | 在桌面端使用 Vant 的辅助库 |
由社区维护的项目如下，欢迎补充：
| 项目 | 描述 |
|---|---|
| vant-react | Vant React 版 |
| vant-aliapp | Vant 支付宝小程序版 |
| taroify | Vant Taro 版 |
本项目基于 MIT 协议，请自由地享受和参与开源
在现有项目中使用 Vant 时，可以通过 npm 或 yarn 进行安装：
# Vue 2 项目，安装 Vant 2：npm i vant -S# Vue 3 项目，安装 Vant 3：npm i vant@next -S使用 Vant 最简单的方法是直接在 html 文件中引入 CDN 链接，之后你可以通过全局变量 vant 访问到所有组件。
<!-- 引入样式文件 --><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vant@next/lib/index.css" rel="external nofollow" target="_blank" /><!-- 引入 Vue 和 Vant 的 JS 文件 --><script src="https://cdn.jsdelivr.net/npm/vue@next" rel="external nofollow" ></script><script src="https://cdn.jsdelivr.net/npm/vant@next/lib/vant.min.js" rel="external nofollow" ></script><script> // 在 #app 标签下渲染一个按钮组件 const app = Vue.createApp({ template: `<van-button>按钮</van-button>`, }); app.use(vant); // 通过 CDN 引入时不会自动注册 Lazyload 组件 // 可以通过下面的方式手动注册 app.use(vant.Lazyload); // 调用函数组件，弹出一个 Toast vant.Toast('提示'); app.mount('#app');</script>你可以通过以下免费 CDN 服务来使用 Vant:
在新项目中使用 Vant 时，推荐使用 Vue 官方提供的脚手架 Vue Cli 创建项目并安装 Vant。
# 安装 Vue Clinpm install -g @vue/cli# 创建一个项目vue create hello-world# 创建完成后，可以通过命令打开图形化界面，如下图所示vue ui
在图形化界面中，点击 依赖 -> 安装依赖，然后将 vant 添加到依赖中即可。
我们提供了丰富的示例工程，通过示例工程你可以了解如下内容：
babel-plugin-import 是一款 babel 插件，它会在编译过程中将 import 语句自动转换为按需引入的方式。
# 安装插件npm i babel-plugin-import -D在.babelrc 或 babel.config.js 中添加配置：
{ "plugins": [ [ "import", { "libraryName": "vant", "libraryDirectory": "es", "style": true } ] ]}接着你可以在代码中直接引入 Vant 组件，插件会自动将代码转化为按需引入的形式。
// 原始代码import { Button } from 'vant';// 编译后代码import Button from 'vant/es/button';import 'vant/es/button/style';如果你在使用 TypeScript，可以使用 ts-import-plugin 实现按需引入。
对于 vite 项目，可以使用 vite-plugin-style-import 实现按需引入, 原理和 babel-plugin-import 类似。
# 安装插件npm i vite-plugin-style-import -D// vite.config.jsimport vue from '@vitejs/plugin-vue';import styleImport from 'vite-plugin-style-import';export default { plugins: [ vue(), styleImport({ libs: [ { libraryName: 'vant', esModule: true, resolveStyle: (name) => `vant/es/${name}/style`, }, ], }), ],};在不使用插件的情况下，可以手动引入需要使用的组件和样式。
// 引入组件import Button from 'vant/es/button';// 引入组件对应的样式，若组件没有样式文件，则无须引入import 'vant/es/button/style';Vant 支持一次性导入所有组件，引入所有组件会增加代码包体积，因此不推荐这种做法。
import { createApp } from 'vue';import Vant from 'vant';import 'vant/lib/index.css';const app = createApp();app.use(Vant);Tips: 配置按需引入后，将不允许直接导入所有组件。
Vant 基于 CSS 变量提供了主题定制的能力，可以对组件样式进行统一修改，详见 ConfigProvider 全局配置 组件。
如果主题定制不能满足你的需求，也可以通过自定义样式类来覆盖默认样式，参考下面的示例：
<template> <van-button class="my-button">按钮</van-button></template><style> /** 覆盖 Button 最外层元素的样式 */ .my-button { width: 200px; } /** 覆盖 Button 内部子元素的样式 */ .my-button .van-button__text { color: red; }</style>在 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 支持多种组件注册方式，请根据实际业务需要进行选择。
全局注册后，你可以在 app 下的任意子组件中使用注册的 Vant 组件。
import { Button } from 'vant';import { createApp } from 'vue';const app = createApp();// 方式一. 通过 app.use 注册// 注册完成后，在模板中通过 <van-button> 或 <VanButton> 标签来使用按钮组件app.use(Button);// 方式二. 通过 app.component 注册// 注册完成后，在模板中通过 <van-button> 标签来使用按钮组件app.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://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.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(); },};Vant 默认使用 px 作为样式单位，如果需要使用 viewport 单位 (vw, vh, vmin, vmax)，推荐使用 postcss-px-to-viewport 进行转换。
postcss-px-to-viewport 是一款 PostCSS 插件，用于将 px 单位转化为 vw/vh 单位。
下面提供了一份基本的 PostCSS 示例配置，可以在此配置的基础上根据项目需求进行修改。
// postcss.config.jsmodule.exports = { plugins: { 'postcss-px-to-viewport': { viewportWidth: 375, }, },};Tips: 在配置 postcss-loader 时，应避免 ignore node_modules 目录，否则将导致 Vant 样式无法被编译。
如果需要使用 rem 单位进行适配，推荐使用以下两个工具：
下面提供了一份基本的 PostCSS 示例配置，可以在此配置的基础上根据项目需求进行修改。
// postcss.config.jsmodule.exports = { plugins: { 'postcss-pxtorem': { rootValue: 37.5, propList: ['*'], }, },};如果设计稿的尺寸不是 375，而是 750 或其他大小，可以将 rootValue 配置调整为:
// postcss.config.jsmodule.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 />
提示
当前文档为 Vant 3 的更新日志，如需查询 Vant 2 的更新内容，请访问 Vant 2 更新日志。
Vant 遵循 Semver 语义化版本规范。
发布节奏
2021-07-26
Feature
Bug Fixes
2021-07-19
Feature
Bug Fixes
2021-07-11
Feature
Bug Fixes
2021-07-03
Feature
Bug Fixes
2021-06-27
Feature
2021-06-22
New Component
Feature
Bug Fixes
2021-06-03
Feature
Bug Fixes
2021-05-23
Feature
Bug Fixes
2021-05-03
Feature
Bug Fixes
2021-04-25
Feature
Bug Fixes
2021-04-18
Feature
Bug Fixes
2021-04-11
Feature
Types
Bug Fixes
2021-04-05
Feature
Bug Fixes
2021-03-30
Feature
Bug Fixes
2021-03-19
Feature
Feature
Bug Fixes
2021-03-08
Feature
Bug Fixes
2021-03-07
Types
Feature
Bug Fixes
2021-02-28
Feature
perf
Bug Fixes
2021-01-31
Feature
Bug Fixes
2021-01-24
Feature
style
Bug Fixes
2021-01-17
Feature
Bug Fixes
2021-01-10
Feature
Bug Fixes
2021-01-02
Feature
Bug Fixes
2020-12-27
Feature
Bug Fixes
2020-12-23
更新内容
2020-12-21
New Component
Feature
Types
2020-12-10
Breaking Change
perf
Bug Fixes
2020-12-04
perf
Bug Fixes
2020-12-01
Breaking Change
Feature
style
Bug Fixes
2020-11-22
Bug Fixes
2020-11-22
New Component
Feature
Bug Fixes
2020-11-15
Bug Fixes
2020-11-08
Bug Fixes
2020-11-01
Bug Fixes
2020-10-24
Bug Fixes
2020-10-18
refactor
style
Bug Fixes
2020-10-03
breaking changes
Feature
2020-09-28
Bug Fixes
2020-09-28
breaking changes
refactor
使用 Composition API 重构以下组件：
Feature
Bug Fixes
2020-09-18
breaking changes
refactor
使用 Composition API 重构以下组件：
Bug Fixes
2020-09-13
breaking changes
refactor
使用 Composition API 重构以下组件：
Feature
Bug Fixes
2020-09-06
breaking changes
refactor
使用 Composition API 重构以下组件：
Bug Fixes
2020-09-01
Feature
Vant 3 是基于 Vue 3 开发的，在使用 Vant 3 前，请将项目中的 Vue 升级到 3.0 以上版本。
Vant 2 到 Vant 3 存在一些不兼容更新，请仔细阅读下方的不兼容更新内容，并依次处理。
组件命名调整
GoodsAction 商品导航组件重命名为 ActionBar 行动栏。
<!-- Vant 2 --><van-goods-action> <van-goods-action-icon text="图标" /> <van-goods-action-button text="按钮" /></van-goods-action><!-- Vant 3 --><van-action-bar> <van-action-bar-icon text="图标" /> <van-action-bar-button text="按钮" /></van-action-bar>移除 SwitchCell 组件，可以直接使用 Cell 和 Switch 组件代替。
<!-- Vant 2 --><van-switch-cell title="标题" v-model="checked" /><!-- Vant 3 --><van-cell center title="标题"> <template #right-icon> <van-switch v-model="checked" size="24" /> </template></van-cell>为了适配 Vue 3 的 v-model API 用法变更，所有提供 v-model 属性的组件在用法上有一定调整。以下弹窗类组件的 v-model 被重命名为 v-model:show：
<!-- Vant 2 --><van-popup v-model="show" /><!-- Vant 3 --><van-popup v-model:show="show" />以下表单型组件 v-model 对应的 prop 重命名为 modelValue，event 重命名为 update:modelValue：
<!-- Vant 2 --><van-field :value="value" @input="onInput" /><!-- Vant 3 --><van-field :model-value="value" @update:model-value="onInput" />在之前的版本中，我们通过 info 属性来展示图标右上角的徽标信息，为了更符合社区的命名习惯，我们将这个属性重命名为 badge，影响以下组件：
同时内部使用的 Info 组件也会重命名为 Badge。
<!-- Vant 2 --><van-icon info="5" /><!-- Vant 3 --><van-icon badge="5" />Vue 3.0 中增加了 Teleport 组件，提供将组件渲染到任意 DOM 位置的能力，Vant 2 也通过 get-container 属性提供了类似的能力。为了与官方的 API 保持一致，Vant 中的 get-container 属性将重命名为 teleport。
<!-- Vant 2 --><template> <van-popup get-container="body" /> <van-popup :get-container="getContainer" /></template><script> export default { methods: { getContainer() { return document.querySelector('#container'); }, }, };</script><!-- Vant 3 --><template> <van-popup teleport="body" /> <van-popup :teleport="container" /></template><script> export default { beforeCreate() { this.container = document.querySelector('#container'); }, };</script>Vant 2 中默认提供了 $toast、$dialog 等全局方法，但 Vue 3.0 不再支持直接在 Vue 的原型链上挂载方法，因此从 Vant 3.0 开始，使用全局方法前必须先通过 app.use 将组件注册到对应的 app 上。
import { Toast, Dialog, Notify } from 'vant';// 将 Toast 等组件注册到 app 上app.use(Toast);app.use(Dialog);app.use(Notify);// app 内的子组件可以直接调用 $toast 等方法export default { mounted() { this.$toast('提示文案'); },};感谢你使用 Vant。
以下是关于向 Vant 提交反馈或代码的指南。在向 Vant 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下文字。
按照下面的步骤操作，即可在本地开发 Vant 组件。
# 克隆仓库# 默认为 dev 分支，包含 Vant 3 的代码# 如果需要在 Vant 2 上进行更改，请基于 2.x 分支进行开发git clone git@github.com:youzan/vant.git# 安装依赖cd vant && yarn# 进入开发模式，浏览器访问 http://localhost:8080npm run dev项目的主要目录结构如下所示：
vant├─ docs # 文档├─ packages # 基础包├─ src # 组件源代码├─ test # 单测工具类└─ vant.config.js # 文档网站配置组件代码位于 src 目录下，每个组件一个独立的文件夹。
添加新组件时，请按照下面的目录结构组织文件，并在 vant.config.js 中配置组件名称。
src└─ button ├─ demo # 示例代码 ├─ test # 单元测试 ├─ Component.ts # 组件 ├─ index.ts # 组件入口 ├─ index.less # 样式 ├─ var.less # 样式变量 ├─ README.md # 英文文档 └─ README.zh-CN.md # 中文文档如果你是第一次在 GitHub 上提 Pull Request ，可以阅读下面这两篇文章来学习：
提 Pull Request 前，请依照下面的流程同步主仓库的最新代码：
# 添加主仓库到 remote，作为 fork 后仓库的上游仓库git remote add upstream https://github.com/youzan/vant.git# 拉取主仓库最新代码git fetch upstream# 切换至 dev 分支git checkout dev# 合并主仓库代码git merge upstream/devVant 是基于有赞 Zan Design System 视觉规范实现的组件库，在这里可以下载 Vant 的设计资源。
包含 Sketch 格式的色彩规范、字体规范、组件设计规范。
包含 Sketch 格式的图标库资源。
Vant 的所有图标都托管在 iconfont.cn 上，点此查看：Vant 图标库。
Axure 元件库，由社区的 @axure-tczy 同学贡献。
在参与 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 的时候，其命名应该始终使用 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" />指令缩写，用 : 表示 v-bind: ，用 @ 表示 v-on:
<!-- bad --><input v-bind:value="value" v-on:input="onInput" /><!-- good --><input :value="value" @input="onInput" />标签的 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: '', components: {}, props: {}, emits: [], setup() {}, data() {}, computed: {}, watch: {}, created() {}, mounted() {}, unmounted() {}, 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/es/locale/lang/en-US';Locale.use('en-US', enUS);通过 Locale.add 方法可以实现文案的修改和扩展，示例如下：
import { Locale } from 'vant';const messages = { 'zh-CN': { vanPicker: { confirm: '关闭', // 将'确认'修改为'关闭' }, },};Locale.add(messages);目前支持的语言:
| 语言 | 文件名 |
|---|---|
| 简体中文 | zh-CN |
| 繁體中文（港） | zh-HK |
| 繁體中文（台） | zh-TW |
| 德语 | de-DE |
| 德语 (正式) | de-DE-formal |
| 英语 | en-US |
| 西班牙语 | es-ES |
| 日语 | ja-JP |
| 挪威语 | nb-NO |
| 罗马尼亚语 | ro-RO |
| 俄罗斯语 | ru-RU |
| 土耳其语 | tr-TR |
| 泰语 | th-TH |
| 法语 | fr-FR |
在 这里 查看所有的语言包源文件。
如果上方列表中没有你需要的语言，欢迎给我们提 Pull Request 来增加新的语言包，改动内容可以参考增加德语语言包 的 PR。
可以使用 vue-i18n 来实现。
目前没有提供 CDN 形式的语言包，可以手动拷贝语言包的内容来使用。
语言包中默认不包含 Sku 业务组件的语言配置，因此如果有 Sku 组件的国际化需求，请自行配置国际化文案。
按钮用于触发一个操作，如提交表单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Button } from 'vant';const app = createApp();app.use(Button);按钮支持 default、primary、success、warning、danger 五种类型，默认为 default。
<van-button type="primary">主要按钮</van-button><van-button type="success">成功按钮</van-button><van-button type="default">默认按钮</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="primary">朴素按钮</van-button>设置 hairline 属性可以展示 0.5px 的细边框。
<van-button plain hairline type="primary">细边框按钮</van-button><van-button plain hairline type="primary">细边框按钮</van-button>通过 disabled 属性来禁用按钮，禁用状态下按钮不可点击。
<van-button disabled type="primary">禁用状态</van-button><van-button disabled type="primary">禁用状态</van-button>通过 loading 属性设置按钮为加载状态，加载状态下默认会隐藏按钮文字，可以通过 loading-text 设置加载状态下的文字。
<van-button loading type="primary" /><van-button loading type="primary" loading-type="spinner" /><van-button loading type="primary" loading-text="加载中..." />通过 square 设置方形按钮，通过 round 设置圆形按钮。
<van-button square type="primary">方形按钮</van-button><van-button round type="primary">圆形按钮</van-button>通过 icon 属性设置按钮图标，支持 Icon 组件里的所有图标，也可以传入图标 URL。
<van-button icon="plus" type="primary" /><van-button icon="plus" type="primary">按钮</van-button><van-button icon="https://img.yzcdn.cn/vant/user-active.png" type="primary"> 按钮</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, #ff6034, #ee0a24)"> 渐变色按钮</van-button>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success warning danger | string | default |
| size | 尺寸，可选值为 large small mini | string | normal |
| text | 按钮文字 | string | - |
| color | 按钮颜色，支持传入 linear-gradient 渐变色 | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| icon-position | 图标展示位置，可选值为 right | string | left |
| tag | 按钮根节点的 HTML 标签 | string | button |
| native-type | 原生 button 标签的 type 属性 | string | button |
| block | 是否为块级元素 | boolean | false |
| plain | 是否为朴素按钮 | boolean | false |
| square | 是否为方形按钮 | boolean | false |
| round | 是否为圆形按钮 | boolean | false |
| disabled | 是否禁用按钮 | boolean | false |
| hairline | 是否使用 0.5px 边框 | boolean | false |
| loading | 是否显示为加载状态 | boolean | false |
| loading-text | 加载状态提示文字 | string | - |
| loading-type | 加载图标类型，可选值为 spinner | string | circular |
| loading-size | 加载图标大小 | string | 20px |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，同 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击按钮，且按钮状态不为加载或禁用时触发 | event: MouseEvent |
| touchstart | 开始触摸按钮时触发 | event: TouchEvent |
| 名称 | 说明 |
|---|---|
| default | 按钮内容 |
icon v3.0.18 | 自定义图标 |
| loading | 自定义加载图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-button-mini-height | 24px | - |
| --van-button-mini-padding | 0 var(--van-padding-base) | - |
| --van-button-mini-font-size | var(--van-font-size-xs) | - |
| --van-button-small-height | 32px | - |
| --van-button-small-padding | 0 var(--van-padding-xs) | - |
| --van-button-small-font-size | var(--van-font-size-sm) | - |
| --van-button-normal-font-size | var(--van-font-size-md) | - |
| --van-button-normal-padding | 0 15px | - |
| --van-button-large-height | 50px | - |
| --van-button-default-height | 44px | - |
| --van-button-default-line-height | 1.2 | - |
| --van-button-default-font-size | var(--van-font-size-lg) | - |
| --van-button-default-color | var(--van-text-color) | - |
| --van-button-default-background-color | var(--van-white) | - |
| --van-button-default-border-color | var(--van-border-color) | - |
| --van-button-primary-color | var(--van-white) | - |
| --van-button-primary-background-color | var(--van-primary-color) | - |
| --van-button-primary-border-color | var(--van-primary-color) | - |
| --van-button-success-color | var(--van-white) | - |
| --van-button-success-background-color | var(--van-success-color) | - |
| --van-button-success-border-color | var(--van-success-color) | - |
| --van-button-danger-color | var(--van-white) | - |
| --van-button-danger-background-color | var(--van-danger-color) | - |
| --van-button-danger-border-color | var(--van-danger-color) | - |
| --van-button-warning-color | var(--van-white) | - |
| --van-button-warning-background-color | var(--van-orange) | - |
| --van-button-warning-border-color | var(--van-orange) | - |
| --van-button-border-width | var(--van-border-width-base) | - |
| --van-button-border-radius | var(--van-border-radius-sm) | - |
| --van-button-round-border-radius | var(--van-border-radius-max) | - |
| --van-button-plain-background-color | var(--van-white) | - |
| --van-button-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-button-icon-size | 1.2em | - |
| --van-button-loading-icon-size | 20px | - |
单元格为列表中的单个展示项。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Cell, CellGroup } from 'vant';const app = createApp();app.use(Cell);app.use(CellGroup);Cell 可以单独使用，也可以与 CellGroup 搭配使用，CellGroup 可以为 Cell 提供上下外边框。
<van-cell-group> <van-cell title="单元格" value="内容" /> <van-cell title="单元格" value="内容" label="描述信息" /></van-cell-group>通过 CellGroup 的 inset 属性，可以将单元格转换为圆角卡片风格（从 3.1.0 版本开始支持）。
<van-cell-group inset> <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 时，内容会靠左对齐。
<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 #title> <span class="custom-title">单元格</span> <van-tag type="danger">标签</van-tag> </template></van-cell><van-cell title="单元格" icon="shop-o"> <!-- 使用 right-icon 插槽来自定义右侧图标 --> <template #right-icon> <van-icon name="search" class="search-icon" /> </template></van-cell><style> .custom-title { margin-right: 4px; vertical-align: middle; } .search-icon { font-size: 16px; line-height: inherit; }</style>通过 center 属性可以让 Cell 的左右内容都垂直居中。
<van-cell center title="单元格" value="内容" label="描述信息" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 分组标题 | string | - |
inset v3.1.0 | 是否展示为圆角卡片风格 | boolean | false |
| border | 是否显示外边框 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 左侧标题 | number | string | - |
| value | 右侧内容 | number | string | - |
| label | 标题下方的描述信息 | string | - |
| size | 单元格大小，可选值为 large | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，同 vue-router 的 to 属性 | string | object | - |
| border | 是否显示内边框 | boolean | true |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| clickable | 是否开启点击反馈 | boolean | null |
| is-link | 是否展示右侧箭头并开启点击反馈 | boolean | false |
| required | 是否显示表单必填星号 | boolean | false |
| center | 是否使内容垂直居中 | boolean | false |
| arrow-direction | 箭头方向，可选值为 left up down | string | right |
| title-style | 左侧标题额外样式 | string | Array | object | - |
| title-class | 左侧标题额外类名 | string | Array | object | - |
| value-class | 右侧内容额外类名 | string | Array | object | - |
| label-class | 描述信息额外类名 | string | Array | object | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击单元格时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 默认插槽 |
| title | 自定义分组标题 |
| 名称 | 说明 |
|---|---|
| title | 自定义左侧标题 |
value v3.1.1 | 自定义右侧内容 |
| label | 自定义标题下方的描述信息 |
| icon | 自定义左侧图标 |
| right-icon | 自定义右侧图标 |
| extra | 自定义单元格最右侧的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-cell-font-size | var(--van-font-size-md) | - |
| --van-cell-line-height | 24px | - |
| --van-cell-vertical-padding | 10px | - |
| --van-cell-horizontal-padding | var(--van-padding-md) | - |
| --van-cell-text-color | var(--van-text-color) | - |
| --van-cell-background-color | var(--van-white) | - |
| --van-cell-border-color | var(--van-border-color) | - |
| --van-cell-active-color | var(--van-active-color) | - |
| --van-cell-required-color | var(--van-danger-color) | - |
| --van-cell-label-color | var(--van-gray-6) | - |
| --van-cell-label-font-size | var(--van-font-size-sm) | - |
| --van-cell-label-line-height | var(--van-line-height-sm) | - |
| --van-cell-label-margin-top | var(--van-padding-base) | - |
| --van-cell-value-color | var(--van-gray-6) | - |
| --van-cell-icon-size | 16px | - |
| --van-cell-right-icon-color | var(--van-gray-6) | - |
| --van-cell-large-vertical-padding | var(--van-padding-sm) | - |
| --van-cell-large-title-font-size | var(--van-font-size-lg) | - |
| --van-cell-large-label-font-size | var(--van-font-size-md) | - |
| --van-cell-group-background-color | var(--van-white) | - |
| --van-cell-group-title-color | var(--van-gray-6) | - |
| --van-cell-group-title-padding | var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) | - |
| --van-cell-group-title-font-size | var(--van-font-size-md) | - |
| --van-cell-group-title-line-height | 16px | - |
| --van-cell-group-inset-padding | 0 var(--van-padding-md) | - |
| --van-cell-group-inset-border-radius | var(--van-border-radius-lg) | - |
| --van-cell-group-inset-title-padding | var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) var(--van-padding-xl) | - |
用于配置 Vant 组件的主题样式，从 3.1.0 版本开始支持。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ConfigProvider } from 'vant';const app = createApp();app.use(ConfigProvider);Vant 组件通过丰富的 CSS 变量 来组织样式，通过覆盖这些 CSS 变量，可以实现定制主题、动态切换主题等效果。
以 Button 组件为例，查看组件的样式，可以看到 .van-button--primary 类名上存在以下变量：
.van-button--primary { color: var(--van-button-primary-color); background-color: var(--van-button-primary-background-color);}这些变量的默认值被定义在 root 节点上，HTML 文档的任何节点都可以访问到这些变量：
:root { --van-white: #fff; --van-blue: #1989fa; --van-button-primary-color: var(--van-white); --van-button-primary-background-color: var(--van-primary-color);}你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：
/* 添加这段样式后，Primary Button 会变成红色 */:root { --van-button-primary-background-color: red;}ConfigProvider 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 ConfigProvider 组件，并通过 theme-vars 属性来配置一些主题变量。
<van-config-provider :theme-vars="themeVars"> <van-form> <van-field name="rate" label="评分"> <template #input> <van-rate v-model="rate" /> </template> </van-field> <van-field name="slider" label="滑块"> <template #input> <van-slider v-model="slider" /> </template> </van-field> <div style="margin: 16px"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div> </van-form></van-config-provider>import { ref } from 'vue';export default { setup() { const rate = ref(4); const slider = ref(50); // themeVars 内的值会被转换成对应 CSS 变量 // 比如 sliderBarHeight 会转换成 `--van-slider-bar-height` const themeVars = { rateIconFullColor: '#07c160', sliderBarHeight: '4px', sliderButtonWidth: '20px', sliderButtonHeight: '20px', sliderActiveBackgroundColor: '#07c160', buttonPrimaryBorderColor: '#07c160', buttonPrimaryBackgroundColor: '#07c160', }; return { rate, slider, themeVars, }; },};注意：ConfigProvider 仅影响它的子组件的样式，不影响全局 root 节点。
Vant 中的 CSS 变量分为 基础变量 和 组件变量。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。
由于 CSS 变量继承机制的原因， 两者的修改方式有一定差异：
下面是所有的基础变量：
// Color Palette--van-black: #000;--van-white: #fff;--van-gray-1: #f7f8fa;--van-gray-2: #f2f3f5;--van-gray-3: #ebedf0;--van-gray-4: #dcdee0;--van-gray-5: #c8c9cc;--van-gray-6: #969799;--van-gray-7: #646566;--van-gray-8: #323233;--van-red: #ee0a24;--van-blue: #1989fa;--van-orange: #ff976a;--van-orange-dark: #ed6a0c;--van-orange-light: #fffbe8;--van-green: #07c160;// Gradient Colors--van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24);--van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);// Component Colors--van-primary-color: var(--van-blue);--van-success-color: var(--van-green);--van-danger-color: var(--van-red);--van-warning-color: var(--van-orange);--van-text-color: var(--van-gray-8);--van-active-color: var(--van-gray-2);--van-active-opacity: 0.7;--van-disabled-opacity: 0.5;--van-background-color: var(--van-gray-1);--van-background-color-light: #fafafa;--van-text-link-color: #576b95;// Padding--van-padding-base: 4px;--van-padding-xs: 8px;--van-padding-sm: 12px;--van-padding-md: 16px;--van-padding-lg: 24px;--van-padding-xl: 32px;// Font--van-font-size-xs: 10px;--van-font-size-sm: 12px;--van-font-size-md: 14px;--van-font-size-lg: 16px;--van-font-weight-bold: 500;--van-line-height-xs: 14px;--van-line-height-sm: 18px;--van-line-height-md: 20px;--van-line-height-lg: 22px;--van-base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;--van-price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif;// Animation--van-animation-duration-base: 0.3s;--van-animation-duration-fast: 0.2s;--van-animation-timing-function-enter: ease-out;--van-animation-timing-function-leave: ease-in;// Border--van-border-color: var(--van-gray-3);--van-border-width-base: 1px;--van-border-radius-sm: 2px;--van-border-radius-md: 4px;--van-border-radius-lg: 8px;--van-border-radius-max: 999px;你可以在各个组件文档底部的表格中查看组件变量。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| theme-vars | 自定义主题变量 | object | - |
tag v3.1.2 | 根节点对应的 HTML 标签名 | string | div |
icon-prefix v3.1.3 | 所有图标的类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过 icon 属性引用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Icon } from 'vant';const app = createApp();app.use(Icon);通过 name 属性来指定需要使用的图标，Vant 内置了一套图标库（见右侧示例），可以直接传入对应的名称来使用。
<van-icon name="chat-o" />你也可以直接在 name 属性中传入一个图片 URL 来作为图标。
<van-icon name="https://b.yzcdn.cn/vant/icon-demo-1126.png" />设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-icon name="chat-o" dot /><van-icon name="chat-o" badge="9" /><van-icon name="chat-o" badge="99+" />通过 color 属性来设置图标的颜色。
<van-icon name="cart-o" color="#1989fa" /><van-icon name="fire-o" color="#ee0a24" />通过 size 属性来设置图标的尺寸大小，可以指定任意 CSS 单位。
<!-- 不指定单位，默认使用 px --><van-icon name="chat-o" size="40" /><!-- 指定使用 rem 单位 --><van-icon name="chat-o" size="3rem" />如果需要在现有 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" />https://vant-contrib.gitee.io/vant/v3/mobile.html#/zh-CN/icon有vant的默认自带的图标可供选用！
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 图标名称或图片链接 | string | - |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| color | 图标颜色 | string | inherit |
| size | 图标大小，如 20px 2em，默认单位为 px | number | string | inherit |
| class-prefix | 类名前缀，用于使用自定义图标 | string | van-icon |
| tag | 根节点对应的 HTML 标签名 | string | i |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击图标时触发 | event: MouseEvent |
增强版的 img 标签，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Image as VanImage } from 'vant';const app = createApp();app.use(VanImage);基础用法与原生 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 { createApp } from 'vue';import { Lazyload } from 'vant';const app = createApp();app.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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| src | 图片链接 | string | - |
| fit | 图片填充模式 | string | fill |
| alt | 替代文本 | string | - |
| width | 宽度，默认单位为 px | number | string | - |
| height | 高度，默认单位为 px | number | string | - |
| radius | 圆角大小，默认单位为 px | number | string | 0 |
| round | 是否显示为圆形 | boolean | false |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| show-error | 是否展示图片加载失败提示 | boolean | true |
| show-loading | 是否展示图片加载中提示 | boolean | true |
| error-icon | 失败时提示的图标名称或图片链接 | string | photo-fail |
| loading-icon | 加载时提示的图标名称或图片链接 | string | photo |
icon-size v3.0.11 | 加载图标和失败图标的大小 | number | string | 32px |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| 名称 | 含义 |
|---|---|
| contain | 保持宽高缩放图片，使图片的长边能完全显示出来 |
| cover | 保持宽高缩放图片，使图片的短边能完全显示出来，裁剪长边 |
| fill | 拉伸图片，使图片填满元素 |
| none | 保持图片原有尺寸 |
| scale-down | 取 none 或 contain 中较小的一个 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击图片时触发 | event: MouseEvent |
| load | 图片加载完毕时触发 | - |
| error | 图片加载失败时触发 | - |
| 名称 | 说明 |
|---|---|
| default | 自定义图片下方的内容 |
| loading | 自定义加载中的提示内容 |
| error | 自定义加载失败时的提示内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-image-placeholder-text-color | var(--van-gray-6) | - |
| --van-image-placeholder-font-size | var(--van-font-size-md) | - |
| --van-image-placeholder-background-color | var(--van-background-color) | - |
| --van-image-loading-icon-size | 32px | - |
| --van-image-loading-icon-color | var(--van-gray-4) | - |
| --van-image-error-icon-size | 32px | - |
| --van-image-error-icon-color | var(--van-gray-4) | - |
在 .vue 文件中通过相对路径引用本地图片时，需要在图片的链接外包上一层 require()，将图片 URL 转换为 webpack 模块请求，并结合 file-loader 或者 url-loader 进行处理。
<!-- 错误写法 --><van-image src="./image.png" /><!-- 正确写法 --><van-image :src="require('./image.png')" /> 对此更详细的解释可以参考 vue-loader 的处理资源路径章节。
使用 Image 组件时，可能会遇到将 <image> 作为标签名时无法渲染的问题，比如下面的写法：
<template> <image src="xxx" /></template><script>import { Image } from 'vant';export default { components: { Image, },};<script>这是因为 <image> 标签是原生的 SVG 标签，Vue 不允许将原生标签名注册为组件名，使用 <van-image> 即可规避这个问题。
Layout 提供了 van-row 和 van-col 两个组件来进行行列布局。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Col, Row } from 'vant';const app = createApp();app.use(Col);app.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>通过 justify 属性可以设置主轴上内容的对齐方式，等价于 flex 布局中的 justify-content 属性。
<!-- 居中 --><van-row 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 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 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 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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| gutter | 列元素之间的间距（单位为 px） | number | string | - |
| tag | 自定义元素标签 | string | div |
| justify | 主轴对齐方式，可选值为 end centerspace-around space-between | string | start |
| align | 交叉轴对齐方式，可选值为 center bottom | string | top |
wrap v3.0.11 | 是否自动换行 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| span | 列元素宽度 | number | string | - |
| offset | 列元素偏移距离 | number | string | - |
| tag | 自定义元素标签 | string | div |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Popup } from 'vant';const app = createApp();app.use(Popup);通过 v-model:show 控制弹出层是否展示。
<van-cell is-link @click="showPopup">展示弹出层</van-cell><van-popup v-model:show="show">内容</van-popup>import { ref } from 'vue';export default { setup() { const show = ref(false); const showPopup = () => { show.value = true; }; return { show, showPopup, }; },};通过 position 属性设置弹出位置，默认居中弹出，可以设置为 top、bottom、left、right。
<van-popup v-model:show="show" position="top" :style="{ height: '30%' }" />设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用 close-icon-position 属性可以自定义图标位置。
<van-popup v-model:show="show" closeable position="bottom" :style="{ height: '30%' }"/><!-- 自定义图标 --><van-popup v-model:show="show" closeable close-icon="close" position="bottom" :style="{ height: '30%' }"/><!-- 图标位置 --><van-popup v-model:show="show" closeable close-icon-position="top-left" position="bottom" :style="{ height: '30%' }"/>设置 round 属性后，弹窗会根据弹出位置添加不同的圆角样式。
<van-popup v-model:show="show" round position="bottom" :style="{ height: '30%' }"/>弹出层默认挂载到组件标签所在位置，可以通过 teleport 属性指定挂载位置。
<!-- 挂载到 body 节点下 --><van-popup v-model:show="show" teleport="body" /><!-- 挂载到 #app 节点下 --><van-popup v-model:show="show" teleport="#app" /><!-- 挂载到指定的元素下 --><van-popup v-model:show="show" :teleport="myContainer" />export default { setup() { const myContainer = document.querySelector('.my-container'); return { myContainer, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示弹出层 | boolean | false |
| overlay | 是否显示遮罩层 | boolean | true |
| position | 弹出位置，可选值为 top bottom right left | string | center |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| duration | 动画时长，单位秒 | number | string | 0.3 |
| round | 是否显示圆角 | boolean | false |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | false |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| closeable | 是否显示关闭图标 | boolean | false |
| close-icon | 关闭图标名称或图片链接 | string | cross |
| close-icon-position | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
icon-prefix v3.0.18 | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| transition-appear | 是否在初始渲染时启用过渡动画 | boolean | false |
| teleport | 指定挂载的节点 | string | Element | - |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击弹出层时触发 | event: MouseEvent |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| click-close-icon | 点击关闭图标时触发 | event: MouseEvent |
| open | 打开弹出层时触发 | - |
| close | 关闭弹出层时触发 | - |
| opened | 打开弹出层且动画结束后触发 | - |
| closed | 关闭弹出层且动画结束后触发 | - |
| 名称 | 说明 |
|---|---|
| default | 弹窗内容 |
overlay-content v3.0.18 | 遮罩层的内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-popup-background-color | var(--van-white) | - |
| --van-popup-transition | transform var(--van-animation-duration-base) | - |
| --van-popup-round-border-radius | 16px | - |
| --van-popup-close-icon-size | 22px | - |
| --van-popup-close-icon-color | var(--van-gray-5) | - |
| --van-popup-close-icon-active-color | var(--van-gray-6) | - |
| --van-popup-close-icon-margin | 16px | - |
| --van-popup-close-icon-z-index | 1 | - |
Vant 中默认包含了一些常用样式，可以直接通过 className 的方式使用。
当文本内容长度超过容器最大宽度时，自动省略多余的文本。
<!-- 最多显示一行 --><div class="van-ellipsis">这是一段最多显示一行的文字，多余的内容会被省略</div><!-- 最多显示两行 --><div class="van-multi-ellipsis--l2"> 这是一段最多显示两行的文字，多余的内容会被省略</div><!-- 最多显示三行 --><div class="van-multi-ellipsis--l3"> 这是一段最多显示三行的文字，多余的内容会被省略</div>为元素添加 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>为元素添加底部安全区适配。
<div class="van-safe-area-bottom"></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>在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Toast } from 'vant';const app = createApp();app.use(Toast);
Toast('提示内容');使用 Toast.loading 方法展示加载提示，通过 forbidClick 属性可以禁用背景点击。
Toast.loading({ message: '加载中...', forbidClick: true,});使用 Toast.success 方法展示成功提示，使用 Toast.fail 方法展示失败提示。
Toast.success('成功文案');Toast.fail('失败文案');通过 icon 选项可以自定义图标，支持传入图标名称或图片链接，通过loadingType 属性可以自定义加载图标类型。
Toast({ message: '自定义图标', icon: 'like-o',});Toast({ message: '自定义图片', icon: 'https://img.yzcdn.cn/vant/logo.png',});Toast.loading({ message: '加载中...', forbidClick: true, loadingType: 'spinner',});Toast 默认渲染在屏幕正中位置，通过 position 属性可以控制 Toast 展示的位置。
Toast({ message: '顶部展示', position: 'top',});Toast({ message: '底部展示', position: 'bottom',});执行 Toast 方法时会返回对应的 Toast 实例，通过修改实例上的 message 属性可以实现动态更新提示的效果。
const toast = Toast.loading({ duration: 0, forbidClick: true, message: '倒计时 3 秒',});let second = 3;const timer = setInterval(() => { second--; if (second) { toast.message = `倒计时 ${second} 秒`; } else { clearInterval(timer); Toast.clear(); }}, 1000);通过 app.use 全局注册 Toast 组件后，会自动在 app 的所有子组件上挂载 $toast 方法，便于在组件内调用。
export default { mounted() { this.$toast('提示文案'); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例：
Toast.allowMultiple();const toast1 = Toast('第一个 Toast');const toast2 = Toast.success('第二个 Toast');toast1.clear();toast2.clear();通过 Toast.setDefaultOptions 函数可以全局修改 Toast 的默认配置。
Toast.setDefaultOptions({ duration: 2000 });Toast.setDefaultOptions('loading', { forbidClick: true });Toast.resetDefaultOptions();Toast.resetDefaultOptions('loading');| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Toast | 展示提示 | options | message | toast 实例 |
| Toast.loading | 展示加载提示 | options | message | toast 实例 |
| Toast.success | 展示成功提示 | options | message | toast 实例 |
| Toast.fail | 展示失败提示 | options | message | toast 实例 |
| Toast.clear | 关闭提示 | clearAll: boolean | void |
| Toast.allowMultiple | 允许同时存在多个 Toast | - | void |
| Toast.setDefaultOptions | 修改默认配置，对所有 Toast 生效。 传入 type 可以修改指定类型的默认配置 | type | options | void |
| Toast.resetDefaultOptions | 重置默认配置，对所有 Toast 生效。 传入 type 可以重置指定类型的默认配置 | type | void |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 提示类型，可选值为 loading successfail html | string | text |
| position | 位置，可选值为 top bottom | string | middle |
| message | 文本内容，支持通过
换行 | string | '' |
| icon | 自定义图标，支持传入图标名称或图片链接 | string | - |
| iconSize | 图标大小，如 20px 2em，默认单位为 px | number | string | 36px |
| iconPrefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| overlay | 是否显示背景遮罩层 | boolean | false |
| forbidClick | 是否禁止背景点击 | boolean | false |
| closeOnClick | 是否在点击后关闭 | boolean | false |
| closeOnClickOverlay | 是否在点击遮罩层后关闭 | boolean | false |
| loadingType | 加载图标类型, 可选值为 spinner | string | circular |
| duration | 展示时长(ms)，值为 0 时，toast 不会消失 | number | 2000 |
| className | 自定义类名 | string | Array | object | - |
overlayClass v3.0.4 | 自定义遮罩层类名 | string | Array | object | - |
overlayStyle v3.0.4 | 自定义遮罩层样式 | object | - |
| onOpened | 完全展示后的回调函数 | Function | - |
| onClose | 关闭时的回调函数 | Function | - |
| transition | 动画类名，等价于 transition 的name属性 | string | van-fade |
| teleport | 指定挂载的节点，用法示例 | string | Element | body |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-toast-max-width | 70% | - |
| --van-toast-font-size | var(--van-font-size-md) | - |
| --van-toast-text-color | var(--van-white) | - |
| --van-toast-loading-icon-color | var(--van-white) | - |
| --van-toast-line-height | var(--van-line-height-md) | - |
| --van-toast-border-radius | var(--van-border-radius-lg) | - |
| --van-toast-background-color | fade(var(--van-black), 70%) | - |
| --van-toast-icon-size | 36px | - |
| --van-toast-text-min-width | 96px | - |
| --van-toast-text-padding | var(--van-padding-xs) var(--van-padding-sm) | - |
| --van-toast-default-padding | var(--van-padding-md) | - |
| --van-toast-default-width | 88px | - |
| --van-toast-default-min-height | 88px | - |
| --van-toast-position-top-distance | 20% | - |
| --van-toast-position-bottom-distance | 20% | - |
日历组件用于选择日期或日期区间。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Calendar } from 'vant';const app = createApp();app.use(Calendar);下面演示了结合单元格来使用日历组件的用法，日期选择完成后会触发 confirm 事件。
<van-cell title="选择单个日期" :value="date" @click="show = true" /><van-calendar v-model:show="show" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const date = ref(''); const show = ref(false); const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`; const onConfirm = (value) => { show.value = false; date.value = formatDate(value); }; return { date, show, onConfirm, }; },};设置 type 为 multiple 后可以选择多个日期，此时 confirm 事件返回的 date 为数组结构，数组包含若干个选中的日期。
<van-cell title="选择多个日期" :value="text" @click="show = true" /><van-calendar v-model:show="show" type="multiple" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const text = ref(''); const show = ref(false); const onConfirm = (dates) => { show.value = false; text.value = `选择了 ${dates.length} 个日期`; }; return { text, show, onConfirm, }; },};设置 type 为 range 后可以选择日期区间，此时 confirm 事件返回的 date 为数组结构，数组第一项为开始时间，第二项为结束时间。
<van-cell title="选择日期区间" :value="date" @click="show = true" /><van-calendar v-model:show="show" type="range" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const date = ref(''); const show = ref(false); const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`; const onConfirm = (values) => { const [start, end] = values; show.value = false; date.value = `${formatDate(start)} - ${formatDate(end)}`; }; return { date, show, onConfirm, }; },};Tips: 默认情况下，日期区间的起止时间不能为同一天，可以通过设置 allow-same-day 属性来允许选择同一天。
将 show-confirm 设置为 false 可以隐藏确认按钮，这种情况下选择完成后会立即触发 confirm 事件。 
<van-calendar v-model:show="show" :show-confirm="false" />通过 color 属性可以自定义日历的颜色，对选中日期和底部按钮生效。
<van-calendar v-model:show="show" color="#1989fa" />通过 min-date 和 max-date 定义日历的范围。
<van-calendar v-model:show="show" :min-date="minDate" :max-date="maxDate" />import { ref } from 'vue';export default { setup() { const show = ref(false); return { show, minDate: new Date(2010, 0, 1), maxDate: new Date(2010, 0, 31), }; },};通过 confirm-text 设置按钮文字，通过 confirm-disabled-text 设置按钮禁用时的文字。
<van-calendar v-model:show="show" type="range" confirm-text="完成" confirm-disabled-text="请选择结束时间"/>通过传入 formatter 函数来对日历上每一格的内容进行格式化。
<van-calendar v-model:show="show" type="range" :formatter="formatter" />export default { setup() { const 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; }; return { formatter, }; },};通过 position 属性自定义弹出层的弹出位置，可选值为 top、left、right。
<van-calendar v-model:show="show" :round="false" position="right" />选择日期区间时，可以通过 max-range 属性来指定最多可选天数，选择的范围超过最多可选天数时，会弹出相应的提示文案。
<van-calendar type="range" :max-range="3" :style="{ height: '500px' }" />通过 first-day-of-week 属性设置一周从哪天开始。
<van-calendar first-day-of-week="1" />将 poppable 设置为 false，日历会直接展示在页面内，而不是以弹层的形式出现。
<van-calendar title="日历" :poppable="false" :show-confirm="false" :style="{ height: '500px' }"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 选择类型: single 表示选择单个日期， multiple 表示选择多个日期， range 表示选择日期区间 | string | single |
| title | 日历标题 | string | 日期选择 |
| color | 主题色，对底部按钮和选中日期生效 | string | #ee0a24 |
| min-date | 可选择的最小日期 | Date | 当前日期 |
| max-date | 可选择的最大日期 | Date | 当前日期的六个月后 |
| default-date | 默认选中的日期，type 为 multiple 或 range 时为数组，传入 null 表示默认不选择 | Date | Date[] | null | 今天 |
| row-height | 日期行高 | number | string | 64 |
| formatter | 日期格式化函数 | (day: Day) => Day | - |
| poppable | 是否以弹层的形式展示日历 | boolean | true |
| lazy-render | 是否只渲染可视区域的内容 | boolean | true |
| show-mark | 是否显示月份背景水印 | boolean | true |
| show-title | 是否展示日历标题 | boolean | true |
| show-subtitle | 是否展示日历副标题（年月） | boolean | true |
| show-confirm | 是否展示确认按钮 | boolean | true |
| readonly | 是否为只读状态，只读状态下不能选择日期 | boolean | false |
| confirm-text | 确认按钮的文字 | string | 确定 |
| confirm-disabled-text | 确认按钮处于禁用状态时的文字 | string | 确定 |
| first-day-of-week | 设置周起始日 | 0-6 | 0 |
当 Calendar 的 poppable 为 true 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示日历弹窗 | boolean | false |
| position | 弹出位置，可选值为 top right left | string | bottom |
| round | 是否显示圆角弹窗 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，用法示例 | string | Element | - |
当 Calendar 的 type 为 range 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| max-range | 日期区间最多可选天数 | number | string | 无限制 |
| range-prompt | 范围选择超过最多可选天数时的提示文案 | string | 选择天数不能超过 xx 天 |
| show-range-prompt | 范围选择超过最多可选天数时，是否展示提示文案 | boolean | true |
| allow-same-day | 是否允许日期范围的起止时间为同一天 | boolean | false |
当 Calendar 的 type 为 multiple 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| max-range | 日期最多可选天数 | number | string | 无限制 |
| range-prompt | 选择超过最多可选天数时的提示文案 | string | 选择天数不能超过 xx 天 |
日历中的每个日期都对应一个 Day 对象，通过formatter属性可以自定义 Day 对象的内容
| 键名 | 说明 | 类型 |
|---|---|---|
| date | 日期对应的 Date 对象 | Date |
| type | 日期类型，可选值为 selected、start、middle、end、disabled | string |
| text | 中间显示的文字 | string |
| topInfo | 上方的提示信息 | string |
| bottomInfo | 下方的提示信息 | string |
| className | 额外类名 | string |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击并选中任意日期时触发 | value: Date | Date[] |
| confirm | 日期选择完成后触发，若 show-confirm 为 true，则点击确认按钮后触发 | value: Date | Date[] |
| open | 打开弹出层时触发 | - |
| close | 关闭弹出层时触发 | - |
| opened | 打开弹出层且动画结束后触发 | - |
| closed | 关闭弹出层且动画结束后触发 | - |
| unselect | 当日历组件的 type 为 multiple 时，取消选中日期时触发 | value: Date |
| month-show | 当某个月份进入可视区域时触发 | { date: Date, title: string } |
| over-range | 范围选择超过最多可选天数时触发 | - |
click-subtitle v3.1.3 | 点击日历副标题时触发 | event: MouseEvent |
| 名称 | 说明 | 参数 |
|---|---|---|
| title | 自定义标题 | - |
subtitle v3.1.3 | 自定义日历副标题 | - |
| footer | 自定义底部区域内容 | - |
top-info v3.0.17 | 自定义日期上方的提示信息 | day: Day |
bottom-info v3.0.17 | 自定义日期下方的提示信息 | day: Day |
通过 ref 可以获取到 Calendar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| reset | 将选中的日期重置到指定日期，未传参时会重置到默认日期 | date?: Date | Date[] | - |
| scrollToDate | 滚动到某个日期 | date: Date | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-calendar-background-color | var(--van-white) | - |
| --van-calendar-popup-height | 80% | - |
| --van-calendar-header-box-shadow | 0 2px 10px rgba(125, 126, 128, 0.16) | - |
| --van-calendar-header-title-height | 44px | - |
| --van-calendar-header-title-font-size | var(--van-font-size-lg) | - |
| --van-calendar-header-subtitle-font-size | var(--van-font-size-md) | - |
| --van-calendar-weekdays-height | 30px | - |
| --van-calendar-weekdays-font-size | var(--van-font-size-sm) | - |
| --van-calendar-month-title-font-size | var(--van-font-size-md) | - |
| --van-calendar-month-mark-color | fade(var(--van-gray-2), 80%) | - |
| --van-calendar-month-mark-font-size | 160px | - |
| --van-calendar-day-height | 64px | - |
| --van-calendar-day-font-size | var(--van-font-size-lg) | - |
| --van-calendar-range-edge-color | var(--van-white) | - |
| --van-calendar-range-edge-background-color | var(--van-danger-color) | - |
| --van-calendar-range-middle-color | var(--van-danger-color) | - |
| --van-calendar-range-middle-background-opacity | 0.1 | - |
| --van-calendar-selected-day-size | 54px | - |
| --van-calendar-selected-day-color | var(--van-white) | - |
| --van-calendar-info-font-size | var(--van-font-size-xs) | - |
| --van-calendar-info-line-height | var(--van-line-height-xs) | - |
| --van-calendar-selected-day-background-color | var(--van-danger-color) | - |
| --van-calendar-day-disabled-color | var(--van-gray-5) | - |
| --van-calendar-confirm-button-height | 36px | - |
| --van-calendar-confirm-button-margin | 7px 0 | - |
如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
级联选择框，用于多层级数据的选择，典型场景为省市区选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Cascader } from 'vant';const app = createApp();app.use(Cascader);级联选择组件可以搭配 Field 和 Popup 组件使用，示例如下：
<van-field v-model="state.fieldValue" is-link readonly label="地区" placeholder="请选择所在地区" @click="state.show = true"/><van-popup v-model:show="state.show" round position="bottom"> <van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="options" @close="state.show = false" @finish="onFinish" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, fieldValue: '', cascaderValue: '', }); // 选项列表，children 代表子选项，支持多级嵌套 const options = [ { text: '浙江省', value: '330000', children: [{ text: '杭州市', value: '330100' }], }, { text: '江苏省', value: '320000', children: [{ text: '南京市', value: '320100' }], }, ]; // 全部选项选择完毕后，会触发 finish 事件 const onFinish = ({ selectedOptions }) => { state.show = false; state.fieldValue = selectedOptions.map((option) => option.text).join('/'); }; return { state, options, onFinish, }; },};通过 active-color 属性来设置选中状态的高亮颜色。
<van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="options" active-color="#1989fa" @close="state.show = false" @finish="onFinish"/>可以监听 change 事件并动态设置 options，实现异步加载选项。
<van-field v-model="state.fieldValue" is-link readonly label="地区" placeholder="请选择所在地区" @click="state.show = true"/><van-popup v-model:show="state.show" round position="bottom"> <van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="state.options" @close="state.show = false" @change="onChange" @finish="onFinish" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, fieldValue: '', cascaderValue: '', options: [ { text: '浙江省', value: '330000', children: [], }, ], }); const onChange = ({ value }) => { if (value === state.options[0].value) { setTimeout(() => { state.options[0].children = [ { text: '杭州市', value: '330100' }, { text: '宁波市', value: '330200' }, ]; }, 500); } }; const onFinish = ({ selectedOptions }) => { state.show = false; state.fieldValue = selectedOptions.map((option) => option.text).join('/'); }; return { state, onChange, onFinish, }; },};通过 field-names 属性可以自定义 options 里的字段名称。
<van-cascader v-model="code" title="请选择所在地区" :options="options" :field-names="fieldNames"/>import { ref } from 'vue';export default { setup() { const code = ref(''); const fieldNames = { text: 'name', value: 'code', children: 'items', }; const options = [ { name: '浙江省', code: '330000', items: [{ name: '杭州市', code: '330100' }], }, { name: '江苏省', code: '320000', items: [{ name: '南京市', code: '320100' }], }, ]; return { code, options, fieldNames, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 顶部标题 | string | - |
| value | 选中项的值 | string | number | - |
| options | 可选项数据源 | Option[] | [] |
| placeholder | 未选中时的提示文案 | string | 请选择 |
| active-color | 选中状态的高亮颜色 | string | #ee0a24 |
swipeable v3.0.11 | 是否开启手势左右滑动切换 | boolean | false |
| closeable | 是否显示关闭图标 | boolean | true |
close-icon v3.0.10 | 关闭图标名称或图片链接 | string | cross |
field-names v3.0.4 | 自定义 options 结构中的字段 | object | { text: 'text', value: 'value', children: 'children' } |
options 属性是一个由对象构成的数组，数组中的每个对象配置一个可选项，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 选项文字（必填） | string |
| value | 选项对应的值（必填） | string | number |
color v3.1.0 | 选项文字颜色 | string |
| children | 子选项列表 | Option[] |
disabled v3.1.2 | 是否禁用选项 | boolean |
className v3.1.0 | 为对应列添加额外的 class | string | Array | object |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| change | 选中项变化时触发 | { value, selectedOptions, tabIndex } |
| finish | 全部选项选择完成后触发 | { value, selectedOptions, tabIndex } |
| close | 点击关闭图标时触发 | - |
| click-tab | 点击标签时触发 | tabIndex: number, title: string |
| 名称 | 说明 | 参数 |
|---|---|---|
| title | 自定义顶部标题 | - |
option v3.1.4 | 自定义选项文字 | { option: Option, selected: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-cascader-header-height | 48px | - |
| --van-cascader-header-padding | 0 var(--van-padding-md) | - |
| --van-cascader-title-font-size | var(--van-font-size-lg) | - |
| --van-cascader-title-line-height | 20px | - |
| --van-cascader-close-icon-size | 22px | - |
| --van-cascader-close-icon-color | var(--van-gray-5) | - |
| --van-cascader-close-icon-active-color | var(--van-gray-6) | - |
| --van-cascader-selected-icon-size | 18px | - |
| --van-cascader-tabs-height | 48px | - |
| --van-cascader-active-color | var(--van-danger-color) | - |
| --van-cascader-options-height | 384px | - |
| --van-cascader-option-disabled-color | van(--van-gray-5) | - |
| --van-cascader-tab-color | var(--van-text-color) | - |
| --van-cascader-unselected-tab-color | var(--van-gray-6) | - |
在一组备选项中进行多选。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Checkbox, CheckboxGroup } from 'vant';const app = createApp();app.use(Checkbox);app.use(CheckboxGroup);通过 v-model 绑定复选框的勾选状态。
<van-checkbox v-model="checked">复选框</van-checkbox>import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked }; },};通过设置 disabled 属性可以禁用复选框。
<van-checkbox v-model="checked" disabled>复选框</van-checkbox>将 shape 属性设置为 square，复选框的形状会变成方形。
<van-checkbox v-model="checked" shape="square">复选框</van-checkbox>通过 checked-color 属性设置选中状态的图标颜色。
<van-checkbox v-model="checked" checked-color="#ee0a24">复选框</van-checkbox>通过 icon-size 属性可以自定义图标的大小。
<van-checkbox v-model="checked" icon-size="24px">复选框</van-checkbox>通过 icon 插槽自定义图标，可以通过 slotProps 判断是否为选中状态.
<van-checkbox v-model="checked"> 自定义图标 <template #icon="props"> <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" /> </template></van-checkbox><style> .img-icon { height: 20px; }</style>import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked, activeIcon: 'https://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png', }; },};设置 label-disabled 属性后，点击图标以外的内容不会触发复选框切换。
<van-checkbox v-model="checked" label-disabled>复选框</van-checkbox>复选框可以与复选框组一起使用，复选框组通过 v-model 数组绑定复选框的勾选状态。
<van-checkbox-group v-model="checked"> <van-checkbox name="a">复选框 a</van-checkbox> <van-checkbox name="b">复选框 b</van-checkbox></van-checkbox-group>import { ref } from 'vue';export default { setup() { const checked = ref(['a', 'b']); return { checked }; },};将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。
<van-checkbox-group v-model="checked" direction="horizontal"> <van-checkbox name="a">复选框 a</van-checkbox> <van-checkbox name="b">复选框 b</van-checkbox></van-checkbox-group>import { ref } from 'vue';export default { setup() { const checked = ref([]); return { checked }; },};通过 max 属性可以限制复选框组的最大可选数。
<van-checkbox-group v-model="checked" :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="checked" 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="primary" @click="toggleAll">反选</van-button>import { ref } from 'vue';export default { setup() { const checked = ref([]); const checkboxGroup = ref(null); const checkAll = () => { checkboxGroup.value.toggleAll(true); } const toggleAll = () => { checkboxGroup.value.toggleAll(); }, return { checked, checkAll, toggleAll, checkboxGroup, }; },};此时你需要再引入 Cell 和 CellGroup 组件，并通过 Checkbox 实例上的 toggle 方法触发切换。
<van-checkbox-group v-model="checked"> <van-cell-group> <van-cell v-for="(item, index) in list" clickable :key="item" :title="`复选框 ${item}`" @click="toggle(index)" > <template #right-icon> <van-checkbox :name="item" :ref="el => checkboxRefs[index] = el" @click.stop /> </template> </van-cell> </van-cell-group></van-checkbox-group>import { ref, onBeforeUpdate } from 'vue';export default { setup() { const checked = ref([]); const checkboxRefs = ref([]); const toggle = (index) => { checkboxRefs.value[index].toggle(); }; onBeforeUpdate(() => { checkboxRefs.value = []; }); return { list: ['a', 'b'], toggle, checked, checkboxRefs, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 是否为选中状态 | boolean | false |
| name | 标识符 | any | - |
| shape | 形状，可选值为 square | string | round |
| disabled | 是否禁用复选框 | boolean | false |
| label-disabled | 是否禁用复选框文本点击 | boolean | false |
| label-position | 文本位置，可选值为 left | string | right |
| icon-size | 图标大小，默认单位为 px | number | string | 20px |
| checked-color | 选中状态颜色 | string | #1989fa |
| bind-group | 是否与复选框组绑定 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 所有选中项的标识符 | any[] | - |
| disabled | 是否禁用所有复选框 | boolean | false |
| max | 最大可选数，0 为无限制 | number | string | 0 |
| direction | 排列方向，可选值为 horizontal | string | vertical |
| icon-size | 所有复选框的图标大小，默认单位为 px | number | string | 20px |
| checked-color | 所有复选框的选中状态颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | checked: boolean |
| click | 点击复选框时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | names: any[] |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义文本 | - |
| icon | 自定义图标 | { checked: boolean, disabled: boolean } |
通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggleAll | 切换所有复选框，传 true 为选中，false 为取消选中，不传参为取反 | options?: boolean | object | - |
const { checkboxGroup } = this.$refs;// 全部反选checkboxGroup.toggleAll();// 全部选中checkboxGroup.toggleAll(true);// 全部取消checkboxGroup.toggleAll(false);// 全部反选，并跳过禁用的复选框checkboxGroup.toggleAll({ skipDisabled: true,});// 全部选中，并跳过禁用的复选框checkboxGroup.toggleAll({ checked: true, skipDisabled: true,});通过 ref 可以获取到 Checkbox 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换选中状态，传 true 为选中，false 为取消选中，不传参为取反 | checked?: boolean | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-checkbox-size | 20px | - |
| --van-checkbox-border-color | var(--van-gray-5) | - |
| --van-checkbox-transition-duration | var(--van-animation-duration-fast) | - |
| --van-checkbox-label-margin | var(--van-padding-xs) | - |
| --van-checkbox-label-color | var(--van-text-color) | - |
| --van-checkbox-checked-icon-color | var(--van-primary-color) | - |
| --van-checkbox-disabled-icon-color | var(--van-gray-5) | - |
| --van-checkbox-disabled-label-color | var(--van-gray-5) | - |
| --van-checkbox-disabled-background-color | var(--van-border-color) | - |
时间选择器，支持日期、年月、时分等维度，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { DatetimePicker } from 'vant';const app = createApp();app.use(DatetimePicker);DatetimePicker 通过 type 属性来定义需要选择的时间类型，type 为 date 表示选择年月日。通过 min-date 和 max-date 属性可以确定可选的时间范围。
<van-datetime-picker v-model="currentDate" type="date" title="选择年月日" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date(2021, 0, 17)); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};将 type 设置为 year-month 即可选择年份和月份。通过传入 formatter 函数，可以对选项文字进行格式化处理。
<van-datetime-picker v-model="currentDate" type="year-month" title="选择年月" :min-date="minDate" :max-date="maxDate" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'year') { return `${val}年`; } if (type === 'month') { return `${val}月`; } return val; }; return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), formatter, currentDate, }; },};将 type 设置为 month-day 即可选择月份和日期。
<van-datetime-picker v-model="currentDate" type="month-day" title="选择月日" :min-date="minDate" :max-date="maxDate" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'month') { return `${val}月`; } if (type === 'day') { return `${val}日`; } return val; }; return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), formatter, currentDate, }; },};将 type 设置为 time 即可选择时间（小时和分钟）。
<van-datetime-picker v-model="currentTime" type="time" title="选择时间" :min-hour="10" :max-hour="20"/>import { ref } from 'vue';export default { setup() { const currentTime = ref('12:00'); return { currentTime }; },};将 type 设置为 datetime 即可选择完整时间，包括年月日和小时、分钟。
<van-datetime-picker v-model="currentDate" type="datetime" title="选择完整时间" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};将 type 设置为 datehour 即可选择日期和小时，包括年月日和小时。
<van-datetime-picker v-model="currentDate" type="datehour" title="选择年月日小时" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};通过传入 filter 函数，可以对选项数组进行过滤，实现自定义时间间隔。
<van-datetime-picker v-model="currentTime" type="time" :filter="filter" />import { ref } from 'vue';export default { setup() { const currentTime = ref('12:00'); const filter = (type, options) => { if (type === 'minute') { return options.filter((option) => Number(option) % 5 === 0); } return options; }; return { filter, currentTime, }; },};
<van-datetime-picker v-model="currentDate" type="date" title="自定义列排序" :columns-order="['month', 'day', 'year']" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'year') { return val + '年'; } if (type === 'month') { return val + '月'; } if (type === 'day') { return val + '日'; } return val; }; return { formatter, currentDate, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 时间类型，可选值为 date timeyear-month month-day datehour | string | datetime |
| title | 顶部栏标题 | string | '' |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| show-toolbar | 是否显示顶部栏 | boolean | true |
| loading | 是否显示加载状态 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法切换选项 | boolean | false |
| filter | 选项过滤函数 | (type: string, values: string[]) => string[] | - |
| formatter | 选项格式化函数 | (type: string, value: string) => string | - |
| columns-order | 自定义列排序数组, 子项可选值为 year、month、day、hour、minute | string[] | - |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位ms | number | string | 1000 |
当时间选择器类型为 date 或 datetime 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| min-date | 可选的最小时间，精确到分钟 | Date | 十年前 |
| max-date | 可选的最大时间，精确到分钟 | Date | 十年后 |
当时间选择器类型为 time 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| min-hour | 可选的最小小时 | number | string | 0 |
| max-hour | 可选的最大小时 | number | string | 23 |
| min-minute | 可选的最小分钟 | number | string | 0 |
| max-minute | 可选的最大分钟 | number | string | 59 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当值变化时触发的事件 | value: 当前选中的时间 |
| confirm | 点击完成按钮时触发的事件 | value: 当前选中的时间 |
| cancel | 点击取消按钮时触发的事件 | - |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | option: string | object |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
通过 ref 可以获取到 DatetimePicker 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| getPicker | 获取 Picker 实例，用于调用 Picker 的实例方法 | - | - |
请注意不要在模板中直接使用类似min-date="new Date()"的写法，这样会导致每次渲染组件时传入一个新的 Date 对象，而传入新的数据会触发下一次渲染，从而陷入死循环。
正确的做法是将min-date作为一个数据定义在data函数中。
如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
参见桌面端适配。
如果仅需要选择年份或者月份，建议直接使用 Picker 组件。
用户可以在文本框内输入或编辑文字。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Field, CellGroup } from 'vant';const app = createApp();app.use(Field);app.use(CellGroup);可以通过 v-model 双向绑定输入框的值，通过 placeholder 设置占位提示文字。
<!-- 可以使用 CellGroup 作为容器 --><van-cell-group inset> <van-field v-model="value" label="文本" placeholder="请输入用户名" /></van-cell-group>import { ref } from 'vue';export default { setup() { const value = ref(''); return { value }; },};根据 type 属性定义不同类型的输入框，默认值为 text。
<van-cell-group inset> <!-- 输入任意文本 --> <van-field v-model="state.text" label="文本" /> <!-- 输入手机号，调起手机号键盘 --> <van-field v-model="state.tel" type="tel" label="手机号" /> <!-- 允许输入正整数，调起纯数字键盘 --> <van-field v-model="state.digit" type="digit" label="整数" /> <!-- 允许输入数字，调起带符号的纯数字键盘 --> <van-field v-model="state.number" type="number" label="数字" /> <!-- 输入密码 --> <van-field v-model="state.password" type="password" label="密码" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ tel: '', text: '', digit: '', number: '', password: '', }); return { state }; },};通过 readonly 将输入框设置为只读状态，通过 disabled 将输入框设置为禁用状态。
<van-cell-group inset> <van-field label="文本" model-value="输入框只读" readonly /> <van-field label="文本" model-value="输入框已禁用" disabled /></van-cell-group>通过 left-icon 和 right-icon 配置输入框两侧的图标，通过设置 clearable 在输入过程中展示清除图标。
<van-cell-group inset> <van-field v-model="state.value1" label="文本" left-icon="smile-o" right-icon="warning-o" placeholder="显示图标" /> <van-field v-model="state.value2" clearable label="文本" left-icon="music-o" placeholder="显示清除图标" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: '', value2: '123', }); return { state }; },};设置 required 属性表示这是一个必填项，可以配合 error 或 error-message 属性显示对应的错误提示。
<van-cell-group inset> <van-field v-model="username" error required label="用户名" placeholder="请输入用户名" /> <van-field v-model="phone" required label="手机号" placeholder="请输入手机号" error-message="手机号格式错误" /></van-cell-group>通过 button 插槽可以在输入框尾部插入按钮。
<van-cell-group inset> <van-field v-model="sms" center clearable label="短信验证码" placeholder="请输入短信验证码" > <template #button> <van-button size="small" type="primary">发送验证码</van-button> </template> </van-field></van-cell-group>通过 formatter 属性可以对输入的内容进行格式化，通过 format-trigger 属性可以指定执行格式化的时机，默认在输入时进行格式化。
<van-cell-group inset> <van-field v-model="state.value1" label="文本" :formatter="formatter" placeholder="在输入时执行格式化" /> <van-field v-model="state.value2" label="文本" :formatter="formatter" format-trigger="onBlur" placeholder="在失焦时执行格式化" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: '', value2: '', }); // 过滤输入的数字 const formatter = (value) => value.replace(/d/g, ''); return { state, formatter, }; },};对于 textarea，可以通过 autosize 属性设置高度自适应。
<van-cell-group inset> <van-field v-model="message" rows="1" autosize label="留言" type="textarea" placeholder="请输入留言" /></van-cell-group>设置 maxlength 和 show-word-limit 属性后会在底部显示字数统计。
<van-cell-group inset> <van-field v-model="message" rows="2" autosize label="留言" type="textarea" maxlength="50" placeholder="请输入留言" show-word-limit /></van-cell-group>通过 input-align 属性可以设置输入框内容的对齐方式，可选值为 center、right。
<van-cell-group inset> <van-field v-model="value" label="文本" placeholder="输入框内容右对齐" input-align="right" /></van-cell-group>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入的值 | number | string | - |
| label | 输入框左侧文本 | string | - |
| name | 名称，提交表单的标识符 | string | - |
| type | 输入框类型, 可选值为 tel digitnumber textarea password 等 | string | text |
| size | 大小，可选值为 large | string | - |
| maxlength | 输入的最大字符数 | number | string | - |
| placeholder | 输入框占位提示文字 | string | - |
| border | 是否显示内边框 | boolean | true |
| disabled | 是否禁用输入框 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法输入内容 | boolean | false |
| colon | 是否在 label 后面添加冒号 | boolean | false |
| required | 是否显示表单必填星号 | boolean | false |
| center | 是否使内容垂直居中 | boolean | false |
| clearable | 是否启用清除图标，点击清除图标后会清空输入框 | boolean | false |
clear-icon v3.0.12 | 清除图标名称或图片链接 | string | clear |
| clear-trigger | 显示清除图标的时机，always 表示输入框不为空时展示， focus 表示输入框聚焦且不为空时展示 | string | focus |
| clickable | 是否开启点击反馈 | boolean | false |
| is-link | 是否展示右侧箭头并开启点击反馈 | boolean | false |
| autofocus | 是否自动聚焦，iOS 系统不支持该属性 | boolean | false |
| show-word-limit | 是否显示字数统计，需要设置 maxlength 属性 | boolean | false |
| error | 是否将输入内容标红 | boolean | false |
| error-message | 底部错误提示文案，为空时不展示 | string | - |
| error-message-align | 错误提示文案对齐方式，可选值为 center right | string | left |
| formatter | 输入内容格式化函数 | (val: string) => string | - |
| format-trigger | 格式化函数触发的时机，可选值为 onBlur | string | onChange |
| arrow-direction | 箭头方向，可选值为 left up down | string | right |
| label-class | 左侧文本额外类名 | string | Array | object | - |
| label-width | 左侧文本宽度，默认单位为 px | number | string | 6.2em |
| label-align | 左侧文本对齐方式，可选值为 center right | string | left |
| input-align | 输入框对齐方式，可选值为 center right | string | left |
| autosize | 是否自适应内容高度，只对 textarea 有效， 可传入对象,如 { maxHeight: 100, minHeight: 50 }， 单位为 px | boolean | object | false |
| left-icon | 左侧图标名称或图片链接 | string | - |
| right-icon | 右侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| rules | 表单校验规则，详见 Form 组件 | Rule[] | - |
autocomplete v3.0.3 | input 标签原生的自动完成属性 | string | - |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 输入框内容变化时触发 | value: string (当前输入的值) |
| focus | 输入框获得焦点时触发 | event: Event |
| blur | 输入框失去焦点时触发 | event: Event |
| clear | 点击清除按钮时触发 | event: MouseEvent |
| click | 点击组件时触发 | event: MouseEvent |
| click-input | 点击输入区域时触发 | event: MouseEvent |
| click-left-icon | 点击左侧图标时触发 | event: MouseEvent |
| click-right-icon | 点击右侧图标时触发 | event: MouseEvent |
通过 ref 可以获取到 Field 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 获取输入框焦点 | - | - |
| blur | 取消输入框焦点 | - | - |
| 名称 | 说明 |
|---|---|
| label | 自定义输入框左侧文本 |
| input | 自定义输入框，使用此插槽后，与输入框相关的属性和事件将失效。 在 Form 组件进行表单校验时，会使用 input 插槽中子组件的 value，而不是 Field 组件的 value。 |
| left-icon | 自定义输入框头部图标 |
| right-icon | 自定义输入框尾部图标 |
| button | 自定义输入框尾部按钮 |
| extra | 自定义输入框最右侧的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-field-label-width | 6.2em | - |
| --van-field-label-color | var(--van-gray-7) | - |
| --van-field-label-margin-right | var(--van-padding-sm) | - |
| --van-field-input-text-color | var(--van-text-color) | - |
| --van-field-input-error-text-color | var(--van-danger-color) | - |
| --van-field-input-disabled-text-color | var(--van-gray-5) | - |
| --van-field-placeholder-text-color | var(--van-gray-5) | - |
| --van-field-icon-size | 16px | - |
| --van-field-clear-icon-size | 16px | - |
| --van-field-clear-icon-color | var(--van-gray-5) | - |
| --van-field-right-icon-color | var(--van-gray-6) | - |
| --van-field-error-message-color | var(--van-danger-color) | - |
| --van-field-error-message-text-color | 12px | - |
| --van-field-text-area-min-height | 60px | - |
| --van-field-word-limit-color | var(--van-gray-7) | - |
| --van-field-word-limit-font-size | var(--van-font-size-sm) | - |
| --van-field-word-limit-line-height | 16px | - |
| --van-field-disabled-text-color | var(--van-gray-5) | - |
| --van-field-required-mark-color | var(--van-red) | - |
HTML 原生的 type="number" 属性在 iOS 和 Android 系统上都存在一定问题，比如 maxlength 属性不生效、无法获取到完整的输入内容等。因此设置 type 为 number 时，Field 不会使用原生的 type="number" 属性，而是用现代浏览器支持的 inputmode 属性来控制输入键盘的类型。
清除按钮监听是的移动端 Touch 事件，参见桌面端适配。
用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型，需要与 Field 输入框 组件搭配使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Form, Field, CellGroup } from 'vant';const app = createApp();app.use(Form);app.use(Field);app.use(CellGroup);在表单中，每个 Field 组件 代表一个表单项，使用 Field 的 rules 属性定义校验规则。
<van-form @submit="onSubmit"> <van-cell-group inset> <van-field v-model="state.username" name="用户名" label="用户名" placeholder="用户名" :rules="[{ required: true, message: '请填写用户名' }]" /> <van-field v-model="state.password" type="password" name="密码" label="密码" placeholder="密码" :rules="[{ required: true, message: '请填写密码' }]" /> </van-cell-group> <div style="margin: 16px;"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div></van-form>import { reactive } from 'vue';export default { setup() { const state = reactive({ username: '', password: '', }); const onSubmit = (values) => { console.log('submit', values); }; return { state, onSubmit, }; },};通过 rules 定义表单校验规则，所有可用字段见下方表格。
<van-form @failed="onFailed"> <van-cell-group inset> <!-- 通过 pattern 进行正则校验 --> <van-field v-model="state.value1" name="pattern" placeholder="正则校验" :rules="[{ pattern, message: '请输入正确内容' }]" /> <!-- 通过 validator 进行函数校验 --> <van-field v-model="state.value2" name="validator" placeholder="函数校验" :rules="[{ validator, message: '请输入正确内容' }]" /> <!-- 通过 validator 返回错误提示 --> <van-field v-model="state.value3" name="validatorMessage" placeholder="校验函数返回错误提示" :rules="[{ validator: validatorMessage }]" /> <!-- 通过 validator 进行异步函数校验 --> <van-field v-model="state.value4" name="asyncValidator" placeholder="异步函数校验" :rules="[{ validator: asyncValidator, message: '请输入正确内容' }]" /> </van-cell-group> <div style="margin: 16px;"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div></van-form>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ value1: '', value2: '', value3: '', value4: '', }); const pattern = /d{6}/; // 校验函数返回 true 表示校验通过，false 表示不通过 const validator = (val) => /1d{10}/.test(val); // 校验函数可以直接返回一段错误提示 const validatorMessage = (val) => `${val} 不合法，请重新输入`; // 校验函数可以返回 Promise，实现异步校验 const asyncValidator = (val) => new Promise((resolve) => { Toast.loading('验证中...'); setTimeout(() => { Toast.clear(); resolve(/d{6}/.test(val)); }, 1000); }); const onFailed = (errorInfo) => { console.log('failed', errorInfo); }; return { state, pattern, onFailed, validator, asyncValidator, }; },};在表单中使用 Switch 组件。
<van-field name="switch" label="开关"> <template #input> <van-switch v-model="checked" size="20" /> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref(false); return { checked }; },};在表单中使用 Checkbox 组件。
<van-field name="checkbox" label="复选框"> <template #input> <van-checkbox v-model="checked" shape="square" /> </template></van-field><van-field name="checkboxGroup" label="复选框组"> <template #input> <van-checkbox-group v-model="groupChecked" direction="horizontal"> <van-checkbox name="1" shape="square">复选框 1</van-checkbox> <van-checkbox name="2" shape="square">复选框 2</van-checkbox> </van-checkbox-group> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref(false); const groupChecked = ref([]); return { checked, groupChecked, }; },};在表单中使用 Radio 组件。
<van-field name="radio" label="单选框"> <template #input> <van-radio-group v-model="checked" direction="horizontal"> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio> </van-radio-group> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked }; },};在表单中使用 Stepper 组件。
<van-field name="stepper" label="步进器"> <template #input> <van-stepper v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(1); return { value }; },};在表单中使用 Rate 组件。
<van-field name="rate" label="评分"> <template #input> <van-rate v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(3); return { value }; },};在表单中使用 Slider 组件。
<van-field name="slider" label="滑块"> <template #input> <van-slider v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(50); return { value }; },};在表单中使用 Uploader 组件。
<van-field name="uploader" label="文件上传"> <template #input> <van-uploader v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref([{ url: 'https://img.yzcdn.cn/vant/leaf.jpg' }]); return { value }; },};在表单中使用 Picker 组件。
<van-field v-model="state.value" readonly clickable name="picker" label="选择器" placeholder="点击选择城市" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" position="bottom"> <van-picker :columns="columns" @confirm="onConfirm" @cancel="state.showPicker = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showPicker: false, }); const columns = ['杭州', '宁波', '温州', '嘉兴', '湖州']; const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, columns, onConfirm, }; },};在表单中使用 DatetimePicker 组件。
<van-field v-model="state.value" readonly clickable name="datetimePicker" label="时间选择" placeholder="点击选择时间" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" position="bottom"> <van-datetime-picker type="time" @confirm="onConfirm" @cancel="state.showPicker = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showPicker: false, }); const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, onConfirm, }; },};在表单中使用 Area 组件。
<van-field v-model="state.value" readonly clickable name="area" label="地区选择" placeholder="点击选择省市区" @click="state.showArea = true"/><van-popup v-model:show="state.showArea" position="bottom"> <van-area :area-list="areaList" @confirm="onConfirm" @cancel="state.showArea = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showArea: false, }); const onConfirm = (value) => { state.showArea = false; state.value = values .filter((item) => !!item) .map((item) => item.name) .join('/'); }; return { state, areaList: {}, // 数据格式见 Area 组件文档 onConfirm, }; },};在表单中使用 Calendar 组件。
<van-field v-model="state.value" readonly clickable name="calendar" label="日历" placeholder="点击选择日期" @click="state.showCalendar = true"/><van-calendar v-model:show="state.showCalendar" @confirm="onConfirm" />import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showCalendar: false, }); const onConfirm = (date) => { state.value = `${date.getMonth() + 1}/${date.getDate()}`; state.showCalendar = false; }; return { state, onConfirm, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label-width | 表单项 label 宽度，默认单位为px | number | string | 6.2em |
| label-align | 表单项 label 对齐方式，可选值为 center right | string | left |
| input-align | 输入框对齐方式，可选值为 center right | string | left |
| error-message-align | 错误提示文案对齐方式，可选值为 center right | string | left |
| validate-trigger | 表单校验触发时机，可选值为 onChange、onSubmit，详见下表 | string | onBlur |
| colon | 是否在 label 后面添加冒号 | boolean | false |
| disabled | 是否禁用表单中的所有输入框 | boolean | false |
| readonly | 是否将表单中的所有输入框设置为只读状态 | boolean | false |
| validate-first | 是否在某一项校验不通过时停止校验 | boolean | false |
| scroll-to-error | 是否在提交表单且校验不通过时滚动至错误的表单项 | boolean | false |
| show-error | 是否在校验不通过时标红输入框 | boolean | false |
| show-error-message | 是否在校验不通过时在输入框下方展示错误提示 | boolean | true |
| submit-on-enter | 是否在按下回车键时提交表单 | boolean | true |
表单项的 API 参见：Field 组件
使用 Field 的rules属性可以定义校验规则，可选属性如下:
| 键名 | 说明 | 类型 |
|---|---|---|
| required | 是否为必选字段 | boolean |
| message | 错误提示文案 | string | (value, rule) => string |
| validator | 通过函数进行校验 | (value, rule) => boolean | string | Promise |
| pattern | 通过正则表达式进行校验 | RegExp |
| trigger | 本项规则的触发时机，可选值为 onChange、onBlur | string |
| formatter | 格式化函数，将表单项的值转换后进行校验 | (value, rule) => any |
通过 validate-trigger 属性可以自定义表单校验的触发时机。
| 值 | 描述 |
|---|---|
| onSubmit | 仅在提交表单时触发校验 |
| onBlur | 在提交表单和输入框失焦时触发校验 |
| onChange | 在提交表单和输入框内容变化时触发校验 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| submit | 提交表单且验证通过后触发 | values: object |
| failed | 提交表单且验证不通过后触发 | errorInfo: { values: object, errors: object[] } |
通过 ref 可以获取到 Form 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| submit | 提交表单，与点击提交按钮的效果等价 | - | - |
| validate | 验证表单，支持传入 name 来验证单个或部分表单项 | name?: string | string[] | Promise |
| resetValidation | 重置表单项的验证提示，支持传入 name 来重置单个或部分表单项 | name?: string | string[] | - |
| scrollToField | 滚动到对应表单项的位置，默认滚动到顶部，第二个参数传 false 可滚动至底部 | name: string, alignToTop: boolean | - |
| 名称 | 说明 |
|---|---|
| default | 表单内容 |
虚拟数字键盘，可以配合密码输入框组件或自定义的输入框组件使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NumberKeyboard } from 'vant';const app = createApp();app.use(NumberKeyboard);数字键盘提供了 input、delete、blur 事件，分别对应输入内容、删除内容和失去焦点的动作。
<van-cell @touchstart.stop="show = true">弹出默认键盘</van-cell><van-number-keyboard :show="show" @blur="show = false" @input="onInput" @delete="onDelete"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(true); const onInput = (value) => Toast(value); const onDelete = () => Toast('删除'); return { show, onInput, onDelete, }; },};点击键盘以外的区域时，键盘会自动收起，通过阻止元素上的 touchstart 事件冒泡可以避免键盘收起。
将 theme 属性设置为 custom 来展示键盘的右侧栏，常用于输入金额的场景。
<van-number-keyboard :show="show" theme="custom" extra-key="." close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 extra-key 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 extra-key 设置为 X。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出身份证号键盘</van-cell><van-number-keyboard :show="show" extra-key="X" close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 title 属性可以设置键盘标题。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出带标题的键盘</van-cell><van-number-keyboard :show="show" title="键盘标题" extra-key="." close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>当 theme 为 custom 时，支持以数组的形式配置两个 extra-key。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出配置多个按键的键盘</van-cell><van-number-keyboard :show="show" :extra-key="['00', '.']" close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 random-key-order 属性可以随机排序数字键盘，常用于安全等级较高的场景。
<van-cell @touchstart.stop="show = true"> 弹出配置随机数字的键盘 </van-cell><van-number-keyboard :show="show" random-key-order @blur="show = false" @input="onInput" @delete="onDelete"/>可以通过 v-model 绑定键盘当前输入值，并通过 maxlength 属性来限制输入长度。
<van-field v-model="value" readonly clickable @touchstart.stop="show = true" /><van-number-keyboard v-model="value" :show="show" :maxlength="6" @blur="show = false"/>import { ref } from 'vue';export default { setup() { const show = ref(true); const value = ref(''); return { show, value, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入值 | string | - |
| show | 是否显示键盘 | boolean | - |
| title | 键盘标题 | string | - |
| theme | 样式风格，可选值为 custom | string | default |
| maxlength | 输入值最大长度 | number | string | - |
| transition | 是否开启过场动画 | boolean | true |
| z-index | 键盘 z-index 层级 | number | string | 100 |
| extra-key | 底部额外按键的内容 | string | string[] | '' |
| close-button-text | 关闭按钮文字，空则不展示 | string | - |
| delete-button-text | 删除按钮文字，空则展示删除图标 | string | - |
| close-button-loading | 是否将关闭按钮设置为加载中状态，仅在 theme="custom" 时有效 | boolean | false |
| show-delete-key | 是否展示删除图标 | boolean | true |
blur-on-close v3.0.6 | 是否在点击关闭按钮时触发 blur 事件 | boolean | true |
| hide-on-click-outside | 是否在点击外部时收起键盘 | boolean | true |
| teleport | 指定挂载的节点，用法示例 | string | Element | - |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| random-key-order | 是否将通过随机顺序展示按键 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| input | 点击按键时触发 | key: 按键内容 |
| delete | 点击删除键时触发 | - |
| close | 点击关闭按钮时触发 | - |
| blur | 点击关闭按钮或非键盘区域时触发 | - |
| show | 键盘完全弹出时触发 | - |
| hide | 键盘完全收起时触发 | - |
| 名称 | 说明 |
|---|---|
| delete | 自定义删除按键内容 |
| extra-key | 自定义左下角按键内容 |
| title-left | 自定义标题栏左侧内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-number-keyboard-background-color | var(--van-gray-2) | - |
| --van-number-keyboard-key-height | 48px | - |
| --van-number-keyboard-key-font-size | 28px | - |
| --van-number-keyboard-key-active-color | var(--van-gray-3) | - |
| --van-number-keyboard-delete-font-size | var(--van-font-size-lg) | - |
| --van-number-keyboard-title-color | var(--van-gray-7) | - |
| --van-number-keyboard-title-height | 34px | - |
| --van-number-keyboard-title-font-size | var(--van-font-size-lg) | - |
| --van-number-keyboard-close-padding | 0 var(--van-padding-md) | - |
| --van-number-keyboard-close-color | var(--van-text-link-color) | - |
| --van-number-keyboard-close-font-size | var(--van-font-size-md) | - |
| --van-number-keyboard-button-text-color | var(--van-white) | - |
| --van-number-keyboard-button-background-color | var(--van-primary-color) | - |
| --van-number-keyboard-z-index | 100 | - |
参见桌面端适配。
带网格的输入框组件，可以用于输入密码、短信验证码等场景，通常与数字键盘组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { PasswordInput, NumberKeyboard } from 'vant';const app = createApp();app.use(PasswordInput);app.use(NumberKeyboard);搭配数字键盘组件来实现密码输入功能。
<!-- 密码输入框 --><van-password-input :value="value" :focused="showKeyboard" @focus="showKeyboard = true"/><!-- 数字键盘 --><van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false"/>import { ref } from 'vue';export default { setup() { const value = ref('123'); const showKeyboard = ref(true); return { value, showKeyboard, }; },};通过 length 属性来设置密码长度。
<van-password-input :value="value" :length="4" :focused="showKeyboard" @focus="showKeyboard = true"/>通过 gutter 属性来设置格子之间的间距。
<van-password-input :value="value" :gutter="10" :focused="showKeyboard" @focus="showKeyboard = true"/>将 mask 设置为 false 可以明文展示输入的内容，适用于短信验证码等场景。
<van-password-input :value="value" :mask="false" :focused="showKeyboard" @focus="showKeyboard = true"/>通过 info 属性设置提示信息，通过 error-info 属性设置错误提示，例如当输入六位时提示密码错误。
<van-password-input :value="value" info="密码为 6 位数字" :error-info="errorInfo" :focused="showKeyboard" @focus="showKeyboard = true"/><van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false"/>import { ref, watch } from 'vue';export default { setup() { const value = ref('123'); const errorInfo = ref(''); const showKeyboard = ref(true); watch(value, (newVal) => { if (newVal.length === 6 && newVal !== '123456') { errorInfo.value = '密码错误'; } else { errorInfo.value = ''; } }); return { value, errorInfo, showKeyboard, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 密码值 | string | '' |
| info | 输入框下方文字提示 | string | - |
| error-info | 输入框下方错误提示 | string | - |
| length | 密码最大长度 | number | string | 6 |
| gutter | 输入框格子之间的间距，如 20px 2em，默认单位为px | number | string | 0 |
| mask | 是否隐藏密码内容 | boolean | true |
| focused | 是否已聚焦，聚焦时会显示光标 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| focus | 输入框聚焦时触发 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-password-input-height | 50px | - |
| --van-password-input-margin | 0 var(--van-padding-md) | - |
| --van-password-input-font-size | 20px | - |
| --van-password-input-border-radius | 6px | - |
| --van-password-input-background-color | var(--van-white) | - |
| --van-password-input-info-color | var(--van-gray-6) | - |
| --van-password-input-info-font-size | var(--van-font-size-md) | - |
| --van-password-input-error-info-color | var(--van-danger-color) | - |
| --van-password-input-dot-size | 10px | - |
| --van-password-input-dot-color | var(--van-black) | - |
| --van-password-input-cursor-color | var(--van-text-color) | - |
| --van-password-input-cursor-width | 1px | - |
| --van-password-input-cursor-height | 40% | - |
| --van-password-input-cursor-animation-duration | 1s | - |
提供多个选项集合供用户选择，支持单列选择和多列级联，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Picker } from 'vant';const app = createApp();app.use(Picker);Picker 组件通过 columns 属性配置选项数据，columns 是一个包含字符串或对象的数组。
顶部栏包含标题、确认按钮和取消按钮，点击确认按钮触发 confirm 事件，点击取消按钮触发 cancel 事件。
<van-picker title="标题" :columns="columns" @confirm="onConfirm" @cancel="onCancel" @change="onChange"/>import { Toast } from 'vant';export default { setup() { const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华']; const onConfirm = (value, index) => { Toast(`当前值: ${value}, 当前索引: ${index}`); }; const onChange = (value, index) => { Toast(`当前值: ${value}, 当前索引: ${index}`); }; const onCancel = () => Toast('取消'); return { columns, onChange, onCancel, onConfirm, }; },};单列选择时，可以通过 default-index 属性设置初始选中项的索引。
<van-picker title="标题" :columns="columns" :default-index="2" />columns 属性可以通过对象数组的形式配置多列选择，对象中可以配置选项数据、初始选中项等，详细格式见下方表格。
<van-picker title="标题" :columns="columns" />export default { setup() { const columns = [ // 第一列 { values: ['周一', '周二', '周三', '周四', '周五'], defaultIndex: 2, }, // 第二列 { values: ['上午', '下午', '晚上'], defaultIndex: 1, }, ]; return { columns }; },};使用 columns 的 children 字段可以实现选项级联的效果。如果级联层级较多，推荐使用 Cascader 级联选项组件。
<van-picker title="标题" :columns="columns" />export default { setup() { const columns = [ { text: '浙江', children: [ { text: '杭州', children: [{ text: '西湖区' }, { text: '余杭区' }], }, { text: '温州', children: [{ text: '鹿城区' }, { text: '瓯海区' }], }, ], }, { text: '福建', children: [ { text: '福州', children: [{ text: '鼓楼区' }, { text: '台江区' }], }, { text: '厦门', children: [{ text: '思明区' }, { text: '海沧区' }], }, ], }, ]; return { columns }; },};级联选择的数据嵌套深度需要保持一致，如果部分选项没有子选项，可以使用空字符串进行占位。
选项可以为对象结构，通过设置 disabled 来禁用该选项。
<van-picker :columns="columns" />export default { setup() { const columns = [ { text: '杭州', disabled: true }, { text: '宁波' }, { text: '温州' }, ]; return { columns }; },};通过 Picker 上的实例方法可以更灵活地控制选择器，比如使用 setColumnValues 方法实现多列联动。
<van-picker ref="picker" :columns="columns" @change="onChange" />import { ref } from 'vue';export default { setup() { const picker = ref(null); const cities = { 浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'], 福建: ['福州', '厦门', '莆田', '三明', '泉州'], }; const columns = [ { values: Object.keys(cities) }, { values: cities['浙江'] }, ]; const onChange = (values) => { picker.value.setColumnValues(1, cities[values[0]]); }; return { picker, columns, onChange, }; },};若选择器数据是异步获取的，可以通过 loading 属性显示加载提示。
<van-picker :columns="state.columns" :loading="state.loading" />import { reactive } from 'vue';export default { setup() { const state = reactive({ columns: [], loading: true, }); setTimeout(() => { state.loading = false; state.columns = ['选项']; }, 1000); return { state }; },};在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
<van-field v-model="state.value" readonly clickable label="城市" placeholder="选择城市" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" round position="bottom"> <van-picker :columns="columns" @cancel="state.showPicker = false" @confirm="onConfirm" /></van-popup>import { reactive } from 'vue';export default { setup() { const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华']; const state = reactive({ value: '', showPicker: false, }); const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, columns, onConfirm, }; },};
<van-picker :title="标题" :columns="columns" :columns-field-names="customFieldName"/>export default { setup() { const columns = [ { cityName: '浙江', cities: [ { cityName: '杭州', cities: [{ cityName: '西湖区' }, { cityName: '余杭区' }], }, { cityName: '温州', cities: [{ cityName: '鹿城区' }, { cityName: '瓯海区' }], }, ], }, { cityName: '福建', cities: [ { cityName: '福州', cities: [{ cityName: '鼓楼区' }, { cityName: '台江区' }], }, { cityName: '厦门', cities: [{ cityName: '思明区' }, { cityName: '海沧区' }], }, ], }, ]; const customFieldName = { text: 'cityName', children: 'cities', }; return { columns, customFieldName, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| columns | 对象数组，配置每一列显示的数据 | Column[] | [] |
| columns-field-names | 自定义 columns 结构中的字段 | object | { text: 'text', values: 'values', children: 'children' } |
| title | 顶部栏标题 | string | - |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| toolbar-position | 顶部栏位置，可选值为 bottom | string | top |
| loading | 是否显示加载状态 | boolean | false |
| show-toolbar | 是否显示顶部栏 | boolean | true |
| allow-html | 是否允许选项内容中渲染 HTML | boolean | false |
| default-index | 单列选择时，默认选中项的索引 | number | string | 0 |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位 ms | number | string | 1000 |
当选择器有多列时，事件回调参数会返回数组。
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，所有列选中值对应的索引 |
| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，所有列选中值对应的索引 |
| change | 选项改变时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，当前列对应的索引 |
| 名称 | 说明 | 参数 |
|---|---|---|
toolbar v3.1.2 | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | option: string | object |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
当传入多列数据时，columns 为一个对象数组，数组中的每一个对象配置每一列，每一列有以下 key:
| 键名 | 说明 | 类型 |
|---|---|---|
| values | 列中对应的备选值 | Array<string | number> |
| defaultIndex | 初始选中项的索引，默认为 0 | number |
| className | 为对应列添加额外的类名 | string | Array | object |
| children | 级联选项 | Column |
通过 ref 可以获取到 Picker 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| getValues | 获取所有列选中的值 | - | values |
| setValues | 设置所有列选中的值 | values | - |
| getIndexes | 获取所有列选中值对应的索引 | - | indexes |
| setIndexes | 设置所有列选中值对应的索引 | indexes | - |
| getColumnValue | 获取对应列选中的值 | columnIndex | value |
| setColumnValue | 设置对应列选中的值 | columnIndex, value | - |
| getColumnIndex | 获取对应列选中项的索引 | columnIndex | optionIndex |
| setColumnIndex | 设置对应列选中项的索引 | columnIndex, optionIndex | - |
| getColumnValues | 获取对应列中所有选项 | columnIndex | values |
| setColumnValues | 设置对应列中所有选项 | columnIndex, values | - |
| confirm | 停止惯性滚动并触发 confirm 事件 | - | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-picker-background-color | var(--van-white) | - |
| --van-picker-toolbar-height | 44px | - |
| --van-picker-title-font-size | var(--van-font-size-lg) | - |
| --van-picker-title-line-height | var(--van-line-height-md) | - |
| --van-picker-action-padding | 0 var(--van-padding-md) | - |
| --van-picker-action-font-size | var(--van-font-size-md) | - |
| --van-picker-confirm-action-color | var(--van-text-link-color) | - |
| --van-picker-cancel-action-color | var(--van-gray-6) | - |
| --van-picker-option-padding | 0 var(--van-padding-base) | - |
| --van-picker-option-font-size | var(--van-font-size-lg) | - |
| --van-picker-option-text-color | var(--van-black) | - |
| --van-picker-option-disabled-opacity | 0.3 | - |
| --van-picker-loading-icon-color | var(--van-primary-color) | - |
| --van-picker-loading-mask-color | rgba(255, 255, 255, 0.9) | - |
参见桌面端适配。
在一组备选项中进行单选。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { RadioGroup, Radio } from 'vant';const app = createApp();app.use(Radio);app.use(RadioGroup);通过 v-model 绑定值当前选中项的 name。
<van-radio-group v-model="checked"> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio></van-radio-group>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked }; },};将 direction 属性设置为 horizontal 后，单选框组会变成水平排列。
<van-radio-group v-model="checked" 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="checked" disabled> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio></van-radio-group>将 shape 属性设置为 square，单选框的形状会变成方形。
<van-radio-group v-model="checked"> <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="checked"> <van-radio name="1" checked-color="#ee0a24">单选框 1</van-radio> <van-radio name="2" checked-color="#ee0a24">单选框 2</van-radio></van-radio-group>通过 icon-size 属性可以自定义图标的大小。
<van-radio-group v-model="checked"> <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="checked"> <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>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked, activeIcon: 'https://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png', }; },};设置 label-disabled 属性后，点击图标以外的内容不会触发单选框切换。
<van-radio-group v-model="checked"> <van-radio name="1" label-disabled>单选框 1</van-radio> <van-radio name="2" label-disabled>单选框 2</van-radio></van-radio-group>此时你需要再引入 Cell 和 CellGroup 组件。
<van-radio-group v-model="checked"> <van-cell-group> <van-cell title="单选框 1" clickable @click="checked = '1'"> <template #right-icon> <van-radio name="1" /> </template> </van-cell> <van-cell title="单选框 2" clickable @click="checked = '2'"> <template #right-icon> <van-radio name="2" /> </template> </van-cell> </van-cell-group></van-radio-group>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符 | any | - |
| shape | 形状，可选值为 square | string | round |
| disabled | 是否为禁用状态 | boolean | false |
| label-disabled | 是否禁用文本内容点击 | boolean | false |
| label-position | 文本位置，可选值为 left | string | right |
| icon-size | 图标大小，默认单位为px | number | string | 20px |
| checked-color | 选中状态颜色 | string | #1989fa |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中项的标识符 | any | - |
| disabled | 是否禁用所有单选框 | boolean | false |
| direction | 排列方向，可选值为horizontal | string | vertical |
| icon-size | 所有单选框的图标大小，默认单位为px | number | string | 20px |
| checked-color | 所有单选框的选中状态颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击单选框时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | name: string |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义文本 | - |
| icon | 自定义图标 | { checked: boolean, disabled: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-radio-size | 20px | - |
| --van-radio-border-color | var(--van-gray-5) | - |
| --van-radio-transition-duration | var(--van-animation-duration-fast) | - |
| --van-radio-label-margin | var(--van-padding-xs) | - |
| --van-radio-label-color | var(--van-text-color) | - |
| --van-radio-checked-icon-color | var(--van-primary-color) | - |
| --van-radio-disabled-icon-color | var(--van-gray-5) | - |
| --van-radio-disabled-label-color | var(--van-gray-5) | - |
| --van-radio-disabled-background-color | var(--van-border-color) | - |
用于对事物进行评级操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Rate } from 'vant';const app = createApp();app.use(Rate);通过 v-model 来绑定当前评分值。
<van-rate v-model="value" />import { ref } from 'vue';export default { setup() { const value = ref(3); return { value }; },};通过 icon 属性设置选中时的图标，void-icon 属性设置未选中时的图标。
<van-rate v-model="value" icon="like" void-icon="like-o" />通过 size 属性设置图标大小，color 属性设置选中时的颜色，void-color 设置未选中时的颜色。
<van-rate v-model="value" :size="25" color="#ffd21e" void-icon="star" void-color="#eee"/>设置 allow-half 属性后可以选中半星。
<van-rate v-model="value" allow-half />import { ref } from 'vue';export default { setup() { const value = ref(2.5); return { value }; },};通过 count 属性设置评分总数。
<van-rate v-model="value" :count="6" />通过 disabled 属性来禁用评分。
<van-rate v-model="value" disabled />通过 readonly 属性将评分设置为只读状态。
<van-rate v-model="value" readonly />设置 readonly 和 allow-half 属性后，Rate 组件可以展示任意小数结果。
<van-rate v-model="value" readonly allow-half />import { ref } from 'vue';export default { setup() { const value = ref(3.3); return { value }; },};评分变化时，会触发 change 事件。
<van-rate v-model="value" @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(3); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前分值 | number | - |
| count | 图标总数 | number | string | 5 |
| size | 图标大小，默认单位为px | number | string | 20px |
| gutter | 图标间距，默认单位为px | number | string | 4px |
| color | 选中时的颜色 | string | #ee0a24 |
| void-color | 未选中时的颜色 | string | #c8c9cc |
| disabled-color | 禁用时的颜色 | string | #c8c9cc |
| icon | 选中时的图标名称或图片链接 | string | star |
| void-icon | 未选中时的图标名称或图片链接 | string | star-o |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| allow-half | 是否允许半选 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法修改评分 | boolean | false |
| disabled | 是否禁用评分 | boolean | false |
| touchable | 是否可以通过滑动手势选择评分 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当前分值变化时触发的事件 | 当前分值 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-rate-icon-size | 20px | - |
| --van-rate-icon-gutter | var(--van-padding-base) | - |
| --van-rate-icon-void-color | var(--van-gray-5) | - |
| --van-rate-icon-full-color | var(--van-danger-color) | - |
| --van-rate-icon-disabled-color | var(--van-gray-5) | - |
用于搜索场景的输入框组件。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Search } from 'vant';const app = createApp();app.use(Search);v-model 用于控制搜索框中的文字，background 可以自定义搜索框外部背景色。
<van-search v-model="value" placeholder="请输入搜索关键词" />import { ref } from 'vue';export default { setup() { const value = ref(''); return { value }; },};Search 组件提供了 search 和 cancel 事件，search 事件在点击键盘上的搜索/回车按钮后触发，cancel 事件在点击搜索框右侧取消按钮时触发。
<form action="/"> <van-search v-model="value" show-action placeholder="请输入搜索关键词" @search="onSearch" @cancel="onCancel" /></form>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(''); const onSearch = (val) => Toast(val); const onCancel = () => Toast('取消'); return { value, onSearch, onCancel, }; },};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 label="地址" placeholder="请输入搜索关键词" @search="onSearch"> <template #action> <div @click="onSearch">搜索</div> </template></van-search>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 搜索框左侧文本 | string | - |
| shape | 搜索框形状，可选值为 round | string | square |
| background | 搜索框外部背景色 | string | #f2f2f2 |
| maxlength | 输入的最大字符数 | number | string | - |
| placeholder | 占位提示文字 | string | - |
| clearable | 是否启用清除图标，点击清除图标后会清空输入框 | boolean | true |
clear-icon v3.0.12 | 清除图标名称或图片链接 | string | clear |
| clear-trigger | 显示清除图标的时机，always 表示输入框不为空时展示， focus 表示输入框聚焦且不为空时展示 | string | focus |
| autofocus | 是否自动聚焦，iOS 系统不支持该属性 | boolean | false |
| show-action | 是否在搜索框右侧显示取消按钮 | boolean | false |
| action-text | 取消按钮文字 | boolean | 取消 |
| disabled | 是否禁用输入框 | boolean | false |
| readonly | 是否将输入框设为只读状态，只读状态下无法输入内容 | boolean | false |
| error | 是否将输入内容标红 | boolean | false |
| error-message | 底部错误提示文案，为空时不展示 | string | - |
formatter v3.0.12 | 输入内容格式化函数 | (val: string) => string | - |
format-trigger v3.0.12 | 格式化函数触发的时机，可选值为 onBlur | string | onChange |
| input-align | 输入框内容对齐方式，可选值为 center right | string | left |
| left-icon | 输入框左侧图标名称或图片链接 | string | search |
| right-icon | 输入框右侧图标名称或图片链接 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| search | 确定搜索时触发 | value: string (当前输入的值) |
| update:model-value | 输入框内容变化时触发 | value: string (当前输入的值) |
| focus | 输入框获得焦点时触发 | event: Event |
| blur | 输入框失去焦点时触发 | event: Event |
| click-input | 点击输入区域时触发 | event: MouseEvent |
| clear | 点击清除按钮后触发 | event: MouseEvent |
| cancel | 点击取消按钮时触发 | - |
通过 ref 可以获取到 Search 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 获取输入框焦点 | - | - |
| blur | 取消输入框焦点 | - | - |
| 名称 | 说明 |
|---|---|
| left | 自定义左侧内容（搜索框外） |
| action | 自定义右侧内容（搜索框外），设置show-action属性后展示 |
| label | 自定义左侧文本（搜索框内） |
| left-icon | 自定义左侧图标（搜索框内） |
| right-icon | 自定义右侧图标（搜索框内） |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-search-padding | 10px var(--van-padding-sm) | - |
| --van-search-background-color | var(--van-white) | - |
| --van-search-content-background-color | var(--van-gray-1) | - |
| --van-search-input-height | 34px | - |
| --van-search-label-padding | 0 5px | - |
| --van-search-label-color | var(--van-text-color) | - |
| --van-search-label-font-size | var(--van-font-size-md) | - |
| --van-search-left-icon-color | var(--van-gray-6) | - |
| --van-search-action-padding | 0 var(--van-padding-xs) | - |
| --van-search-action-text-color | var(--van-text-color) | - |
| --van-search-action-font-size | var(--van-font-size-md) | - |
清除按钮监听是的移动端 Touch 事件，参见桌面端适配。
滑动输入条，用于在给定的范围内选择一个值。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Slider } from 'vant';const app = createApp();app.use(Slider);
<van-slider v-model="value" @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(50); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};添加 range 属性就可以开启双滑块模式，确保 value 的值是一个数组。
<van-slider v-model="value" range @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { // 双滑块模式时，值必须是数组 const value = ref([10, 50]); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};
<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"> <template #button> <div class="custom-button">{{ value }}</div> </template></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>设置 vertical 属性后，滑块会垂直展示，且高度为 100% 父元素高度。
<div :style="{ height: '150px' }"> <van-slider v-model="value" vertical @change="onChange" /> <van-slider v-model="value2" range vertical style="margin-left: 100px;" @change="onChange" /></div>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(50); const value2 = ref([10, 50]); const onChange = (value) => Toast('当前值：' + value); return { value, value2, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前进度百分比，在双滑块模式下为数组格式 | number | [number, number] | 0 |
| max | 最大值 | number | string | 100 |
| min | 最小值 | number | string | 0 |
| step | 步长 | number | string | 1 |
| bar-height | 进度条高度，默认单位为 px | number | string | 2px |
| button-size | 滑块按钮大小，默认单位为 px | number | string | 24px |
| active-color | 进度条激活态颜色 | string | #1989fa |
| inactive-color | 进度条非激活态颜色 | string | #e5e5e5 |
| range | 是否开启双滑块模式 | boolean | false |
| disabled | 是否禁用滑块 | boolean | false |
readonly v3.0.5 | 是否为只读状态，只读状态下无法修改滑块的值 | boolean | false |
| vertical | 是否垂直展示 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 进度变化时实时触发 | value: number |
| change | 进度变化且结束拖动后触发 | value: number |
| drag-start | 开始拖动时触发 | event: TouchEvent |
| drag-end | 结束拖动时触发 | event: TouchEvent |
| 名称 | 说明 | 参数 |
|---|---|---|
| button | 自定义滑块按钮 | { value: number } |
left-button v3.1.3 | 自定义左侧滑块按钮（双滑块模式下） | { value: number } |
right-button v3.1.3 | 自定义右侧滑块按钮 （双滑块模式下） | { value: number } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-slider-active-background-color | var(--van-primary-color) | - |
| --van-slider-inactive-background-color | var(--van-gray-3) | - |
| --van-slider-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-slider-bar-height | 2px | - |
| --van-slider-button-width | 24px | - |
| --van-slider-button-height | 24px | - |
| --van-slider-button-border-radius | 50% | - |
| --van-slider-button-background-color | var(--van-white) | - |
| --van-slider-button-box-shadow | 0 1px 2px rgba(0, 0, 0, 0.5) | - |
步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Stepper } from 'vant';const app = createApp();app.use(Stepper);通过 v-model 绑定输入值，可以通过 change 事件监听到输入值的变化。
<van-stepper v-model="value" />import { ref } from 'vue';export default { setup() { const value = ref(1); return { value }; },};通过 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 />通过设置 disable-input 属性来禁用输入框，此时按钮仍然可以点击。
<van-stepper v-model="value" disable-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" />通过 before-change 属性可以在输入值变化前进行校验和拦截。
<van-stepper v-model="value" :before-change="beforeChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(1); const beforeChange = (value) => { Toast.loading({ forbidClick: true }); return new Promise((resolve) => { setTimeout(() => { Toast.clear(); // 在 resolve 函数中返回 true 或 false resolve(true); }, 500); }); }; return { value, beforeChange, }; },};将 theme 设置为 round 来展示圆角风格的步进器。
<van-stepper v-model="value" theme="round" button-size="22" disable-input />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入的值 | number | string | - |
| min | 最小值 | number | string | 1 |
| max | 最大值 | number | string | - |
| default-value | 初始值，当 v-model 为空时生效 | number | string | 1 |
| step | 步长，每次点击时改变的值 | number | string | 1 |
| name | 标识符，可以在 change 事件回调参数中获取 | number | string | - |
| input-width | 输入框宽度，默认单位为 px | number | string | 32px |
| button-size | 按钮大小以及输入框高度，默认单位为 px | number | string | 28px |
| decimal-length | 固定显示的小数位数 | number | string | - |
| theme | 样式风格，可选值为 round | string | - |
| placeholder | 输入框占位提示文字 | string | - |
| integer | 是否只允许输入整数 | boolean | false |
| disabled | 是否禁用步进器 | boolean | false |
| disable-plus | 是否禁用增加按钮 | boolean | false |
| disable-minus | 是否禁用减少按钮 | boolean | false |
| disable-input | 是否禁用输入框 | boolean | false |
| before-change | 输入值变化前的回调函数，返回 false 可阻止输入，支持返回 Promise | (value: number | string) => boolean | Promise<boolean> | false |
| show-plus | 是否显示增加按钮 | boolean | true |
| show-minus | 是否显示减少按钮 | boolean | true |
| show-input | 是否显示输入框 | boolean | true |
| long-press | 是否开启长按手势 | boolean | true |
| allow-empty | 是否允许输入的值为空 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | value: string, detail: { name: string } |
| overlimit | 点击不可用的按钮时触发 | - |
| plus | 点击增加按钮时触发 | - |
| minus | 点击减少按钮时触发 | - |
| focus | 输入框聚焦时触发 | event: Event |
| blur | 输入框失焦时触发 | event: Event |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-stepper-active-color | #e8e8e8 | - |
| --van-stepper-background-color | var(--van-active-color) | - |
| --van-stepper-button-icon-color | var(--van-text-color) | - |
| --van-stepper-button-disabled-color | var(--van-background-color) | - |
| --van-stepper-button-disabled-icon-color | var(--van-gray-5) | - |
| --van-stepper-button-round-theme-color | var(--van-danger-color) | - |
| --van-stepper-input-width | 32px | - |
| --van-stepper-input-height | 28px | - |
| --van-stepper-input-font-size | var(--van-font-size-md) | - |
| --van-stepper-input-line-height | normal | - |
| --van-stepper-input-text-color | var(--van-text-color) | - |
| --van-stepper-input-disabled-text-color | var(--van-gray-5) | - |
| --van-stepper-input-disabled-background-color | var(--van-active-color) | - |
| --van-stepper-border-radius | var(--van-border-radius-md) | - |
这是因为用户输入过程中可能出现小数点或空值，比如 1.，这种情况下组件会抛出字符串类型。
如果希望 value 保持 number 类型，可以在 v-model 上添加 number 修饰符：
<van-stepper v-model.number="value" />用于在打开和关闭状态之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Switch } from 'vant';const app = createApp();app.use(Switch);通过 v-model 绑定开关的选中状态，true 表示开，false 表示关。
<van-switch v-model="checked" />import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked }; },};通过 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="#ee0a24" inactive-color="#dcdee0" />需要异步控制开关时，可以使用 modelValue 属性和 update:model-value 事件代替 v-model，并在事件回调函数中手动处理开关状态。
<van-switch :model-value="checked" @update:model-value="onUpdateValue" />import { ref } from 'vue';import { Dialog } from 'vant';export default { setup() { const checked = ref(true); const onUpdateValue = (newValue) => { Dialog.confirm({ title: '提醒', message: '是否切换开关？', }).then(() => { checked.value = newValue; }); }; return { checked, onUpdateValue, }; },};<van-cell center title="标题"> <template #right-icon> <van-switch v-model="checked" size="24" /> </template></van-cell>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 开关选中状态 | any | false |
| loading | 是否为加载状态 | boolean | false |
| disabled | 是否为禁用状态 | boolean | false |
| size | 开关尺寸，默认单位为px | number | string | 30px |
| active-color | 打开时的背景色 | string | #1989fa |
| inactive-color | 关闭时的背景色 | string | white |
| active-value | 打开时对应的值 | any | true |
| inactive-value | 关闭时对应的值 | any | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 开关状态切换时触发 | value: any |
| click | 点击时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-switch-size | 30px | - |
| --van-switch-width | 2em | - |
| --van-switch-height | 1em | - |
| --van-switch-node-size | 1em | - |
| --van-switch-node-background-color | var(--van-white) | - |
| --van-switch-node-box-shadow | 0 3px 1px 0 rgba(0, 0, 0, 0.05) | - |
| --van-switch-background-color | var(--van-white) | - |
| --van-switch-on-background-color | var(--van-primary-color) | - |
| --van-switch-transition-duration | var(--van-animation-duration-base) | - |
| --van-switch-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-switch-border | var(--van-border-width-base) solid rgba(0, 0, 0, 0.1) | - |
用于将本地的图片或文件上传至服务器，并在上传过程中展示预览图和上传进度。目前 Uploader 组件不包含将文件上传至服务器的接口逻辑，该步骤需要自行实现。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Uploader } from 'vant';const app = createApp();app.use(Uploader);文件上传完毕后会触发 after-read 回调函数，获取到对应的 file 对象。
<van-uploader :after-read="afterRead" />export default { setup() { const afterRead = (file) => { // 此时可以自行将文件上传至服务器 console.log(file); }; return { afterRead, }; },};通过 v-model 可以绑定已经上传的文件列表，并展示文件列表的预览图。
<van-uploader v-model="fileList" multiple />import { ref } from 'vue';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg' }, // Uploader 根据文件后缀来判断是否为图片文件 // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明 { url: 'https://cloud-image', isImage: true }, ]); return { fileList, }; },};通过 status 属性可以标识上传状态，uploading 表示上传中，failed 表示上传失败，done 表示上传完成。
<van-uploader v-model="fileList" :after-read="afterRead" />import { ref } from 'vue';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg', status: 'uploading', message: '上传中...', }, { url: 'https://img.yzcdn.cn/vant/tree.jpg', status: 'failed', message: '上传失败', }, ]); const afterRead = (file) => { file.status = 'uploading'; file.message = '上传中...'; setTimeout(() => { file.status = 'failed'; file.message = '上传失败'; }, 1000); }; return { fileList, afterRead, }; },};通过 max-count 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。
<van-uploader v-model="fileList" multiple :max-count="2" />import { ref } from 'vue';export default { setup() { const fileList = ref([]); return { fileList, }; },};通过 max-size 属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过 oversize 事件获取。
<van-uploader multiple :max-size="500 * 1024" @oversize="onOversize" />import { Toast } from 'vant';export default { setup() { const onOversize = (file) => { console.log(file); Toast('文件大小不能超过 500kb'); }; return { onOversize, }; },};如果需要针对不同类型的文件来作出不同的大小限制，可以在 max-size 属性中传入一个函数，在函数中通过 file.type 区分文件类型，返回 true 表示超出限制，false 表示未超出限制。
<van-uploader multiple :max-size="isOverSize" />import { Toast } from 'vant';export default { setup() { const isOverSize = (file) => { const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024; return file.size >= maxSize; }; return { isOverSize, }; },};通过默认插槽可以自定义上传区域的样式。
<van-uploader> <van-button icon="plus" type="primary">上传文件</van-button></van-uploader>通过 preview-cover 插槽可以自定义覆盖在预览区域上方的内容。
<van-uploader v-model="fileList"> <template #preview-cover="{ file }"> <div class="preview-cover van-ellipsis">{{ file.name }}</div> </template></van-uploader><style> .preview-cover { position: absolute; bottom: 0; box-sizing: border-box; width: 100%; padding: 4px; color: #fff; font-size: 12px; text-align: center; background: rgba(0, 0, 0, 0.3); }</style>通过传入 beforeRead 函数可以在上传前进行校验和处理，返回 true 表示校验通过，返回 false 表示校验失败。支持返回 Promise 对 file 对象进行自定义处理，例如压缩图片。
<van-uploader :before-read="beforeRead" />import { Toast } from 'vant';export default { setup() { // 返回布尔值 const beforeRead = (file) => { if (file.type !== 'image/jpeg') { Toast('请上传 jpg 格式图片'); return false; } return true; }; // 返回 Promise const asyncBeforeRead = (file) => { return new Promise((resolve, reject) => { if (file.type !== 'image/jpeg') { Toast('请上传 jpg 格式图片'); reject(); } else { const img = new File(['foo'], 'bar.jpg', { type: 'image/jpeg', }); resolve(img); } }); }; return { beforeRead, asyncBeforeRead, }; },};通过 disabled 属性禁用文件上传。
<van-uploader disabled />在 v-model 数组中设置单个预览图片属性，支持 imageFit deletable previewSize beforeDelete。
<van-uploader v-model="fileList" :deletable="false" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg' }, { url: 'https://img.yzcdn.cn/vant/sand.jpg', deletable: true, beforeDelete: () => { Toast('自定义单个预览图片的事件和样式'); }, }, { url: 'https://img.yzcdn.cn/vant/tree.jpg', deletable: true, imageFit: 'contain', previewSize: 120, }, ]); return { fileList }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 已上传的文件列表 | FileListItem[] | - |
| accept | 允许上传的文件类型，详细说明 | string | image/* |
| name | 标识符，可以在回调函数的第二项参数中获取 | number | string | - |
| preview-size | 预览图和上传区域的尺寸，默认单位为 px | number | string | 80px |
| preview-image | 是否在上传完成后展示预览图 | boolean | true |
| preview-full-image | 是否在点击预览图后展示全屏图片预览 | boolean | true |
| preview-options | 全屏图片预览的配置项，可选值见 ImagePreview | object | - |
| multiple | 是否开启图片多选，部分安卓机型不支持 | boolean | false |
| disabled | 是否禁用文件上传 | boolean | false |
readonly v3.1.5 | 是否将上传区域设置为只读状态 | boolean | false |
| deletable | 是否展示删除按钮 | boolean | true |
| show-upload | 是否展示上传区域 | boolean | true |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| capture | 图片选取模式，可选值为 camera (直接调起摄像头) | string | - |
| after-read | 文件读取完成后的回调函数 | Function | - |
| before-read | 文件读取前的回调函数，返回 false 可终止文件读取， 支持返回 Promise | Function | - |
| before-delete | 文件删除前的回调函数，返回 false 可终止文件读取， 支持返回 Promise | Function | - |
max-size v3.0.17 | 文件大小限制，单位为 byte | number | string | (file: File) => boolean | - |
| max-count | 文件上传数量限制 | number | string | - |
| result-type | 文件读取结果类型，可选值为 file text | string | dataUrl |
| upload-text | 上传区域文字提示 | string | - |
| image-fit | 预览图裁剪模式，可选值见 Image 组件 | string | cover |
| upload-icon | 上传区域图标名称或图片链接 | string | photograph |
注意：accept、capture 和 multiple 为浏览器 input 标签的原生属性，移动端各种机型对这些属性的支持程度有所差异，因此在不同机型和 WebView 下可能出现一些兼容性问题。
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| oversize | 文件大小超过限制时触发 | 同 after-read |
click-upload v3.1.5 | 点击上传区域时触发 | event: MouseEvent |
| click-preview | 点击预览图时触发 | 同 after-read |
| close-preview | 关闭全屏图片预览时触发 | - |
| delete | 删除文件预览时触发 | 同 after-read |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义上传区域 | - |
| preview-cover | 自定义覆盖在预览区域上方的内容 | item: FileListItem |
before-read、after-read、before-delete 执行时会传递以下回调参数：
| 参数名 | 说明 | 类型 |
|---|---|---|
| file | file 对象 | object |
| detail | 额外信息，包含 name 和 index 字段 | object |
result-type 字段表示文件读取结果的类型，上传大文件时，建议使用 file 类型，避免卡顿。
| 值 | 描述 |
|---|---|
| file | 结果仅包含 File 对象 |
| text | 结果包含 File 对象，以及文件的文本内容 |
| dataUrl | 结果包含 File 对象，以及文件对应的 base64 编码 |
通过 ref 可以获取到 Uploader 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| closeImagePreview | 关闭全屏的图片预览 | - | - |
| chooseFile | 主动调起文件选择，由于浏览器安全限制，只有在用户触发操作的上下文中调用才有效 | - | - |
通过 UploaderInstance 获取 Uploader 实例的类型定义。
import { ref } from 'vue';import type { UploaderInstance } from 'vant';const uploaderRef = ref<UploaderInstance>();uploaderRef.value?.chooseFile();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-uploader-size | 80px | - |
| --van-uploader-icon-size | 24px | - |
| --van-uploader-icon-color | var(--van-gray-4) | - |
| --van-uploader-text-color | var(--van-gray-6) | - |
| --van-uploader-text-font-size | var(--van-font-size-sm) | - |
| --van-uploader-upload-background-color | var(--van-gray-1) | - |
| --van-uploader-upload-active-color | var(--van-active-color) | - |
| --van-uploader-delete-color | var(--van-white) | - |
| --van-uploader-delete-icon-size | 14px | - |
| --van-uploader-delete-background-color | rgba(0, 0, 0, 0.7) | - |
| --van-uploader-file-background-color | var(--van-background-color) | - |
| --van-uploader-file-icon-size | 20px | - |
| --van-uploader-file-icon-color | var(--van-gray-7) | - |
| --van-uploader-file-name-padding | 0 var(--van-padding-base) | - |
| --van-uploader-file-name-margin-top | var(--van-padding-xs) | - |
| --van-uploader-file-name-font-size | var(--van-font-size-sm) | - |
| --van-uploader-file-name-text-color | var(--van-gray-7) | - |
| --van-uploader-mask-text-color | var(--van-white) | - |
| --van-uploader-mask-background-color | fade(var(--van-gray-8), 88%) | - |
| --van-uploader-mask-icon-size | 22px | - |
| --van-uploader-mask-message-font-size | var(--van-font-size-sm) | - |
| --van-uploader-mask-message-line-height | var(--van-line-height-xs) | - |
| --van-uploader-loading-icon-size | 22px | - |
| --van-uploader-loading-icon-color | var(--van-white) | - |
| --van-uploader-disabled-opacity | var(--van-disabled-opacity) | - |
部分手机在拍照上传时会出现图片被旋转 90 度的问题，这个问题可以通过 compressorjs 或其他开源库进行处理。
compressorjs 是一个开源的图片处理库，提供了图片压缩、图片旋转等能力。
使用 compressorjs 进行处理的示例代码如下:
<van-uploader :before-read="beforeRead" />import Compressor from 'compressorjs';export default { setup() { const beforeRead = (file) => { return new Promise((resolve) => { // compressorjs 默认开启 checkOrientation 选项 // 会将图片修正为正确方向 new Compressor(file, { success: resolve, error(err) { console.log(err.message); }, }); }); }; return { beforeRead, }; },};目前 Chrome、Safari 等浏览器不支持展示 HEIC/HEIF 格式的图片，因此上传后无法在 Uploader 组件中进行预览。
[HEIF] 格式的兼容性请参考 caniuse。
底部弹起的模态面板，包含与当前情境相关的多个选项。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ActionSheet } from 'vant';const app = createApp();app.use(ActionSheet);动作面板通过 actions 属性来定义选项，actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象格式见文档下方表格。
<van-cell is-link title="基础用法" @click="show = true" /><van-action-sheet v-model:show="show" :actions="actions" @select="onSelect" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三' }, ]; const onSelect = (item) => { // 默认情况下点击选项时不会自动收起 // 可以通过 close-on-click-action 属性开启自动收起 show.value = false; Toast(item.name); }; return { show, actions, onSelect, }; },};设置 cancel-text 属性后，会在底部展示取消按钮，点击后关闭当前面板并触发 cancel 事件。
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" close-on-click-action @cancel="onCancel"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三' }, ]; const onCancel = () => Toast('取消'); return { show, actions, onCancel, }; },};通过 description 可以在菜单顶部显示描述信息，通过选项的 subname 属性可以在选项文字的右侧展示描述信息。
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" description="这是一段描述信息" close-on-click-action/>import { ref } from 'vue';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三', subname: '描述信息' }, ]; return { show, actions, }; },};可以通过 loading 和 disabled 将选项设置为加载状态或禁用状态，或者通过color设置选项的颜色
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" close-on-click-action/>import { ref } from 'vue';export default { setup() { const show = ref(false); const actions = [ { name: '着色选项', color: '#ee0a24' }, { name: '禁用选项', disabled: true }, { name: '加载选项', loading: true }, ]; return { show, actions, }; },};通过插槽可以自定义面板的展示内容，同时可以使用title属性展示标题栏
<van-action-sheet v-model:show="show" title="标题"> <div class="content">内容</div></van-action-sheet><style> .content { padding: 16px 16px 160px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示动作面板 | boolean | false |
| actions | 面板选项列表 | Action[] | [] |
| title | 顶部标题 | string | - |
| cancel-text | 取消按钮文字 | string | - |
| description | 选项上方的描述信息 | string | - |
| closeable | 是否显示关闭图标 | boolean | true |
| close-icon | 关闭图标名称或图片链接 | string | cross |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| round | 是否显示圆角 | boolean | true |
| overlay | 是否显示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | false |
| close-on-click-action | 是否在点击选项后关闭 | boolean | false |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 标题 | string |
| subname | 二级标题 | string |
| color | 选项文字颜色 | string |
| className | 为对应列添加额外的 class | string | Array | object |
| loading | 是否为加载状态 | boolean |
| disabled | 是否为禁用状态 | boolean |
| callback | 点击时触发的回调函数 | action: Action |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击选项时触发，禁用或加载状态下不会触发 | action: Action, index: number |
| cancel | 点击取消按钮时触发 | - |
| open | 打开面板时触发 | - |
| close | 关闭面板时触发 | - |
| opened | 打开面板且动画结束后触发 | - |
| closed | 关闭面板且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义面板的展示内容 |
| description | 自定义描述文案 |
cancel v3.0.10 | 自定义取消按钮内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-action-sheet-max-height | 80% | - |
| --van-action-sheet-header-height | 48px | - |
| --van-action-sheet-header-font-size | var(--van-font-size-lg) | - |
| --van-action-sheet-description-color | var(--van-gray-6) | - |
| --van-action-sheet-description-font-size | var(--van-font-size-md) | - |
| --van-action-sheet-description-line-height | var(--van-line-height-md) | - |
| --van-action-sheet-item-background | var(--van-white) | - |
| --van-action-sheet-item-font-size | var(--van-font-size-lg) | - |
| --van-action-sheet-item-line-height | var(--van-line-height-lg) | - |
| --van-action-sheet-item-text-color | var(--van-text-color) | - |
| --van-action-sheet-item-disabled-text-color | var(--van-gray-5) | - |
| --van-action-sheet-subname-color | var(--van-gray-6) | - |
| --van-action-sheet-subname-font-size | var(--van-font-size-sm) | - |
| --van-action-sheet-subname-line-height | var(--van-line-height-sm) | - |
| --van-action-sheet-close-icon-size | 22px | - |
| --van-action-sheet-close-icon-color | var(--van-gray-5) | - |
| --van-action-sheet-close-icon-active-color | var(--van-gray-6) | - |
| --van-action-sheet-close-icon-padding | 0 var(--van-padding-md) | - |
| --van-action-sheet-cancel-text-color | var(--van-gray-7) | - |
| --van-action-sheet-cancel-padding-top | var(--van-padding-xs) | - |
| --van-action-sheet-cancel-padding-color | var(--van-background-color) | - |
| --van-action-sheet-loading-icon-size | 22px | - |
弹出模态框，常用于消息提示、消息确认，或在当前页面内完成特定的交互操作，支持函数调用和组件调用两种方式。
Dialog 是一个函数，调用后会直接在页面中弹出相应的模态框。
import { Dialog } from 'vant';Dialog({ message: '提示' });通过组件调用 Dialog 时，可以通过下面的方式进行注册：
import { createApp } from 'vue';import { Dialog } from 'vant';// 全局注册const app = createApp();app.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 });将 theme 选项设置为 round-button 可以展示圆角按钮风格的弹窗。
Dialog.alert({ title: '标题', message: '弹窗内容', theme: 'round-button',}).then(() => { // on close});Dialog.alert({ message: '弹窗内容', theme: 'round-button',}).then(() => { // on close});通过 beforeClose 属性可以传入一个回调函数，在弹窗关闭前进行特定操作。
const beforeClose = (action) => new Promise((resolve) => { setTimeout(() => { if (action === 'confirm') { resolve(true); } else { // 拦截取消操作 resolve(false); } }, 1000); });Dialog.confirm({ title: '标题', message: '弹窗内容', beforeClose,});通过 app.use 全局注册 Dialog 组件后，会自动在 app 的所有子组件上挂载 $dialog 方法，在所有组件内部都可以直接调用此方法。
export default { mounted() { this.$dialog.alert({ message: '弹窗内容', }); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。
<van-dialog v-model:show="show" title="标题" show-cancel-button> <img src="https://img.yzcdn.cn/vant/apple-3.jpg" rel="external nofollow" /></van-dialog>import { ref } from 'vue';export default { setup() { const show = ref(false); return { show }; },};| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Dialog | 展示弹窗 | options: DialogOptions | Promise<void> |
| Dialog.alert | 展示消息提示弹窗 | options: DialogOptions | Promise<void> |
| Dialog.confirm | 展示消息确认弹窗 | options: DialogOptions | Promise<void> |
| Dialog.setDefaultOptions | 修改默认配置，对所有 Dialog 生效 | options: DialogOptions | void |
| Dialog.resetDefaultOptions | 重置默认配置，对所有 Dialog 生效 | - | void |
| Dialog.close | 关闭弹窗 | - | void |
通过函数调用 Dialog 时，支持传入以下选项：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | - |
| width | 弹窗宽度，默认单位为 px | number | string | 320px |
| message | 文本内容，支持通过
换行 | string | () => JSX.ELement | - |
| messageAlign | 内容对齐方式，可选值为 left right | string | center |
| theme | 样式风格，可选值为 round-button | string | default |
| className | 自定义类名 | string | Array | object | - |
| showConfirmButton | 是否展示确认按钮 | boolean | true |
| showCancelButton | 是否展示取消按钮 | boolean | false |
| confirmButtonText | 确认按钮文案 | string | 确认 |
| confirmButtonColor | 确认按钮颜色 | string | #ee0a24 |
| cancelButtonText | 取消按钮文案 | string | 取消 |
| cancelButtonColor | 取消按钮颜色 | string | black |
| overlay | 是否展示遮罩层 | boolean | true |
| overlayClass | 自定义遮罩层类名 | string | Array | object | - |
| overlayStyle | 自定义遮罩层样式 | object | - |
| closeOnPopstate | 是否在页面回退时自动关闭 | boolean | true |
| closeOnClickOverlay | 是否在点击遮罩层后关闭弹窗 | boolean | false |
| lockScroll | 是否锁定背景滚动 | boolean | true |
| allowHtml | 是否允许 message 内容中渲染 HTML | boolean | false |
| beforeClose | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | body |
通过组件调用 Dialog 时，支持以下 Props：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示弹窗 | boolean | - |
| title | 标题 | string | - |
| width | 弹窗宽度，默认单位为 px | number | string | 320px |
| message | 文本内容，支持通过
换行 | string | () => JSX.ELement | - |
| message-align | 内容水平对齐方式，可选值为 left right | string | center |
| theme | 样式风格，可选值为 round-button | string | default |
| show-confirm-button | 是否展示确认按钮 | boolean | true |
| show-cancel-button | 是否展示取消按钮 | boolean | false |
| confirm-button-text | 确认按钮文案 | string | 确认 |
| confirm-button-color | 确认按钮颜色 | string | #ee0a24 |
| cancel-button-text | 取消按钮文案 | string | 取消 |
| cancel-button-color | 取消按钮颜色 | string | black |
| overlay | 是否展示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭弹窗 | boolean | false |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| allow-html | 是否允许 message 内容中渲染 HTML | boolean | false |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 Dialog 时，支持以下事件：
| 事件 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击确认按钮时触发 | - |
| cancel | 点击取消按钮时触发 | - |
| open | 打开弹窗时触发 | - |
| close | 关闭弹窗时触发 | - |
| opened | 打开弹窗且动画结束后触发 | - |
| closed | 关闭弹窗且动画结束后触发 | - |
通过组件调用 Dialog 时，支持以下插槽：
| 名称 | 说明 |
|---|---|
| default | 自定义内容 |
| title | 自定义标题 |
footer v3.0.10 | 自定义底部按钮区域 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-dialog-width | 320px | - |
| --van-dialog-small-screen-width | 90% | - |
| --van-dialog-font-size | var(--van-font-size-lg) | - |
| --van-dialog-transition | var(--van-animation-duration-base) | - |
| --van-dialog-border-radius | 16px | - |
| --van-dialog-background-color | var(--van-white) | - |
| --van-dialog-header-font-weight | var(--van-font-weight-bold) | - |
| --van-dialog-header-line-height | 24px | - |
| --van-dialog-header-padding-top | 26px | - |
| --van-dialog-header-isolated-padding | var(--van-padding-lg) 0 | - |
| --van-dialog-message-padding | var(--van-padding-lg) | - |
| --van-dialog-message-font-size | var(--van-font-size-md) | - |
| --van-dialog-message-line-height | var(--van-line-height-md) | - |
| --van-dialog-message-max-height | 60vh | - |
| --van-dialog-has-title-message-text-color | var(--van-gray-7) | - |
| --van-dialog-has-title-message-padding-top | var(--van-padding-xs) | - |
| --van-dialog-button-height | 48px | - |
| --van-dialog-round-button-height | 36px | - |
| --van-dialog-confirm-button-text-color | var(--van-danger-color) | - |
将 closeOnPopstate 属性设置为 false 即可。
Dialog.alert({ title: '标题', message: '弹窗内容', closeOnPopstate: false,}).then(() => { // on close});请注意 Dialog 是一个函数，Dialog.Component 才是 Dialog 对应的组件。JSX 调用弹窗的正确姿势如下：
export default { setup() { const show = ref(false); return () => <Dialog.Component v-model={[show, 'show']} />; },};向下弹出的菜单列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { DropdownMenu, DropdownItem } from 'vant';const app = createApp();app.use(DropdownMenu);app.use(DropdownItem);<van-dropdown-menu> <van-dropdown-item v-model="state.value1" :options="option1" /> <van-dropdown-item v-model="state.value2" :options="option2" /></van-dropdown-menu>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: 0, value2: 'a', }); const option1 = [ { text: '全部商品', value: 0 }, { text: '新款商品', value: 1 }, { text: '活动商品', value: 2 }, ]; const option2 = [ { text: '默认排序', value: 'a' }, { text: '好评排序', value: 'b' }, { text: '销量排序', value: 'c' }, ]; return { state, option1, option2, }; },};通过插槽可以自定义 DropdownItem 的内容，此时需要使用实例上的 toggle 方法手动控制菜单的显示。
<van-dropdown-menu> <van-dropdown-item v-model="value" :options="option" /> <van-dropdown-item title="筛选" ref="item"> <van-cell center title="包邮"> <template #right-icon> <van-switch v-model="switch1" size="24" active-color="#ee0a24" /> </template> </van-cell> <van-cell center title="团购"> <template #right-icon> <van-switch v-model="switch2" size="24" active-color="#ee0a24" /> </template> </van-cell> <div style="padding: 5px 16px;"> <van-button type="danger" block round @click="onConfirm"> 确认 </van-button> </div> </van-dropdown-item></van-dropdown-menu>import { ref, reactive } from 'vue';export default { setup() { const item = ref(null); const state = reactive({ value: 0, switch1: false, switch2: false, }); const options = [ { text: '全部商品', value: 0 }, { text: '新款商品', value: 1 }, { text: '活动商品', value: 2 }, ]; const onConfirm = () => { item.value.toggle(); }; return { item, state, options, onConfirm, }; },};通过 active-color 属性可以自定义菜单标题和选项的选中态颜色。
<van-dropdown-menu active-color="#1989fa"> <van-dropdown-item v-model="value1" :options="option1" /> <van-dropdown-item v-model="value2" :options="option2" /></van-dropdown-menu>将 direction 属性值设置为 up，菜单即可向上展开。
<van-dropdown-menu direction="up"> <van-dropdown-item v-model="value1" :options="option1" /> <van-dropdown-item v-model="value2" :options="option2" /></van-dropdown-menu><van-dropdown-menu> <van-dropdown-item v-model="value1" disabled :options="option1" /> <van-dropdown-item v-model="value2" disabled :options="option2" /></van-dropdown-menu>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| active-color | 菜单标题和选项的选中态颜色 | string | #ee0a24 |
| direction | 菜单展开方向，可选值为up | string | down |
| z-index | 菜单栏 z-index 层级 | number | string | 10 |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.2 |
| overlay | 是否显示遮罩层 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭菜单 | boolean | true |
| close-on-click-outside | 是否在点击外部元素后关闭菜单 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中项对应的 value | number | string | - |
| title | 菜单项标题 | string | 当前选中项文字 |
| options | 选项数组 | Option[] | [] |
| disabled | 是否禁用菜单 | boolean | false |
| lazy-render | 是否在首次展开时才渲染菜单内容 | boolean | true |
| title-class | 标题额外类名 | string | Array | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 点击选项导致 value 变化时触发 | value |
| open | 打开菜单栏时触发 | - |
| close | 关闭菜单栏时触发 | - |
| opened | 打开菜单栏且动画结束后触发 | - |
| closed | 关闭菜单栏且动画结束后触发 | - |
| 名称 | 说明 |
|---|---|
| default | 菜单内容 |
| title | 自定义菜单项标题 |
通过 ref 可以获取到 DropdownItem 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换菜单展示状态，传 true 为显示，false 为隐藏，不传参为取反 | show?: boolean | - |
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 文字 | string |
| value | 标识符 | number | string |
| icon | 左侧图标名称或图片链接 | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-dropdown-menu-height | 48px | - |
| --van-dropdown-menu-background-color | var(--van-white) | - |
| --van-dropdown-menu-box-shadow | 0 2px 12px fade(var(--van-gray-7), 12) | - |
| --van-dropdown-menu-title-font-size | 15px | - |
| --van-dropdown-menu-title-text-color | var(--van-text-color) | - |
| --van-dropdown-menu-title-active-text-color | var(--van-danger-color) | - |
| --van-dropdown-menu-title-disabled-text-color | var(--van-gray-6) | - |
| --van-dropdown-menu-title-padding | 0 var(--van-padding-xs) | - |
| --van-dropdown-menu-title-line-height | var(--van-line-height-lg) | - |
| --van-dropdown-menu-option-active-color | var(--van-danger-color) | - |
| --van-dropdown-menu-content-max-height | 80% | - |
| --van-dropdown-item-z-index | 10 | - |
把 DropdownMenu 嵌套在 Tabs 等组件内部使用时，可能会遇到下拉菜单位置错误的问题。这是因为在 Chrome 浏览器中，transform 元素内部的 fixed 布局会降级成 absolute 布局，导致下拉菜单的布局异常。
将 DropdownItem 的 teleport 属性设置为 body 即可避免此问题：
<van-dropdown-menu> <van-dropdown-item teleport="body" /> <van-dropdown-item teleport="body" /></van-dropdown-menu>加载图标，用于表示加载中的过渡状态。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Loading } from 'vant';const app = createApp();app.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>通过 color 或者 text-color 属性设置加载文案的颜色。
<!-- 可修改文案和加载图标的颜色 --><van-loading color="#0094ff" /><!-- 只修改文案颜色 --><van-loading text-color="#0094ff" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| color | 颜色 | string | #c9c9c9 |
| type | 类型，可选值为 spinner | string | circular |
| size | 加载图标大小，默认单位为 px | number | string | 30px |
| text-size | 文字大小，默认单位为 px | number | string | 14px |
| text-color | 文字颜色 | string | #c9c9c9 |
| vertical | 是否垂直排列图标和文字内容 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 加载文案 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-loading-text-color | var(--van-gray-6) | - |
| --van-loading-text-font-size | var(--van-font-size-md) | - |
| --van-loading-spinner-color | var(--van-gray-5) | - |
| --van-loading-spinner-size | 30px | - |
| --van-loading-spinner-animation-duration | 0.8s | - |
在页面顶部展示消息提示，支持函数调用和组件调用两种方式。
Notify 是一个函数，调用后会直接在页面中弹出相应的消息提示。
import { Notify } from 'vant';Notify('通知内容');通过组件调用 Notify 时，可以通过下面的方式进行注册：
import { createApp } from 'vue';import { Notify } from 'vant';// 全局注册const app = createApp();app.use(Notify);// 局部注册export default { components: { [Notify.Component.name]: Notify.Component, },};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,});通过 app.use 全局注册 Notify 组件后，会自动在 app 的所有子组件上挂载 $notify 方法，便于在组件内调用。
export default { mounted() { this.$notify('提示文案'); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
如果需要在 Notify 内嵌入组件或其他自定义内容，可以使用组件调用的方式。
<van-button type="primary" text="组件调用" @click="showNotify" /><van-notify v-model:show="show" type="success"> <van-icon name="bell" style="margin-right: 4px;" /> <span>通知内容</span></van-notify>import { ref } from 'vue';export default { setup() { const show = ref(false); const showNotify = () => { show.value = true; setTimeout(() => { show.value = false; }, 2000); }; return { show, showNotify, }; },};| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Notify | 展示提示 | options | message | notify 实例 |
| Notify.clear | 关闭提示 | - | void |
| Notify.setDefaultOptions | 修改默认配置，对所有 Notify 生效 | options | void |
| Notify.resetDefaultOptions | 重置默认配置，对所有 Notify 生效 | - | void |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success warning | string | danger |
| message | 展示文案，支持通过
换行 | string | - |
| duration | 展示时长(ms)，值为 0 时，notify 不会消失 | number | string | 3000 |
| color | 字体颜色 | string | white |
| background | 背景颜色 | string | - |
| className | 自定义类名 | string | Array | object | - |
lockScroll v3.0.7 | 是否锁定背景滚动 | boolean | false |
| onClick | 点击时的回调函数 | (event: MouseEvent): void | - |
| onOpened | 完全展示后的回调函数 | () => void | - |
| onClose | 关闭时的回调函数 | () => void | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-notify-text-color | var(--van-white) | - |
| --van-notify-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-notify-font-size | var(--van-font-size-md) | - |
| --van-notify-line-height | var(--van-line-height-md) | - |
| --van-notify-primary-background-color | var(--van-primary-color) | - |
| --van-notify-success-background-color | var(--van-success-color) | - |
| --van-notify-danger-background-color | var(--van-danger-color) | - |
| --van-notify-warning-background-color | var(--van-warning-color) | - |
创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Overlay } from 'vant';const app = createApp();app.use(Overlay);<van-button type="primary" text="显示遮罩层" @click="show = true" /><van-overlay :show="show" @click="show = false" />import { ref } from 'vue';export default { setup() { const show = ref(false); return { show }; },};通过默认插槽可以在遮罩层上嵌入任意内容。
<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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| show | 是否展示遮罩层 | boolean | false |
| z-index | z-index 层级 | number | string | 1 |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| class-name | 自定义类名 | string | - |
| custom-style | 自定义样式 | object | - |
| lock-scroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 默认插槽，用于在遮罩层上方嵌入内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-overlay-z-index | 1 | - |
| --van-overlay-background-color | rgba(0, 0, 0, 0.7) | - |
用于提供下拉刷新的交互操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { PullRefresh } from 'vant';const app = createApp();app.use(PullRefresh);下拉刷新时会触发 refresh 事件，在事件的回调函数中可以进行同步或异步操作，操作完成后将 v-model 设置为 false，表示加载完成。
<van-pull-refresh v-model="state.loading" @refresh="onRefresh"> <p>刷新次数: {{ state.count }}</p></van-pull-refresh>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ count: 0, loading: false, }); const onRefresh = () => { setTimeout(() => { Toast('刷新成功'); state.loading = false; state.count++; }, 1000); }; return { state, onRefresh, }; },};通过 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 实现一个缩放效果 --> <template #pulling="props"> <img class="doge" src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow" rel="external nofollow" :style="{ transform: `scale(${props.distance / 80})` }" /> </template> <!-- 释放提示 --> <template #loosing> <img class="doge" src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow" rel="external nofollow" /> </template> <!-- 加载提示 --> <template #loading> <img class="doge" src="https://img.yzcdn.cn/vant/doge-fire.jpg" rel="external nofollow" /> </template> <p>刷新次数: {{ count }}</p></van-pull-refresh><style> .doge { width: 140px; height: 72px; margin-top: 8px; border-radius: 4px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 是否处于加载中状态 | boolean | - |
| pulling-text | 下拉过程提示文案 | string | 下拉即可刷新... |
| loosing-text | 释放过程提示文案 | string | 释放即可刷新... |
| loading-text | 加载过程提示文案 | string | 加载中... |
| success-text | 刷新成功提示文案 | string | - |
| success-duration | 刷新成功提示展示时长(ms) | number | string | 500 |
| animation-duration | 动画时长 | number | string | 300 |
| head-height | 顶部内容高度 | number | string | 50 |
pull-distance v3.0.8 | 触发下拉刷新的距离 | number | string | 与 head-height 一致 |
| disabled | 是否禁用下拉刷新 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| refresh | 下拉刷新时触发 | - |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义内容 | - |
| normal | 非下拉状态时顶部内容 | - |
| pulling | 下拉过程中顶部内容 | { distance: 当前下拉距离 } |
| loosing | 释放过程中顶部内容 | { distance: 当前下拉距离 } |
| loading | 加载过程中顶部内容 | { distance: 当前下拉距离 } |
| success | 刷新成功提示内容 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-pull-refresh-head-height | 50px | - |
| --van-pull-refresh-head-font-size | var(--van-font-size-md) | - |
| --van-pull-refresh-head-text-color | var(--van-gray-6) | - |
| --van-pull-refresh-loading-icon-size | 16px | - |
默认情况下，下拉区域的高度是和内容高度保持一致的，如果需要让下拉区域始终为全屏，可以给 PullRefresh 设置一个与屏幕大小相等的最小高度：
<van-pull-refresh style="min-height: 100vh;" />PullRefresh 的触发条件是「父级滚动元素的滚动条在顶部位置」。
参见桌面端适配。
底部弹起的分享面板，用于展示各分享渠道对应的操作按钮，不含具体的分享逻辑。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ShareSheet } from 'vant';const app = createApp();app.use(ShareSheet);分享面板通过 options 属性来定义分享选项，数组的每一项是一个对象，对象格式见文档下方表格。
<van-cell title="显示分享面板" @click="showShare = true" /><van-share-sheet v-model:show="showShare" title="立即分享给好友" :options="options" @select="onSelect"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const showShare = ref(false); const options = [ { name: '微信', icon: 'wechat' }, { name: '微博', icon: 'weibo' }, { name: '复制链接', icon: 'link' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, ]; const onSelect = (option) => { Toast(option.name); showShare.value = false; }; return { options, onSelect, showShare, }; },};当分享选项的数量较多时，可以将 options 定义为数组嵌套的格式，每个子数组会作为一行选项展示。
<van-share-sheet v-model:show="showShare" title="立即分享给好友" :options="options"/>import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ [ { name: '微信', icon: 'wechat' }, { name: '朋友圈', icon: 'wechat-moments' }, { name: '微博', icon: 'weibo' }, { name: 'QQ', icon: 'qq' }, ], [ { name: '复制链接', icon: 'link' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, { name: '小程序码', icon: 'weapp-qrcode' }, ], ]; return { options, showShare, }; },};除了使用内置的几种图标外，可以直接在 icon 中传入图片 URL 来使用自定义的图标。
<van-share-sheet v-model:show="showShare" :options="options" />import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-fire.png', }, { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-light.png', }, { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-water.png', }, ]; return { options, showShare, }; },};通过 description 属性可以设置标题下方的描述文字, 在 options 内设置 description 属性可以添加分享选项描述。
<van-share-sheet v-model:show="showShare" :options="options" title="立即分享给好友" description="描述信息"/>import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ { name: '微信', icon: 'wechat' }, { name: '微博', icon: 'weibo' }, { name: '复制链接', icon: 'link', description: '描述信息' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, ]; return { options, showShare, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示分享面板 | boolean | false |
| options | 分享选项 | Option[] | [] |
| title | 顶部标题 | string | - |
| cancel-text | 取消按钮文字，传入空字符串可以隐藏按钮 | string | '取消' |
| description | 标题下方的辅助描述文字 | string | - |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| overlay | 是否显示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染内容 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
options 属性为一个对象数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 分享渠道名称 | string |
| description | 分享选项描述 | string |
| icon | 图标，可选值为 wechat weibo qq link qrcode poster weapp-qrcode wechat-moments，支持传入图片 URL | string |
| className | 分享选项类名 | string |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击分享选项时触发 | option: Option, index: number |
| cancel | 点击取消按钮时触发 | - |
| open | 打开面板时触发 | - |
| close | 关闭面板时触发 | - |
| opened | 打开面板且动画结束后触发 | - |
| closed | 关闭面板且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| title | 自定义顶部标题 |
| description | 自定义描述文字 |
cancel v3.0.10 | 自定义取消按钮内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-share-sheet-header-padding | var(--van-padding-sm) var(--van-padding-md) var(--van-padding-base) | - |
| --van-share-sheet-title-color | var(--van-text-color) | - |
| --van-share-sheet-title-font-size | var(--van-font-size-md) | - |
| --van-share-sheet-title-line-height | var(--van-line-height-md) | - |
| --van-share-sheet-description-color | var(--van-gray-6) | - |
| --van-share-sheet-description-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-description-line-height | 16px | - |
| --van-share-sheet-icon-size | 48px | - |
| --van-share-sheet-option-name-color | var(--van-gray-7) | - |
| --van-share-sheet-option-name-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-option-description-color | var(--van-gray-5) | - |
| --van-share-sheet-option-description-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-cancel-button-font-size | var(--van-font-size-lg) | - |
| --van-share-sheet-cancel-button-height | 48px | - |
| --van-share-sheet-cancel-button-background | var(--van-white) | - |
在不同的 App 或浏览器中，存在各式各样的分享接口或分享方式，因此 ShareSheet 组件不提供具体的分享逻辑，需要开发者根据业务场景自行实现。
由于微信未提供分享相关的 API，需要引导用户点击右上角进行分享。
可以通过 JSBridge 调用原生应用的 SDK 进行分享。
可以通过 Popup 组件以弹层的形式展示图片，然后引导用户保存图片进行分享。
可以左右滑动来展示操作按钮的单元格组件。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { SwipeCell } from 'vant';const app = createApp();app.use(SwipeCell);SwipeCell 组件提供了 left 和 right 两个插槽，用于定义两侧滑动区域的内容。
<van-swipe-cell> <template #left> <van-button square type="primary" text="选择" /> </template> <van-cell :border="false" title="单元格" value="内容" /> <template #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" /> <template #right> <van-button square text="删除" type="danger" class="delete-button" /> </template></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 #left> <van-button square type="primary" text="选择" /> </template> <van-cell :border="false" title="单元格" value="内容" /> <template #right> <van-button square type="danger" text="删除" /> </template></van-swipe-cell>import { Dialog } from 'vant';export default { setup() { // position 为关闭时点击的位置 const beforeClose = ({ position }) => { switch (position) { case 'left': case 'cell': case 'outside': return true; case 'right': return new Promise((resolve) => { Dialog.confirm({ title: '确定删除吗？', }).then(resolve); }); } }; return { beforeClose }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符，可以在事件参数中获取到 | number | string | '' |
| left-width | 指定左侧滑动区域宽度，单位为 px | number | string | auto |
| right-width | 指定右侧滑动区域宽度，单位为 px | number | string | auto |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (args) => boolean | Promise<boolean> | - |
| disabled | 是否禁用滑动 | boolean | false |
| stop-propagation | 是否阻止滑动事件冒泡 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 默认显示的内容 |
| left | 左侧滑动区域的内容 |
| right | 右侧滑动区域的内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | position: 'left' | 'right' | 'cell' | 'outside' |
| open | 打开时触发 | { name: string | number, position: 'left' | 'right' } |
| close | 关闭时触发 | { name: string | number, position: 'left' | 'right' | 'cell' | 'outside' } |
beforeClose 的第一个参数为对象，对象中包含以下属性：
| 参数名 | 说明 | 类型 |
|---|---|---|
| name | 标识符 | string | number |
| position | 关闭时的点击位置 | 'left' | 'right' | 'cell' | 'outside' |
通过 ref 可以获取到 SwipeCell 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| open | 打开单元格侧边栏 | position: left | right | - |
| close | 收起单元格侧边栏 | - | - |
通过 SwipeCellInstance 获取 SwipeCell 实例的类型定义。
import { ref } from 'vue';import type { SwipeCellInstance } from 'vant';const swipeCellRef = ref<SwipeCellInstance>();swipeCellRef.value?.close();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-switch-cell-padding-top | var(--van-cell-vertical-padding) - 1px | - |
| --van-switch-cell-padding-bottom | var(--van-cell-vertical-padding) - 1px | - |
| --van-switch-cell-large-padding-top | var(--van-cell-large-vertical-padding) - 1px | - |
| --van-switch-cell-large-padding-bottom | var(--van-cell-large-vertical-padding) - 1px | - |
参见桌面端适配。
在右上角展示徽标数字或小红点。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Badge } from 'vant';const app = createApp();app.use(Badge);设置 content 属性后，Badge 会在子元素的右上角显示对应的徽标，也可以通过 dot 来显示小红点。
<van-badge :content="5"> <div class="child" /></van-badge><van-badge :content="10"> <div class="child" /></van-badge><van-badge content="Hot"> <div class="child" /></van-badge><van-badge dot> <div class="child" /></van-badge><style> .child { width: 40px; height: 40px; background: #f2f3f5; border-radius: 4px; }</style>设置 max 属性后，当 content 的数值超过最大值时，会自动显示为 {max}+。
<van-badge :content="20" max="9"> <div class="child" /></van-badge><van-badge :content="50" max="20"> <div class="child" /></van-badge><van-badge :content="200" max="99"> <div class="child" /></van-badge>通过 color 属性来设置徽标的颜色。
<van-badge :content="5" color="#1989fa"> <div class="child" /></van-badge><van-badge :content="10" color="#1989fa"> <div class="child" /></van-badge><van-badge dot color="#1989fa"> <div class="child" /></van-badge>通过 content 插槽可以自定义徽标的内容，比如插入一个图标。
<van-badge> <div class="child" /> <template #content> <van-icon name="success" class="badge-icon" /> </template></van-badge><van-badge> <div class="child" /> <template #content> <van-icon name="cross" class="badge-icon" /> </template></van-badge><van-badge> <div class="child" /> <template #content> <van-icon name="down" class="badge-icon" /> </template></van-badge>.badge-icon { display: block; font-size: 10px; line-height: 16px;}当 Badge 没有子元素时，会作为一个独立的元素进行展示。
<van-badge :content="20" /><van-badge :content="200" max="99" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 徽标内容 | number | string | - |
| color | 徽标背景颜色 | string | #ee0a24 |
| dot | 是否展示为小红点 | boolean | false |
| max | 最大值，超过最大值会显示 {max}+，仅当 content 为数字时有效 | number | string | - |
offset v3.0.5 | 设置徽标的偏移量，数组的两项分别对应水平和垂直方向的偏移量，默认单位为 px | [number | string, number | string] | - |
show-zero v3.0.10 | 当 content 为数字 0 时，是否展示徽标 | boolean | true |
| 名称 | 说明 |
|---|---|
| default | 徽标包裹的子元素 |
| content | 自定义徽标内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-badge-size | 16px | - |
| --van-badge-color | var(--van-white) | - |
| --van-badge-padding | 0 3px | - |
| --van-badge-font-size | var(--van-font-size-sm) | - |
| --van-badge-font-weight | var(--van-font-weight-bold) | - |
| --van-badge-border-width | var(--van-border-width-base) | - |
| --van-badge-background-color | var(--van-danger-color) | - |
| --van-badge-dot-color | var(--van-danger-color) | - |
| --van-badge-dot-size | 8px | - |
| --van-badge-font-family | -apple-system-font, Helvetica Neue, Arial, sans-serif | - |
圆环形的进度条组件，支持进度渐变动画。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Circle } from 'vant';const app = createApp();app.use(Circle);rate 属性表示进度条的目标进度，v-model:current-rate 表示动画过程中的实时进度。当 rate 发生变化时，v-model:current-rate 会以 speed 的速度变化，直至达到 rate 设定的值。
<van-circle v-model:current-rate="currentRate" :rate="30" :speed="100" :text="text"/>import { ref, computed } from 'vue';export default { setup() { const currentRate = ref(0); const text = computed(() => currentRate.value.toFixed(0) + '%'); return { text, currentRate, }; },};通过 stroke-width 属性来控制进度条宽度。
<van-circle v-model:current-rate="currentRate" :rate="rate" :stroke-width="60" text="宽度定制"/>通过 color 属性来控制进度条颜色，layer-color 属性来控制轨道颜色。
<van-circle v-model:current-rate="currentRate" :rate="rate" layer-color="#ebedf0" text="颜色定制"/>color 属性支持传入对象格式来定义渐变色。
<van-circle v-model:current-rate="currentRate" :rate="rate" :color="gradientColor" text="渐变色"/>import { ref } from 'vue';export default { setup() { const currentRate = ref(0); const gradientColor = { '0%': '#3fecff', '100%': '#6149f6', }; return { currentRate, gradientColor, }; },};将 clockwise 设置为 false，进度会从逆时针方向开始。
<van-circle v-model:current-rate="currentRate" :rate="rate" :clockwise="false" text="逆时针方向"/>通过 size 属性设置圆环直径。
<van-circle v-model:current-rate="currentRate" :rate="rate" size="120px" text="大小定制"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:current-rate | 当前进度 | number | - |
| rate | 目标进度 | number | string | 100 |
| size | 圆环直径，默认单位为 px | number | string | 100px |
| color | 进度条颜色，传入对象格式可以定义渐变色 | string | object | #1989fa |
| layer-color | 轨道颜色 | string | white |
| fill | 填充颜色 | string | none |
| speed | 动画速度（单位为 rate/s） | number | string | 0 |
| text | 文字 | string | - |
| stroke-width | 进度条宽度 | number | string | 40 |
| stroke-linecap | 进度条端点的形状，可选值为 square butt | string | round |
| clockwise | 是否顺时针增加 | boolean | true |
| 名称 | 说明 |
|---|---|
| default | 自定义文字内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-circle-size | 100px | - |
| --van-circle-color | var(--van-primary-color) | - |
| --van-circle-layer-color | var(--van-white) | - |
| --van-circle-text-color | var(--van-text-color) | - |
| --van-circle-text-font-weight | var(--van-font-weight-bold) | - |
| --van-circle-text-font-size | var(--van-font-size-md) | - |
| --van-circle-text-line-height | var(--van-line-height-md) | - |
将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Collapse, CollapseItem } from 'vant';const app = createApp();app.use(Collapse);app.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">内容</van-collapse-item></van-collapse>import { ref } from 'vue';export default { setup() { const activeNames = ref(['1']); return { activeNames }; },};通过 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>import { ref } from 'vue';export default { setup() { const activeName = ref('1'); return { activeName }; },};通过 disabled 属性来禁用单个面板。
<van-collapse v-model="activeNames"> <van-collapse-item title="标题1" name="1">内容</van-collapse-item> <van-collapse-item title="标题2" name="2" disabled>内容</van-collapse-item> <van-collapse-item title="标题3" name="3" disabled>内容</van-collapse-item></van-collapse>通过 title 插槽可以自定义标题栏的内容。
<van-collapse v-model="activeNames"> <van-collapse-item name="1"> <template #title> <div>标题1 <van-icon name="question-o" /></div> </template> 内容 </van-collapse-item> <van-collapse-item title="标题2" name="2" icon="shop-o"> 内容 </van-collapse-item></van-collapse>import { ref } from 'vue';export default { setup() { const activeNames = ref(['1']); return { activeNames }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前展开面板的 name | 手风琴模式：number | string 非手风琴模式：(number | string)[] | - |
| accordion | 是否开启手风琴模式 | boolean | false |
| border | 是否显示外边框 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换面板时触发 | activeNames: 类型与 v-model 绑定的值一致 |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 唯一标识符，默认为索引值 | number | string | index |
| icon | 标题栏左侧图标名称或图片链接 | string | - |
| size | 标题栏大小，可选值为 large | string | - |
| title | 标题栏左侧内容 | number | string | - |
| value | 标题栏右侧内容 | number | string | - |
| label | 标题栏描述信息 | number | string | - |
| border | 是否显示内边框 | boolean | true |
| is-link | 是否展示标题栏右侧箭头并开启点击反馈 | boolean | true |
| disabled | 是否禁用面板 | boolean | false |
readonly v3.0.12 | 是否为只读状态，只读状态下无法操作面板 | boolean | false |
| title-class | 左侧标题额外类名 | string | - |
| value-class | 右侧内容额外类名 | string | - |
| label-class | 描述信息额外类名 | string | - |
通过 ref 可以获取到 CollapseItem 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换面试展开状态，传 true 为展开，false 为收起，不传参为切换 | expand?: boolean | - |
通过 CollapseItemInstance 获取 CollapseItem 实例的类型定义。
import { ref } from 'vue';import type { CollapseItemInstance } from 'vant';const collapseItemRef = ref<CollapseItemInstance>();collapseItemRef.value?.toggle();| 名称 | 说明 |
|---|---|
| default | 面板内容 |
| title | 自定义标题栏左侧内容 |
| value | 自定义标题栏右侧内容 |
label v3.1.1 | 自定义标题栏描述信息 |
| icon | 自定义标题栏左侧图标 |
| right-icon | 自定义标题栏右侧图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-collapse-item-transition-duration | var(--van-animation-duration-base) | - |
| --van-collapse-item-content-padding | var(--van-padding-sm) var(--van-padding-md) | - |
| --van-collapse-item-content-font-size | var(--van-font-size-md) | - |
| --van-collapse-item-content-line-height | 1.5 | - |
| --van-collapse-item-content-text-color | var(--van-gray-6) | - |
| --van-collapse-item-content-background-color | var(--van-white) | - |
| --van-collapse-item-title-disabled-color | var(--van-gray-5) | - |
用于实时展示倒计时数值，支持毫秒精度。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { CountDown } from 'vant';const app = createApp();app.use(CountDown);time 属性表示倒计时总时长，单位为毫秒。
<van-count-down :time="time" />import { ref } from 'vue';export default { setup() { const time = ref(30 * 60 * 60 * 1000); return { time }; },};通过 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 #default="timeData"> <span class="block">{{ timeData.hours }}</span> <span class="colon">:</span> <span class="block">{{ timeData.minutes }}</span> <span class="colon">:</span> <span class="block">{{ timeData.seconds }}</span> </template></van-count-down><style> .colon { display: inline-block; margin: 0 4px; color: #ee0a24; } .block { display: inline-block; width: 22px; color: #fff; font-size: 12px; text-align: center; background-color: #ee0a24; }</style>通过 ref 获取到组件实例后，可以调用 start、pause、reset 方法。
<van-count-down ref="countDown" millisecond :time="3000" :auto-start="false" format="ss:SSS" @finish="onFinish"/><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 { setup() { const countDown = ref(null); const start = () => { countDown.value.start(); }; const pause = () => { countDown.value.pause(); }; const reset = () => { countDown.value.reset(); }; const onFinish = () => Toast('倒计时结束'); return { start, pause, reset, onFinish, countDown, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| time | 倒计时时长，单位毫秒 | number | string | 0 |
| format | 时间格式 | string | HH:mm:ss |
| auto-start | 是否自动开始倒计时 | boolean | true |
| millisecond | 是否开启毫秒级渲染 | boolean | false |
| 格式 | 说明 |
|---|---|
| DD | 天数 |
| HH | 小时 |
| mm | 分钟 |
| ss | 秒数 |
| S | 毫秒（1 位） |
| SS | 毫秒（2 位） |
| SSS | 毫秒（3 位） |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| finish | 倒计时结束时触发 | - |
| change | 倒计时变化时触发 | currentTime: CurrentTime |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义内容 | currentTime: CurrentTime |
| 名称 | 说明 | 类型 |
|---|---|---|
| total | 剩余总时间（单位毫秒） | number |
| days | 剩余天数 | number |
| hours | 剩余小时 | number |
| minutes | 剩余分钟 | number |
| seconds | 剩余秒数 | number |
| milliseconds | 剩余毫秒 | number |
通过 ref 可以获取到 CountDown 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| start | 开始倒计时 | - | - |
| pause | 暂停倒计时 | - | - |
| reset | 重设倒计时，若 auto-start 为 true，重设后会自动开始倒计时 | - | - |
通过 CountDownInstance 获取 CountDown 实例的类型定义。
import { ref } from 'vue';import type { CountDownInstance } from 'vant';const countDownRef = ref<CountDownInstance>();countDownRef.value?.start();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-count-down-text-color | var(--van-text-color) | - |
| --van-count-down-font-size | var(--van-font-size-md) | - |
| --van-count-down-line-height | var(--van-line-height-md) | - |
如果你遇到了在 iOS 上倒计时不生效的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
用于将内容分隔为多个区域。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Divider } from 'vant';const app = createApp();app.use(Divider);默认渲染一条水平分割线。
<van-divider />通过插槽在可以分割线中间插入内容。
<van-divider>文字</van-divider>通过 content-position 指定内容所在位置。
<van-divider content-position="left">文字</van-divider><van-divider content-position="right">文字</van-divider>添加 dashed 属性使分割线渲染为虚线。
<van-divider dashed>文字</van-divider>可以直接通过 style 属性设置分割线的样式。
<van-divider :style="{ color: '#1989fa', borderColor: '#1989fa', padding: '0 16px' }"> 文字</van-divider>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| dashed | 是否使用虚线 | boolean | false |
| hairline | 是否使用 0.5px 线 | boolean | true |
| content-position | 内容位置，可选值为 left right | string | center |
| 名称 | 说明 |
|---|---|
| default | 内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-divider-margin | var(--van-padding-md) 0 | - |
| --van-divider-text-color | var(--van-gray-6) | - |
| --van-divider-font-size | var(--van-font-size-md) | - |
| --van-divider-line-height | 24px | - |
| --van-divider-border-color | var(--van-border-color) | - |
| --van-divider-content-padding | var(--van-padding-md) | - |
| --van-divider-content-left-width | 10% | - |
| --van-divider-content-right-width | 10% | - |
空状态时的占位提示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Empty } from 'vant';const app = createApp();app.use(Empty);<van-empty description="描述文字" />Empty 组件内置了多种占位图片类型，可以在不同业务场景下使用。
<!-- 通用错误 --><van-empty image="error" description="描述文字" /><!-- 网络错误 --><van-empty image="network" description="描述文字" /><!-- 搜索提示 --><van-empty image="search" description="描述文字" />需要自定义图片时，可以在 image 属性中传入任意图片 URL。
<van-empty class="custom-image" image="https://img.yzcdn.cn/vant/custom-empty-image.png" description="描述文字"/><style> .custom-image .van-empty__image { width: 90px; height: 90px; }</style>通过默认插槽可以在 Empty 组件的下方插入内容。
<van-empty description="描述文字"> <van-button round type="danger" class="bottom-button">按钮</van-button></van-empty><style> .bottom-button { width: 160px; height: 40px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| image | 图片类型，可选值为 error network search，支持传入图片 URL | string | default |
| image-size | 图片大小，默认单位为 px | number | string | - |
| description | 图片下方的描述文字 | string | - |
| 名称 | 说明 |
|---|---|
| default | 自定义底部内容 |
| image | 自定义图标 |
| description | 自定义描述文字 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-empty-padding | var(--van-padding-xl) 0 | - |
| --van-empty-image-size | 160px | - |
| --van-empty-description-margin-top | var(--van-padding-md) | - |
| --van-empty-description-padding | 0 60px | - |
| --van-empty-description-color | var(--van-gray-6) | - |
| --van-empty-description-font-size | var(--van-font-size-md) | - |
| --van-empty-description-line-height | var(--van-line-height-md) | - |
| --van-empty-bottom-margin-top | 24px | - |
图片放大预览，支持函数调用和组件调用两种方式。
ImagePreview 是一个函数，调用函数后会直接在页面中展示图片预览界面。
import { ImagePreview } from 'vant';ImagePreview(['https://img.yzcdn.cn/vant/apple-1.jpg']);通过组件调用 ImagePreview 时，可以通过下面的方式进行注册。
import { createApp } from 'vue';import { ImagePreview } from 'vant';// 全局注册const app = createApp();app.use(ImagePreview);// 局部注册export default { components: { [ImagePreview.Component.name]: ImagePreview.Component, },};直接传入图片数组，即可展示图片预览。
ImagePreview([ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg',]);ImagePreview 支持传入配置对象，并通过 startPosition 选项指定图片的初始位置（索引值）。
ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], startPosition: 1,});设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用close-icon-position 属性可以自定义图标位置。
ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], closeable: true,});通过 onClose 选项监听图片预览的关闭事件。
import { Toast } from 'vant';ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], onClose() { Toast('关闭'); },});通过 beforeClose 属性可以拦截关闭行为。
const instance = ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], beforeClose: () => false,});setTimeout(() => { // 调用实例上的 close 方法手动关闭图片预览 instance.close();}, 2000);如果需要在图片预览内嵌入组件或其他自定义内容，可以使用组件调用的方式，调用前需要通过 app.use 注册组件。
<van-image-preview v-model:show="state.show" :images="state.images" @change="onChange"> <template v-slot:index>第{{ index }}页</template></van-image-preview>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, index: 0, }); const onChange = (index) => { state.index = index; }; return { state, images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], onChange, }; },};通过函数调用 ImagePreview 时，支持传入以下选项：
| 参数名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| images | 需要预览的图片 URL 数组 | string[] | [] |
| startPosition | 图片预览起始位置索引 | number | string | 0 |
| swipeDuration | 动画时长，单位为 ms | number | string | 300 |
| showIndex | 是否显示页码 | boolean | true |
| showIndicators | 是否显示轮播指示器 | boolean | false |
| loop | 是否开启循环播放 | boolean | true |
| onClose | 关闭时的回调函数 | Function | - |
| onChange | 切换图片时的回调函数，回调参数为当前索引 | Function | - |
| onScale | 缩放图片时的回调函数，回调参数为当前索引和当前缩放值组成的对象 | Function | - |
| beforeClose | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| closeOnPopstate | 是否在页面回退时自动关闭 | boolean | true |
| className | 自定义类名 | string | Array | object | - |
| maxZoom | 手势缩放时，最大缩放比例 | number | string | 3 |
| minZoom | 手势缩放时，最小缩放比例 | number | string | 1/3 |
| closeable | 是否显示关闭图标 | boolean | false |
| closeIcon | 关闭图标名称或图片链接 | string | clear |
| closeIconPosition | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
transition v3.0.8 | 动画类名，等价于 transition 的 name 属性 | string | van-fade |
overlay-style v3.0.8 | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下 Props：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否展示图片预览 | boolean | false |
| images | 需要预览的图片 URL 数组 | string[] | [] |
| start-position | 图片预览起始位置索引 | number | string | 0 |
| swipe-duration | 动画时长，单位为 ms | number | string | 300 |
| show-index | 是否显示页码 | boolean | true |
| show-indicators | 是否显示轮播指示器 | boolean | false |
| loop | 是否开启循环播放 | boolean | true |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| class-name | 自定义类名 | string | Array | object | - |
| max-zoom | 手势缩放时，最大缩放比例 | number | string | 3 |
| min-zoom | 手势缩放时，最小缩放比例 | number | string | 1/3 |
| closeable | 是否显示关闭图标 | boolean | false |
| close-icon | 关闭图标名称或图片链接 | string | clear |
| close-icon-position | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
transition v3.0.8 | 动画类名，等价于 transition 的 name 属性 | string | van-fade |
overlay-style v3.0.8 | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下事件：
| 事件 | 说明 | 回调参数 |
|---|---|---|
| close | 关闭时触发 | { index: 索引, url: 图片链接 } |
| closed | 关闭且且动画结束后触发 | - |
| change | 切换当前图片时触发 | index: 当前图片的索引 |
| scale | 缩放当前图片时触发 | { index: 当前图片的索引, scale: 当前缩放的值 } |
通过组件调用 ImagePreview 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
swipeTo 2.9.0 | 切换到指定位置 | index: number, options: Options | - |
通过组件调用 ImagePreview 时，支持以下插槽：
| 名称 | 说明 | 参数 |
|---|---|---|
| index | 自定义页码内容 | { index: 当前图片的索引 } |
| cover | 自定义覆盖在图片预览上方的内容 | - |
| 参数名 | 说明 | 类型 |
|---|---|---|
| url | 当前图片 URL | string |
| index | 当前图片的索引值 | number |
| 参数名 | 说明 | 类型 |
|---|---|---|
| index | 当前图片的索引值 | number |
| scale | 当前图片的缩放值 | number |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-image-preview-index-text-color | var(--van-white) | - |
| --van-image-preview-index-font-size | var(--van-font-size-md) | - |
| --van-image-preview-index-line-height | var(--van-line-height-md) | - |
| --van-image-preview-index-text-shadow | 0 1px 1px var(--van-gray-8) | - |
| --van-image-preview-overlay-background-color | rgba(0, 0, 0, 0.9) | - |
| --van-image-preview-close-icon-size | 22px | - |
| --van-image-preview-close-icon-color | var(--van-gray-5) | - |
| --van-image-preview-close-icon-active-color | var(--van-gray-6) | - |
| --van-image-preview-close-icon-margin | var(--van-padding-md) | - |
| --van-image-preview-close-icon-z-index | 1 | - |
参见桌面端适配。
请注意 ImagePreview 是一个函数，ImagePreview.Component 才是 ImagePreview 对应的组件。JSX 调用图片预览的正确姿势如下：
export default { setup() { const show = ref(false); return () => <ImagePreview.Component v-model={[show, 'show']} />; },};当页面需要加载大量内容时，使用懒加载可以实现延迟加载页面可视区域外的内容，从而使页面加载更流畅。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
Lazyload 是 Vue 指令，使用前需要对指令进行注册。
import { createApp } from 'vue';import { Lazyload } from 'vant';const app = createApp();app.use(Lazyload);// 注册时可以配置额外的选项app.use(Lazyload, { lazyComponent: true,});将 v-lazy 指令的值设置为你需要懒加载的图片。
<img v-for="img in imageList" v-lazy="img" />export default { setup() { return { imageList: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], }; },};和图片懒加载不同，背景图懒加载需要使用 v-lazy:background-image，值设置为背景图片的地址，需要注意的是必须声明容器高度。
<div v-for="img in imageList" v-lazy:background-image="img" />将需要懒加载的组件放在 lazy-component 标签中，即可实现组件懒加载。
// 注册时设置`lazyComponent`选项app.use(Lazyload, { lazyComponent: true,});<lazy-component> <img v-for="img in imageList" v-lazy="img" /></lazy-component>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| loading | 加载时的图片 | string | - |
| error | 错误时的图片 | string | - |
| preload | 预加载高度的比例 | string | - |
| attempt | 尝试次数 | number | 3 |
| listenEvents | 监听的事件 | string[] | scroll等 |
| adapter | 适配器 | object | - |
| filter | 图片 URL 过滤 | object | - |
| lazyComponent | 是否能懒加载模块 | boolean | false |
更多内容请参照：vue-lazyload 官方文档
由于 Lazyload 组件在注册时可以传入一些配置项，所以我们不会自动注册 Lazyload 组件，需要手动进行注册：
const app = Vue.createApp();app.use(vant.Lazyload, { lazyComponent: true,});用于循环播放展示一组消息通知。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NoticeBar } from 'vant';const app = createApp();app.use(NoticeBar);通过 text 属性设置通知栏的内容，通过 left-icon 属性设置通知栏左侧的图标。
<van-notice-bar left-icon="volume-o" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>通知栏的内容长度溢出时会自动开启滚动播放，通过 scrollable 属性可以控制该行为。
<!-- 文字较短时，通过设置 scrollable 属性开启滚动播放 --><van-notice-bar scrollable text="技术是开发它的人的共同灵魂。" /><!-- 文字较长时，通过禁用 scrollable 属性关闭滚动播放 --><van-notice-bar :scrollable="false" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>文字较长时，可以通过设置 wrapable 属性来开启多行展示。
<van-notice-bar wrapable :scrollable="false" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>通知栏支持 closeable 和 link 两种模式。
<!-- closeable 模式，在右侧显示关闭按钮 --><van-notice-bar mode="closeable">技术是开发它的人的共同灵魂。</van-notice-bar><!-- link 模式，在右侧显示链接箭头 --><van-notice-bar mode="link">技术是开发它的人的共同灵魂。</van-notice-bar>通过 color 属性设置文本颜色，通过 background 属性设置背景色。
<van-notice-bar color="#1989fa" background="#ecf9ff" left-icon="info-o"> 技术是开发它的人的共同灵魂。</van-notice-bar>搭配 NoticeBar 和 Swipe 组件可以实现垂直滚动的效果。
<van-notice-bar left-icon="volume-o" :scrollable="false"> <van-swipe vertical class="notice-swipe" :autoplay="3000" :show-indicators="false" > <van-swipe-item>内容 1</van-swipe-item> <van-swipe-item>内容 2</van-swipe-item> <van-swipe-item>内容 3</van-swipe-item> </van-swipe></van-notice-bar><style> .notice-swipe { height: 40px; line-height: 40px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| mode | 通知栏模式，可选值为 closeable link | string | '' |
| text | 通知文本内容 | string | '' |
| color | 通知文本颜色 | string | #f60 |
| background | 滚动条背景 | string | #fff7cc |
| left-icon | 左侧图标名称或图片链接 | string | - |
| delay | 动画延迟时间 (s) | number | string | 1 |
| speed | 滚动速率 (px/s) | number | string | 60 |
| scrollable | 是否开启滚动播放，内容长度溢出时默认开启 | boolean | - |
| wrapable | 是否开启文本换行，只在禁用滚动时生效 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击通知栏时触发 | event: MouseEvent |
| close | 关闭通知栏时触发 | event: MouseEvent |
| replay | 每当滚动栏重新开始滚动时触发 | - |
通过 ref 可以获取到 NoticeBar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
reset v3.1.1 | 重置通知栏到初始状态 | - | - |
| 名称 | 内容 |
|---|---|
| default | 通知文本内容 |
| left-icon | 自定义左侧图标 |
| right-icon | 自定义右侧图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-notice-bar-height | 40px | - |
| --van-notice-bar-padding | 0 var(--van-padding-md) | - |
| --van-notice-bar-wrapable-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-notice-bar-text-color | var(--van-orange-dark) | - |
| --van-notice-bar-font-size | var(--van-font-size-md) | - |
| --van-notice-bar-line-height | 24px | - |
| --van-notice-bar-background-color | var(--van-orange-light) | - |
| --van-notice-bar-icon-size | 16px | - |
| --van-notice-bar-icon-min-width | 24px | - |
弹出式的气泡菜单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Popover } from 'vant';const app = createApp();app.use(Popover);当 Popover 弹出时，会基于 reference 插槽的内容进行定位。
<van-popover v-model:show="showPopover" :actions="actions" @select="onSelect"> <template #reference> <van-button type="primary">浅色风格</van-button> </template></van-popover>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const showPopover = ref(false); // 通过 actions 属性来定义菜单选项 const actions = [ { text: '选项一' }, { text: '选项二' }, { text: '选项三' }, ]; const onSelect = (action) => Toast(action.text); return { actions, onSelect, showPopover, }; },};Popover 支持浅色和深色两种风格，默认为浅色风格，将 theme 属性设置为 dark 可切换为深色风格。
<van-popover v-model:show="showPopover" theme="dark" :actions="actions"> <template #reference> <van-button type="primary">深色风格</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一' }, { text: '选项二' }, { text: '选项三' }, ]; return { actions, showPopover, }; },};通过 placement 属性来控制气泡的弹出位置。
<van-popover placement="top" />placement 支持以下值：
top # 顶部中间位置top-start # 顶部左侧位置top-end # 顶部右侧位置left # 左侧中间位置left-start # 左侧上方位置left-end # 左侧下方位置right # 右侧中间位置right-start # 右侧上方位置right-end # 右侧下方位置bottom # 底部中间位置bottom-start # 底部左侧位置bottom-end # 底部右侧位置在 actions 数组中，可以通过 icon 字段来定义选项的图标，支持传入图标名称或图片链接。
<van-popover v-model:show="showPopover" :actions="actions"> <template #reference> <van-button type="primary">展示图标</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一', icon: 'add-o' }, { text: '选项二', icon: 'music-o' }, { text: '选项三', icon: 'more-o' }, ]; return { actions, showPopover, }; },};在 actions 数组中，可以通过 disabled 字段来禁用某个选项。
<van-popover v-model:show="showPopover" :actions="actions"> <template #reference> <van-button type="primary">禁用选项</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一', disabled: true }, { text: '选项二', disabled: true }, { text: '选项三' }, ]; return { actions, showPopover, }; },};通过默认插槽，可以在 Popover 内部放置任意内容。
<van-popover v-model:show="showPopover"> <van-grid square clickable :border="false" column-num="3" style="width: 240px;" > <van-grid-item v-for="i in 6" :key="i" text="选项" icon="photo-o" @click="showPopover = false" /> </van-grid> <template #reference> <van-button type="primary">自定义内容</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); return { showPopover }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否展示气泡弹出层 | boolean | false |
| actions | 选项列表 | Action[] | [] |
| placement | 弹出位置 | string | bottom |
| theme | 主题风格，可选值为 dark | string | light |
| trigger | 触发方式，可选值为 manual | click | |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| offset | 出现位置的偏移量 | [number, number] | [0, 8] |
| overlay | 是否显示遮罩层 | boolean | false |
overlay-class v3.0.10 | 自定义遮罩层类名 | string | Array | object | - |
overlay-style v3.0.10 | 自定义遮罩层样式 | object | - |
| close-on-click-action | 是否在点击选项后关闭 | boolean | true |
| close-on-click-outside | 是否在点击外部元素后关闭菜单 | boolean | true |
close-on-click-overlay v3.0.10 | 是否在点击遮罩层后关闭菜单 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | body |
icon-prefix v3.0.17 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 选项文字 | string |
| icon | 文字左侧的图标，支持传入图标名称或图片链接 | string |
| color | 选项文字颜色 | string |
| disabled | 是否为禁用状态 | boolean |
| className | 为对应选项添加额外的类名 | string | Array | object |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击选项时触发 | action: Action, index: number |
| open | 打开菜单时触发 | - |
| close | 关闭菜单时触发 | - |
| opened | 打开菜单且动画结束后触发 | - |
| closed | 关闭菜单且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义菜单内容 |
| reference | 触发 Popover 显示的元素内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-popover-arrow-size | 6px | - |
| --van-popover-border-radius | var(--van-border-radius-lg) | - |
| --van-popover-action-width | 128px | - |
| --van-popover-action-height | 44px | - |
| --van-popover-action-font-size | var(--van-font-size-md) | - |
| --van-popover-action-line-height | var(--van-line-height-md) | - |
| --van-popover-action-icon-size | 20px | - |
| --van-popover-light-text-color | var(--van-text-color) | - |
| --van-popover-light-background-color | var(--van-white) | - |
| --van-popover-light-action-disabled-text-color | var(--van-gray-5) | - |
| --van-popover-dark-text-color | var(--van-white) | - |
| --van-popover-dark-background-color | #4a4a4a | - |
| --van-popover-dark-action-disabled-text-color | var(--van-gray-6) | - |
这种情况通常是由于项目中引入了 fastclick 库导致的。建议移除 fastclick，或者配置 fastclick 的 ignore 规则。
用于展示操作的当前进度。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Progress } from 'vant';const app = createApp();app.use(Progress);进度条默认为蓝色，使用 percentage 属性来设置当前进度。
<van-progress :percentage="50" />通过 stroke-width 可以设置进度条的粗细。
<van-progress :percentage="50" stroke-width="8" />设置 inactive 属性后进度条将置灰。
<van-progress inactive :percentage="50" />可以使用 pivot-text 属性自定义文字，color 属性自定义进度条颜色。
<van-progress pivot-text="橙色" color="#f2826a" :percentage="25" /><van-progress pivot-text="红色" color="#ee0a24" :percentage="50" /><van-progress :percentage="75" pivot-text="紫色" pivot-color="#7232dd" color="linear-gradient(to right, #be99ff, #7232dd)"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| percentage | 进度百分比 | number | string | 0 |
| stroke-width | 进度条粗细，默认单位为px | number | string | 4px |
| color | 进度条颜色 | string | #1989fa |
| track-color | 轨道颜色 | string | #e5e5e5 |
| pivot-text | 进度文字内容 | string | 百分比 |
| pivot-color | 进度文字背景色 | string | 同进度条颜色 |
| text-color | 进度文字颜色 | string | white |
| inactive | 是否置灰 | boolean | false |
| show-pivot | 是否显示进度文字 | boolean | true |
通过 ref 可以获取到 Progress 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| resize | 外层元素大小变化后，可以调用此方法来触发重绘 | - | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-progress-height | 4px | - |
| --van-progress-color | var(--van-primary-color) | - |
| --van-progress-background-color | var(--van-gray-3) | - |
| --van-progress-pivot-padding | 0 5px | - |
| --van-progress-pivot-text-color | var(--van-white) | - |
| --van-progress-pivot-font-size | var(--van-font-size-xs) | - |
| --van-progress-pivot-line-height | 1.6 | - |
| --van-progress-pivot-background-color | var(--van-primary-color) | - |
Progress 组件在挂载时，会获取自身的宽度，并计算出进度条的样式。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法展示正确的进度。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-progress v-show="show" /><!-- After --><van-progress v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-progress v-show="show" ref="progress" />this.$refs.progress.resize();用于在内容加载过程中展示一组占位图形。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Skeleton } from 'vant';const app = createApp();app.use(Skeleton);通过 title 属性显示标题占位图，通过 row 属性配置占位段落行数。
<van-skeleton title :row="3" />通过 avatar 属性显示头像占位图。
<van-skeleton title avatar :row="3" />将 loading 属性设置成 false 表示内容加载完成，此时会隐藏占位图，并显示 Skeleton 的子组件。
<van-skeleton title avatar :row="3" :loading="loading"> <div>实际内容</div></van-skeleton>import { ref, onMounted } from 'vue';export default { setup() { const loading = ref(true); onMounted(() => { loading.value = false; }); return { loading, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| row | 段落占位图行数 | number | string | 0 |
| row-width | 段落占位图宽度，可传数组来设置每一行的宽度 | number | string | (number | string)[] | 100% |
| title | 是否显示标题占位图 | boolean | false |
| avatar | 是否显示头像占位图 | boolean | false |
| loading | 是否显示骨架屏，传 false 时会展示子组件内容 | boolean | true |
| animate | 是否开启动画 | boolean | true |
| round | 是否将标题和段落显示为圆角风格 | boolean | false |
| title-width | 标题占位图宽度 | number | string | 40% |
| avatar-size | 头像占位图大小 | number | string | 32px |
| avatar-shape | 头像占位图形状，可选值为 square | string | round |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-skeleton-row-height | 16px | - |
| --van-skeleton-row-background-color | var(--van-active-color) | - |
| --van-skeleton-row-margin-top | var(--van-padding-sm) | - |
| --van-skeleton-title-width | 40% | - |
| --van-skeleton-avatar-size | 32px | - |
| --van-skeleton-avatar-background-color | var(--van-active-color) | - |
| --van-skeleton-animation-duration | 1.2s | - |
用于展示操作流程的各个环节，让用户了解当前的操作在整体流程中的位置。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Step, Steps } from 'vant';const app = createApp();app.use(Step);app.use(Steps);active 属性表示当前步骤的索引，从 0 起计。
<van-steps :active="active"> <van-step>买家下单</van-step> <van-step>商家接单</van-step> <van-step>买家提货</van-step> <van-step>交易完成</van-step></van-steps>import { ref } from 'vue';export default { setup() { const active = ref(1); return { active }; },};可以通过 active-icon 和 active-color 属性设置激活状态下的图标和颜色。
<van-steps :active="active" active-icon="success" active-color="#38f"> <van-step>买家下单</van-step> <van-step>商家接单</van-step> <van-step>买家提货</van-step> <van-step>交易完成</van-step></van-steps>可以通过设置 direction 属性来改变步骤条的显示方向。
<van-steps direction="vertical" :active="0"> <van-step> <h3>【城市】物流状态1</h3> <p>2016-07-12 12:40</p> </van-step> <van-step> <h3>【城市】物流状态2</h3> <p>2016-07-11 10:00</p> </van-step> <van-step> <h3>快件已发货</h3> <p>2016-07-10 09:30</p> </van-step></van-steps>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| active | 当前步骤对应的索引值 | number | string | 0 |
| direction | 步骤条方向，可选值为 vertical | string | horizontal |
| active-icon | 当前步骤对应的底部图标，可选值见 Icon 组件 | string | checked |
| inactive-icon | 非当前步骤对应的底部图标，可选值见 Icon 组件 | string | - |
finish-icon v3.0.7 | 已完成步骤对应的底部图标，优先级高于 inactive-icon，可选值见 Icon 组件 | string | - |
| active-color | 当前步骤和已完成步骤的颜色 | string | #07c160 |
| inactive-color | 未激活步骤的颜色 | string | #969799 |
icon-prefix v3.0.15 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| 名称 | 说明 |
|---|---|
| active-icon | 自定义激活状态图标 |
| inactive-icon | 自定义未激活状态图标 |
finish-icon v3.0.7 | 自定义已完成步骤对应的底部图标，优先级高于 inactive-icon |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-step | 点击步骤的标题或图标时触发 | index: number |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-step-text-color | var(--van-gray-6) | - |
| --van-step-active-color | var(--van-success-color) | - |
| --van-step-process-text-color | var(--van-text-color) | - |
| --van-step-font-size | var(--van-font-size-md) | - |
| --van-step-line-color | var(--van-border-color) | - |
| --van-step-finish-line-color | var(--van-success-color) | - |
| --van-step-finish-text-color | var(--van-text-color) | - |
| --van-step-icon-size | 12px | - |
| --van-step-circle-size | 5px | - |
| --van-step-circle-color | var(--van-gray-6) | - |
| --van-step-horizontal-title-font-size | var(--van-font-size-sm) | - |
| --van-steps-background-color | var(--van-white) | - |
Sticky 组件与 CSS 中 position: sticky 属性实现的效果一致，当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在屏幕顶部。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Sticky } from 'vant';const app = createApp();app.use(Sticky);将内容包裹在 Sticky 组件内即可。
<van-sticky> <van-button type="primary">基础用法</van-button></van-sticky>通过 offset-top 属性可以设置组件在吸顶时与顶部的距离。
<van-sticky :offset-top="50"> <van-button type="primary">吸顶距离</van-button></van-sticky>通过 container 属性可以指定组件的容器，页面滚动时，组件会始终保持在容器范围内，当组件即将超出容器底部时，会固定在容器的底部。
<div ref="container" style="height: 150px;"> <van-sticky :container="container"> <van-button type="warning">指定容器</van-button> </van-sticky></div>export default { setup() { const container = ref(null); return { container }; },};将 position 设置为 bottom 可以让组件吸附在底部。通过 offset-bottom 属性可以设置组件在吸底时与底部的距离。
<van-sticky :offset-bottom="50" position="bottom"> <van-button type="primary">吸底距离</van-button></van-sticky>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
position v3.0.6 | 吸附位置，可选值为 bottom | string | top |
| offset-top | 吸顶时与顶部的距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
offset-bottom v3.0.6 | 吸底时与底部的距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
| z-index | 吸顶时的 z-index | number | string | 99 |
| container | 容器对应的 HTML 节点 | Element | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
change v3.0.10 | 当吸顶状态改变时触发 | isFixed: boolean |
| scroll | 滚动时触发 | { scrollTop: number, isFixed: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-sticky-z-index | 99 | - |
用于循环播放一组图片或内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。import { createApp } from 'vue';
import { Swipe, SwipeItem } from 'vant';const app = createApp();app.use(Swipe);app.use(SwipeItem);每个 SwipeItem 代表一张轮播卡片，可以通过 autoplay 属性设置自动轮播的间隔。
<van-swipe class="my-swipe" :autoplay="3000" indicator-color="white"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe><style> .my-swipe .van-swipe-item { color: #fff; font-size: 20px; line-height: 150px; text-align: center; background-color: #39a9ed; }</style>当 Swipe 中含有图片时，可以通过 lazy-render 属性来开启懒加载模式。在懒加载模式下，只会渲染当前页和下一页。
<van-swipe :autoplay="3000" lazy-render> <van-swipe-item v-for="image in images" :key="image"> <img :src="image" /> </van-swipe-item></van-swipe>export default { setup() { const images = [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ]; return { images }; },};在每一页轮播结束后，会触发 change 事件。
<van-swipe @change="onChange"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>import { Toast } from 'vant';export default { setup() { const onChange = (index) => Toast('当前 Swipe 索引：' + index); return { onChange }; },};设置 vertical 属性后滑块会纵向排列，此时需要指定滑块容器的高度。
<van-swipe style="height: 200px;" vertical> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>滑块默认宽度为 100%，可以通过 width 属性设置单个滑块的宽度。纵向滚动模式下，可以通过 height 属性设置单个滑块的高度。
<van-swipe :loop="false" :width="300"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>目前不支持在循环滚动模式下自定义滑块大小，因此需要将 loop 设置为 false。
通过 indicator 插槽可以自定义指示器的样式。
<van-swipe> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item> <template #indicator="{ active }"> <div class="custom-indicator">{{ active + 1 }}/4</div> </template></van-swipe><style> .custom-indicator { position: absolute; right: 5px; bottom: 5px; padding: 2px 5px; font-size: 12px; background: rgba(0, 0, 0, 0.1); }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| autoplay | 自动轮播间隔，单位为 ms | number | string | - |
| duration | 动画时长，单位为 ms | number | string | 500 |
| initial-swipe | 初始位置索引值 | number | string | 0 |
| width | 滑块宽度，单位为 px | number | string | auto |
| height | 滑块高度，单位为 px | number | string | auto |
| loop | 是否开启循环播放 | boolean | true |
| show-indicators | 是否显示指示器 | boolean | true |
| vertical | 是否为纵向滚动 | boolean | false |
| touchable | 是否可以通过手势滑动 | boolean | true |
| stop-propagation | 是否阻止滑动事件冒泡 | boolean | true |
| lazy-render | 是否延迟渲染未展示的轮播 | boolean | false |
| indicator-color | 指示器颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 每一页轮播结束后触发 | index, 当前页的索引 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
通过 ref 可以获取到 Swipe 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| prev | 切换到上一轮播 | - | - |
| next | 切换到下一轮播 | - | - |
| swipeTo | 切换到指定位置 | index: number, options: SwipeToOptions | - |
| resize | 外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘 | - | - |
通过 SwipeInstance 获取 Swipe 实例的类型定义。
import { ref } from 'vue';import type { SwipeInstance } from 'vant';const swipeRef = ref<SwipeInstance>();swipeRef.value?.next();| 名称 | 说明 | 类型 |
|---|---|---|
| immediate | 是否跳过动画 | boolean |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 轮播内容 | - |
indicator v3.0.16 | 自定义指示器 | { active: number } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-swipe-indicator-size | 6px | - |
| --van-swipe-indicator-margin | var(--van-padding-sm) | - |
| --van-swipe-indicator-active-opacity | 1 | - |
| --van-swipe-indicator-inactive-opacity | 0.3 | - |
| --van-swipe-indicator-active-background-color | var(--van-primary-color) | - |
| --van-swipe-indicator-inactive-background-color | var(--van-border-color) | - |
这种情况通常是由于项目中引入了 fastclick 库导致的。fastclick 的原理是通过 Touch 事件模拟出 click 事件，而 Swipe 内部默认会阻止 touchmove 事件冒泡，干扰了 fastclick 的判断，导致出现这个问题。
将 Swipe 组件的 stop-propagation 属性设置为 false 即可避免该问题。
参见桌面端适配。
Vant 中的 Swipe 组件是比较轻量的，因此功能也比较基础。如果需要更复杂的轮播效果，推荐使用社区里一些优质的轮播库，比如 vue-awesome-swiper。
Swipe 组件在挂载时，会获取自身的宽度，并计算出轮播图的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法正确计算位置。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-swipe v-show="show" /><!-- After --><van-swipe v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-swipe v-show="show" ref="swipe" />this.$refs.swipe.resize();用于标记关键词和概括主要内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tag } from 'vant';const app = createApp();app.use(Tag);通过 type 属性控制标签颜色。
<van-tag type="primary">标签</van-tag><van-tag type="success">标签</van-tag><van-tag type="danger">标签</van-tag><van-tag type="warning">标签</van-tag>设置 plain 属性设置为空心样式。
<van-tag plain type="primary">标签</van-tag>通过 round 设置为圆角样式。
<van-tag round type="primary">标签</van-tag>通过 mark 设置为标记样式(半圆角)。
<van-tag mark type="primary">标签</van-tag>添加 closeable 属性表示标签是可关闭的，关闭标签时会触发 close 事件，在 close 事件中可以执行隐藏标签的逻辑。
<van-tag :show="show" closeable size="medium" type="primary" @close="close"> 标签</van-tag>import { ref } from 'vue';export default { setup() { const show = ref(true); const close = () => { show.value = false; }; return { show, close, }; },};通过 size 属性调整标签大小。
<van-tag type="primary">标签</van-tag><van-tag type="primary" size="medium">标签</van-tag><van-tag type="primary" size="large">标签</van-tag>通过 color 和 text-color 属性设置标签颜色。
<van-tag color="#7232dd">标签</van-tag><van-tag color="#ffe1e1" text-color="#ad0000">标签</van-tag><van-tag color="#7232dd" plain>标签</van-tag>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success danger warning | string | default |
| size | 大小, 可选值为 large medium | string | - |
| color | 标签颜色 | string | - |
| show | 是否展示标签 | boolean | true |
| plain | 是否为空心样式 | boolean | false |
| round | 是否为圆角样式 | boolean | false |
| mark | 是否为标记样式 | boolean | false |
| text-color | 文本颜色，优先级高于 color 属性 | string | white |
| closeable | 是否为可关闭标签 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 标签显示内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| close | 关闭标签时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tag-padding | 0 var(--van-padding-base) | - |
| --van-tag-text-color | var(--van-white) | - |
| --van-tag-font-size | var(--van-font-size-sm) | - |
| --van-tag-border-radius | 2px | - |
| --van-tag-line-height | 16px | - |
| --van-tag-medium-padding | 2px 6px | - |
| --van-tag-large-padding | var(--van-padding-base) var(--van-padding-xs) | - |
| --van-tag-large-border-radius | var(--van-border-radius-md) | - |
| --van-tag-large-font-size | var(--van-font-size-md) | - |
| --van-tag-round-border-radius | var(--van-border-radius-max) | - |
| --van-tag-danger-color | var(--van-danger-color) | - |
| --van-tag-primary-color | var(--van-primary-color) | - |
| --van-tag-success-color | var(--van-success-color) | - |
| --van-tag-warning-color | var(--van-warning-color) | - |
| --van-tag-default-color | var(--van-gray-6) | - |
| --van-tag-plain-background-color | var(--van-white) | - |
用于为页面相关操作提供便捷交互。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ActionBar, ActionBarIcon, ActionBarButton } from 'vant';const app = createApp();app.use(ActionBar);app.use(ActionBarIcon);app.use(ActionBarButton);<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" @click="onClickIcon" /> <van-action-bar-icon icon="cart-o" text="购物车" @click="onClickIcon" /> <van-action-bar-icon icon="shop-o" text="店铺" @click="onClickIcon" /> <van-action-bar-button type="danger" text="立即购买" @click="onClickButton" /></van-action-bar>import { Toast } from 'vant';export default { setup() { const onClickIcon = () => Toast('点击图标'); const onClickButton = () => Toast('点击按钮'); return { onClickIcon, onClickButton, }; },};在 ActionBarIcon 组件上设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" dot /> <van-action-bar-icon icon="cart-o" text="购物车" badge="5" /> <van-action-bar-icon icon="shop-o" text="店铺" badge="12" /> <van-action-bar-button type="warning" text="加入购物车" /> <van-action-bar-button type="danger" text="立即购买" /></van-action-bar>通过 ActionBarIcon 的 color 属性可以自定义图标的颜色。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" color="#ee0a24" /> <van-action-bar-icon icon="cart-o" text="购物车" /> <van-action-bar-icon icon="star" text="已收藏" color="#ff5000" /> <van-action-bar-button type="warning" text="加入购物车" /> <van-action-bar-button type="danger" text="立即购买" /></van-action-bar>通过 ActionBarButton 的 color 属性可以自定义按钮的颜色，支持传入 linear-gradient 渐变色。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" /> <van-action-bar-icon icon="shop-o" text="店铺" /> <van-action-bar-button color="#be99ff" type="warning" text="加入购物车" /> <van-action-bar-button color="#7232dd" type="danger" text="立即购买" /></van-action-bar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 按钮文字 | string | - |
| icon | 图标 | string | - |
| color | 图标颜色 | string | #323233 |
| icon-class | 图标额外类名 | string | Array | object | - |
icon-prefix v3.0.17 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 按钮文字 | string | - |
| type | 按钮类型，可选值为 primary info warning danger | string | default |
| color | 按钮颜色，支持传入 linear-gradient 渐变色 | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| disabled | 是否禁用按钮 | boolean | false |
| loading | 是否显示为加载状态 | boolean | false |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 文本内容 |
| icon | 自定义图标 |
| 名称 | 说明 |
|---|---|
| default | 按钮显示内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-action-bar-background-color | var(--van-white) | - |
| --van-action-bar-height | 50px | - |
| --van-action-bar-icon-width | 48px | - |
| --van-action-bar-icon-height | 100% | - |
| --van-action-bar-icon-color | var(--van-text-color) | - |
| --van-action-bar-icon-size | 18px | - |
| --van-action-bar-icon-font-size | var(--van-font-size-xs) | - |
| --van-action-bar-icon-active-color | var(--van-active-color) | - |
| --van-action-bar-icon-text-color | var(--van-gray-7) | - |
| --van-action-bar-icon-background-color | var(--van-white) | - |
| --van-action-bar-button-height | 40px | - |
| --van-action-bar-button-warning-color | var(--van-gradient-orange) | - |
| --van-action-bar-button-danger-color | var(--van-gradient-red) | - |
宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Grid, GridItem } from 'vant';const app = createApp();app.use(Grid);app.use(GridItem);通过 icon 属性设置格子内的图标，text 属性设置文字内容。
<van-grid> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /></van-grid>默认一行展示四个格子，可以通过 column-num 自定义列数。
<van-grid :column-num="3"> <van-grid-item v-for="value in 6" :key="value" icon="photo-o" text="文字" /></van-grid>通过插槽可以自定义格子展示的内容。
<van-grid :border="false" :column-num="3"> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-1.jpg" rel="external nofollow" /> </van-grid-item> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-2.jpg" rel="external nofollow" /> </van-grid-item> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-3.jpg" rel="external nofollow" /> </van-grid-item></van-grid>设置 square 属性后，格子的高度会和宽度保持一致。
<van-grid square> <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" /></van-grid>通过 gutter 属性设置格子之间的距离。
<van-grid :gutter="10"> <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" /></van-grid>将 direction 属性设置为 horizontal，可以让宫格的内容呈横向排列。
<van-grid direction="horizontal" :column-num="3"> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /></van-grid>通过 to 属性设置 vue-router 跳转链接，通过 url 属性设置 URL 跳转链接。
<van-grid clickable :column-num="2"> <van-grid-item icon="home-o" text="路由跳转" to="/" /> <van-grid-item icon="search" text="URL 跳转" url="/vant/mobile.html" /></van-grid>设置 dot 属性后，会在图标右上角展示一个小红点。设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-grid :column-num="2"> <van-grid-item icon="home-o" text="文字" dot /> <van-grid-item icon="search" text="文字" badge="99+" /></van-grid>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| column-num | 列数 | number | string | 4 |
| icon-size | 图标大小，默认单位为px | number | string | 28px |
| gutter | 格子之间的间距，默认单位为px | number | string | 0 |
| border | 是否显示边框 | boolean | true |
| center | 是否将格子内容居中显示 | boolean | true |
| square | 是否将格子固定为正方形 | boolean | false |
| clickable | 是否开启格子点击反馈 | boolean | false |
| direction | 格子内容排列的方向，可选值为 horizontal | string | vertical |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 文字 | string | - |
| icon | 图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| icon-color | 图标颜色，等同于 Icon 组件的 color 属性 | string | - |
reverse v3.1.0 | 是否调换图标和文本的位置 | boolean | false |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击格子时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义宫格的所有内容 |
| icon | 自定义图标 |
| text | 自定义文字 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-grid-item-content-padding | var(--van-padding-md) var(--van-padding-xs) | - |
| --van-grid-item-content-background-color | var(--van-white) | - |
| --van-grid-item-content-active-color | var(--van-active-color) | - |
| --van-grid-item-icon-size | 28px | - |
| --van-grid-item-text-color | var(--van-gray-7) | - |
| --van-grid-item-text-font-size | var(--van-font-size-sm) | - |
用于列表的索引分类显示和快速定位。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { IndexBar, IndexAnchor } from 'vant';const app = createApp();app.use(IndexBar);app.use(IndexAnchor);点击索引栏时，会自动跳转到对应的 IndexAnchor 锚点位置。
<van-index-bar> <van-index-anchor index="A" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-index-anchor index="B" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> ...</van-index-bar>可以通过 index-list 属性自定义展示的索引字符列表。
<van-index-bar :index-list="indexList"> <van-index-anchor index="1">标题1</van-index-anchor> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-index-anchor index="2">标题2</van-index-anchor> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> ...</van-index-bar>export default { setup() { return { indexList: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| index-list | 索引字符列表 | string[] | number[] | A-Z |
| z-index | z-index 层级 | number | string | 1 |
| sticky | 是否开启锚点自动吸顶 | boolean | true |
| sticky-offset-top | 锚点自动吸顶时与顶部的距离 | number | 0 |
| highlight-color | 索引字符高亮颜色 | string | #ee0a24 |
teleport v3.0.19 | 指定索引栏挂载的节点 | string | Element | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| index | 索引字符 | number | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击索引栏的字符时触发 | index: number | string |
| change | 当前高亮的索引字符变化时触发 | index: number | string |
通过 ref 可以获取到 IndexBar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| scrollTo | 滚动到指定锚点 | index: number | string | - |
| 名称 | 说明 |
|---|---|
| default | 锚点位置显示内容，默认为索引字符 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-index-bar-sidebar-z-index | 2 | - |
| --van-index-bar-index-font-size | var(--van-font-size-xs) | - |
| --van-index-bar-index-line-height | var(--van-line-height-xs) | - |
| --van-index-bar-index-active-color | var(--van-danger-color) | - |
| --van-index-anchor-z-index | 1 | - |
| --van-index-anchor-padding | 0 var(--van-padding-md) | - |
| --van-index-anchor-text-color | var(--van-text-color) | - |
| --van-index-anchor-font-weight | var(--van-font-weight-bold) | - |
| --van-index-anchor-font-size | var(--van-font-size-md) | - |
| --van-index-anchor-line-height | 32px | - |
| --van-index-anchor-background-color | transparent | - |
| --van-index-anchor-sticky-text-color | var(--van-danger-color) | - |
| --van-index-anchor-sticky-background-color | var(--van-white) | - |
为页面提供导航功能，常用于页面顶部。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NavBar } from 'vant';const app = createApp();app.use(NavBar);<van-nav-bar title="标题" left-text="返回" right-text="按钮" left-arrow @click-left="onClickLeft" @click-right="onClickRight"/>import { Toast } from 'vant';export default { setup() { const onClickLeft = () => Toast('返回'); const onClickRight = () => Toast('按钮'); return { onClickLeft, onClickRight, }; },};通过插槽自定义导航栏两侧的内容。
<van-nav-bar title="标题" left-text="返回" left-arrow> <template #right> <van-icon name="search" size="18" /> </template></van-nav-bar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | '' |
| left-text | 左侧文案 | string | '' |
| right-text | 右侧文案 | string | '' |
| left-arrow | 是否显示左侧箭头 | boolean | false |
| border | 是否显示下边框 | boolean | true |
| fixed | 是否固定在顶部 | boolean | false |
| placeholder | 固定在顶部时，是否在标签位置生成一个等高的占位元素 | boolean | false |
| z-index | 导航栏 z-index | number | string | 1 |
| safe-area-inset-top | 是否开启顶部安全区适配 | boolean | false |
| 名称 | 说明 |
|---|---|
| title | 自定义标题 |
| left | 自定义左侧区域内容 |
| right | 自定义右侧区域内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-left | 点击左侧按钮时触发 | event: MouseEvent |
| click-right | 点击右侧按钮时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-nav-bar-height | 46px | - |
| --van-nav-bar-background-color | var(--van-white) | - |
| --van-nav-bar-arrow-size | 16px | - |
| --van-nav-bar-icon-color | var(--van-primary-color) | - |
| --van-nav-bar-text-color | var(--van-primary-color) | - |
| --van-nav-bar-title-font-size | var(--van-font-size-lg) | - |
| --van-nav-bar-title-text-color | var(--van-text-color) | - |
| --van-nav-bar-z-index | 1 | - |
数据量过多时，采用分页的形式将数据分隔，每次只加载一个页面。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Pagination } from 'vant';const app = createApp();app.use(Pagination);通过 v-model 来绑定当前页码。
<van-pagination v-model="currentPage" :total-items="24" :items-per-page="5" />import { ref } from 'vue';export default { setup() { const currentPage = ref(1); return { currentPage }; },};将 mode 设置为 simple 来切换到简单模式，此时分页器不会展示具体的页码按钮。
<van-pagination v-model="currentPage" :page-count="12" mode="simple" />设置 force-ellipses 后会展示省略号按钮，点击后可以快速跳转。
<van-pagination v-model="currentPage" :total-items="125" :show-page-size="3" force-ellipses/>通过 prev-text、next-text 等插槽来自定义分页按钮的内容。
<van-pagination v-model="currentPage" :total-items="50" :show-page-size="5"> <template #prev-text> <van-icon name="arrow-left" /> </template> <template #next-text> <van-icon name="arrow" /> </template> <template #page="{ text }">{{ text }}</template></van-pagination>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前页码 | number | - |
| mode | 显示模式，可选值为 simple | string | multi |
| prev-text | 上一页按钮文字 | string | 上一页 |
| next-text | 下一页按钮文字 | string | 下一页 |
| page-count | 总页数 | number | string | 根据页数计算 |
| total-items | 总记录数 | number | string | 0 |
| items-per-page | 每页记录数 | number | string | 10 |
| show-page-size | 显示的页码个数 | number | string | 5 |
| force-ellipses | 是否显示省略号 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 页码改变时触发 | - |
| 名称 | 描述 | 参数 |
|---|---|---|
| page | 自定义页码 | { number: number, text: string, active: boolean } |
| prev-text | 自定义上一页按钮文字 | - |
| next-text | 自定义下一页按钮文字 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-pagination-height | 40px | - |
| --van-pagination-font-size | var(--van-font-size-md) | - |
| --van-pagination-item-width | 36px | - |
| --van-pagination-item-default-color | var(--van-primary-color) | - |
| --van-pagination-item-disabled-color | var(--van-gray-7) | - |
| --van-pagination-item-disabled-background-color | var(--van-background-color) | - |
| --van-pagination-background-color | var(--van-white) | - |
| --van-pagination-desc-color | var(--van-gray-7) | - |
| --van-pagination-disabled-opacity | var(--van-disabled-opacity) | - |
垂直展示的导航栏，用于在不同的内容区域之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Sidebar, SidebarItem } from 'vant';const app = createApp();app.use(Sidebar);app.use(SidebarItem);通过 v-model 绑定当前选中项的索引。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" /></van-sidebar>import { ref } from 'vue';export default { setup() { const active = ref(0); return { active }; },};设置 dot 属性后，会在右上角展示一个小红点；设置 badge 属性后，会在右上角展示相应的徽标。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" dot /> <van-sidebar-item title="标签名称" badge="5" /> <van-sidebar-item title="标签名称" badge="20" /></van-sidebar>通过 disabled 属性禁用选项。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" disabled /> <van-sidebar-item title="标签名称" /></van-sidebar>设置 change 方法来监听切换导航项时的事件。
<van-sidebar v-model="active" @change="onChange"> <van-sidebar-item title="标签名 1" /> <van-sidebar-item title="标签名 2" /> <van-sidebar-item title="标签名 3" /></van-sidebar>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onChange = (index) => Toast(`标签名 ${index + 1}`); return { active, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前导航项的索引 | number | string | 0 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换导航项时触发 | index: number |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 内容 | string | '' |
| dot | 是否显示右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| disabled | 是否禁用该项 | boolean | false |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | index: number |
| Name | Description |
|---|---|
| title | 自定义标题 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-sidebar-width | 80px | - |
| --van-sidebar-font-size | var(--van-font-size-md) | - |
| --van-sidebar-line-height | var(--van-line-height-md) | - |
| --van-sidebar-text-color | var(--van-text-color) | - |
| --van-sidebar-disabled-text-color | var(--van-gray-5) | - |
| --van-sidebar-padding | 20px var(--van-padding-sm) | - |
| --van-sidebar-active-color | var(--van-active-color) | - |
| --van-sidebar-background-color | var(--van-background-color) | - |
| --van-sidebar-selected-font-weight | var(--van-font-weight-bold) | - |
| --van-sidebar-selected-text-color | var(--van-text-color) | - |
| --van-sidebar-selected-border-width | 4px | - |
| --van-sidebar-selected-border-height | 16px | - |
| --van-sidebar-selected-border-color | var(--van-danger-color) | - |
| --van-sidebar-selected-background-color | var(--van-white) | - |
选项卡组件，用于在不同的内容区域之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tab, Tabs } from 'vant';const app = createApp();app.use(Tab);app.use(Tabs);通过 v-model:active 绑定当前激活标签对应的索引值，默认情况下启用第一个标签。
<van-tabs v-model:active="active"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab> <van-tab title="标签 4">内容 4</van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const active = ref(2); return { active }; },};在标签指定 name 属性的情况下，v-model:active 的值为当前标签的 name（此时无法通过索引值来匹配标签）。
<van-tabs v-model:active="activeName"> <van-tab title="标签 1" name="a">内容 1</van-tab> <van-tab title="标签 2" name="b">内容 2</van-tab> <van-tab title="标签 3" name="c">内容 3</van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const activeName = ref('a'); return { activeName }; },};标签数量超过 5 个时，标签栏可以在水平方向上滚动，切换时会自动将当前标签居中。
<van-tabs v-model:active="active"> <van-tab v-for="index in 8" :title="'标签 ' + index"> 内容 {{ index }} </van-tab></van-tabs>设置 disabled 属性即可禁用标签。
<van-tabs v-model:active="active"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2" disabled>内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab></van-tabs>Tab 支持两种样式风格：line 和card，默认为 line 样式，可以通过 type 属性切换样式风格。
<van-tabs v-model:active="active" type="card"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab></van-tabs>点击标签页时，会触发 click-tab 事件。
<van-tabs v-model:active="active" @click-tab="onClickTab"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab></van-tabs>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onClickTab = ({ title }) => Toast(title); return { active, onClickTab, }; },};通过 sticky 属性可以开启粘性布局，粘性布局下，标签页滚动到顶部时会自动吸顶。
<van-tabs v-model:active="active" sticky> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 title 插槽可以自定义标签内容。
<van-tabs v-model:active="active"> <van-tab v-for="index in 2"> <template #title> <van-icon name="more-o" />选项 </template> 内容 {{ index }} </van-tab></van-tabs>通过 animated 属性可以开启切换标签内容时的转场动画。
<van-tabs v-model:active="active" animated> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 swipeable 属性可以开启滑动切换标签页。
<van-tabs v-model:active="active" swipeable> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 scrollspy 属性可以开启滚动导航模式，该模式下，内容将会平铺展示。
<van-tabs v-model:active="active" scrollspy sticky> <van-tab v-for="index in 8" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 before-change 属性可以在切换标签前执行特定的逻辑。
<van-tabs v-model:active="active" :before-change="beforeChange"> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const active = ref(0); const beforeChange = (index) => { // 返回 false 表示阻止此次切换 if (index === 1) { return false; } // 返回 Promise 来执行异步逻辑 return new Promise((resolve) => { // 在 resolve 函数中返回 true 或 false resolve(index !== 3); }); }; return { beforeChange, }; },};Tips: 通过手势滑动不会触发 before-change 属性。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:active | 绑定当前选中标签的标识符 | number | string | 0 |
| type | 样式风格类型，可选值为 card | string | line |
| color | 标签主题色 | string | #ee0a24 |
| background | 标签栏背景色 | string | white |
| duration | 动画时间，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| line-width | 底部条宽度，默认单位 px | number | string | 40px |
| line-height | 底部条高度，默认单位 px | number | string | 3px |
| animated | 是否开启切换标签内容时的转场动画 | boolean | false |
| border | 是否显示标签栏外边框，仅在 type="line" 时有效 | boolean | false |
| ellipsis | 是否省略过长的标题文字 | boolean | true |
| sticky | 是否使用粘性定位布局 | boolean | false |
| swipeable | 是否开启手势左右滑动切换 | boolean | false |
| lazy-render | 是否开启延迟渲染（首次切换到标签时才触发内容渲染） | boolean | true |
| scrollspy | 是否开启滚动导航 | boolean | false |
| offset-top | 粘性定位布局下与顶部的最小距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
| swipe-threshold | 滚动阈值，标签数量超过阈值且总宽度超过标签栏宽度时开始横向滚动 | number | string | 5 |
| title-active-color | 标题选中态颜色 | string | - |
| title-inactive-color | 标题默认态颜色 | string | - |
| before-change | 切换标签前的回调函数，返回 false 可阻止切换，支持返回 Promise | (name: number | string) => boolean | Promise<boolean> | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | - |
| disabled | 是否禁用标签 | boolean | false |
| dot | 是否在标题右上角显示小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| name | 标签名称，作为匹配的标识符 | number | string | 标签的索引值 |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| title-style | 自定义标题样式 | string | Array | object | - |
| title-class | 自定义标题类名 | string | Array | object | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
click-tab v3.1.4 | 点击标签时触发 | { name: string | number, title: string, event: MouseEvent, disabled: boolean } |
| change | 当前激活的标签改变时触发 | name: string | number, title: string |
| rendered | 标签内容首次渲染时触发（仅在开启延迟渲染后触发） | name: string | number, title: string |
| scroll | 滚动时触发，仅在 sticky 模式下生效 | { scrollTop: number, isFixed: boolean } |
提示：click 和 disabled 事件已废弃，请使用 click-tab 事件代替。
通过 ref 可以获取到 Tabs 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| resize | 外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘 | - | - |
| scrollTo | 滚动到指定的标签页，在滚动导航模式下可用 | name: string | number | - |
通过 TabsInstance 获取 Tabs 实例的类型定义。
import { ref } from 'vue';import type { TabsInstance } from 'vant';const tabsRef = ref<TabsInstance>();tabsRef.value?.scrollTo(0);| 名称 | 说明 |
|---|---|
| nav-left | 标签栏左侧内容 |
| nav-right | 标签栏右侧内容 |
nav-bottom v3.1.1 | 标签栏下方内容 |
| 名称 | 说明 |
|---|---|
| default | 标签页内容 |
| title | 自定义标题 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tab-text-color | var(--van-gray-7) | - |
| --van-tab-active-text-color | var(--van-text-color) | - |
| --van-tab-disabled-text-color | var(--van-gray-5) | - |
| --van-tab-font-size | var(--van-font-size-md) | - |
| --van-tab-line-height | var(--van-line-height-md) | - |
| --van-tabs-default-color | var(--van-danger-color) | - |
| --van-tabs-line-height | 44px | - |
| --van-tabs-card-height | 30px | - |
| --van-tabs-nav-background-color | var(--van-white) | - |
| --van-tabs-bottom-bar-width | 40px | - |
| --van-tabs-bottom-bar-height | 3px | - |
| --van-tabs-bottom-bar-color | var(--van-danger-color) | - |
Tabs 组件在挂载时，会获取自身的宽度，并计算出底部条的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法展示底部条位置。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-tabs v-show="show" /><!-- After --><van-tabs v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-tabs v-show="show" ref="tabs" />this.$refs.tabs.resize();底部导航栏，用于在不同页面之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tabbar, TabbarItem } from 'vant';const app = createApp();app.use(Tabbar);app.use(TabbarItem);v-model 默认绑定选中标签的索引值，通过修改 v-model 即可切换选中的标签。
<van-tabbar v-model="active"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="friends-o">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref(0); return { active }; },};在标签指定 name 属性的情况下，v-model 的值为当前标签的 name。
<van-tabbar v-model="active"> <van-tabbar-item name="home" icon="home-o">标签</van-tabbar-item> <van-tabbar-item name="search" icon="search">标签</van-tabbar-item> <van-tabbar-item name="friends" icon="friends-o">标签</van-tabbar-item> <van-tabbar-item name="setting" icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref('home'); return { active }; },};设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-tabbar v-model="active"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search" dot>标签</van-tabbar-item> <van-tabbar-item icon="friends-o" badge="5">标签</van-tabbar-item> <van-tabbar-item icon="setting-o" badge="20">标签</van-tabbar-item></van-tabbar>通过 icon 插槽自定义图标，可以通过 slot-scope 判断标签是否选中。
<van-tabbar v-model="active"> <van-tabbar-item badge="3"> <span>自定义</span> <template #icon="props"> <img :src="props.active ? icon.active : icon.inactive" /> </template> </van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref(0); const icon = { active: 'https://img.yzcdn.cn/vant/user-active.png', inactive: 'https://img.yzcdn.cn/vant/user-inactive.png', }; return { icon, active, }; },};通过 active-color 属性设置选中标签的颜色，通过 inactive-color 属性设置未选中标签的颜色。
<van-tabbar v-model="active" active-color="#ee0a24" inactive-color="#000"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="friends-o">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>通过 change 事件来监听选中标签的变化。
<van-tabbar v-model="active" @change="onChange"> <van-tabbar-item icon="home-o">标签 1</van-tabbar-item> <van-tabbar-item icon="search">标签 2</van-tabbar-item> <van-tabbar-item icon="friends-o">标签 3</van-tabbar-item> <van-tabbar-item icon="setting-o">标签 4</van-tabbar-item></van-tabbar>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onChange = (index) => Toast(`标签 ${index}`); return { icon, onChange, }; },};标签栏支持路由模式，用于搭配 vue-router 使用。路由模式下会匹配页面路径和标签的 to 属性，并自动选中对应的标签。
<router-view /><van-tabbar route> <van-tabbar-item replace to="/home" icon="home-o">标签</van-tabbar-item> <van-tabbar-item replace to="/search" icon="search">标签</van-tabbar-item></van-tabbar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中标签的名称或索引值 | number | string | 0 |
| fixed | 是否固定在底部 | boolean | true |
| border | 是否显示外边框 | boolean | true |
| z-index | 元素 z-index | number | string | 1 |
| active-color | 选中标签的颜色 | string | #1989fa |
| inactive-color | 未选中标签的颜色 | string | #7d7e80 |
| route | 是否开启路由模式 | boolean | false |
| placeholder | 固定在底部时，是否在标签位置生成一个等高的占位元素 | boolean | false |
| safe-area-inset-bottom | 是否开启底部安全区适配，设置 fixed 时默认开启 | boolean | false |
| before-change | 切换标签前的回调函数，返回 false 可阻止切换，支持返回 Promise | (name: number | string) => boolean | Promise<boolean> | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换标签时触发 | active: number | string |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标签名称，作为匹配的标识符 | number | string | 当前标签的索引值 |
| icon | 图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 名称 | 说明 | 参数 |
|---|---|---|
| icon | 自定义图标 | active: boolean |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tabbar-height | 50px | - |
| --van-tabbar-z-index | 1 | - |
| --van-tabbar-background-color | var(--van-white) | - |
| --van-tabbar-item-font-size | var(--van-font-size-sm) | - |
| --van-tabbar-item-text-color | var(--van-gray-7) | - |
| --van-tabbar-item-active-color | var(--van-primary-color) | - |
| --van-tabbar-item-active-background-color | var(--van-white) | - |
| --van-tabbar-item-line-height | 1 | - |
| --van-tabbar-item-icon-size | 22px | - |
| --van-tabbar-item-icon-margin-bottom | var(--van-padding-base) | - |
用于从一组相关联的数据集合中进行选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { TreeSelect } from 'vant';const app = createApp();app.use(TreeSelect);item 为分类显示所需的数据，数据格式见下方示例。main-active-index 表示左侧高亮选项的索引，active-id 表示右侧高亮选项的 id。
<van-tree-select v-model:active-id="state.activeId" v-model:main-active-index="state.activeIndex" :items="items"/>import { reactive } from 'vue';export default { setup() { const state = reactive({ activeId: 1, activeIndex: 0, }); const items = [ { text: '浙江', children: [ { text: '杭州', id: 1 }, { text: '温州', id: 2 }, ], }, { text: '江苏', children: [ { text: '南京', id: 5 }, { text: '无锡', id: 6 }, ], }, ]; return { state, items, }; },};active-id 为数组格式时，可以选中多个右侧选项。
<van-tree-select v-model:active-id="state.activeIds" v-model:main-active-index="state.activeIndex" :items="items"/>import { reactive } from 'vue';export default { setup() { const state = reactive({ activeId: [1, 2], activeIndex: 0, }); const items = [ { text: '浙江', children: [ { text: '杭州', id: 1 }, { text: '温州', id: 2 }, ], }, { text: '江苏', children: [ { text: '南京', id: 5 }, { text: '无锡', id: 6 }, ], }, ]; return { state, items, }; },};通过 content 插槽可以自定义右侧区域的内容。
<van-tree-select v-model:main-active-index="activeIndex" height="55vw" :items="items"> <template #content> <van-image v-if="activeIndex === 0" src="https://img.yzcdn.cn/vant/apple-1.jpg" rel="external nofollow" /> <van-image v-if="activeIndex === 1" src="https://img.yzcdn.cn/vant/apple-2.jpg" rel="external nofollow" /> </template></van-tree-select>import { ref } from 'vue';export default { setup() { const activeIndex = ref(0); return { activeIndex, items: [{ text: '分组 1' }, { text: '分组 2' }], }; },};设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-tree-select v-model:main-active-index="activeIndex" height="55vw" :items="items"/>import { ref } from 'vue';export default { setup() { const activeIndex = ref(0); return { activeIndex, items: [ { text: '浙江', children: [], dot: true }, { text: '江苏', children: [], badge: 5 }, ], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 分类显示所需的数据 | Item[] | [] |
| height | 高度，默认单位为px | number | string | 300 |
| main-active-index | 左侧选中项的索引 | number | string | 0 |
| active-id | 右侧选中项的 id，支持传入数组 | number | string | (number | string)[] | 0 |
| max | 右侧项最大选中个数 | number | string | Infinity |
| selected-icon | 自定义右侧栏选中状态的图标 | string | success |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-nav | 点击左侧导航时触发 | index：被点击的导航的索引 |
| click-item | 点击右侧选择项时触发 | data: 该点击项的数据 |
| 名称 | 说明 |
|---|---|
| content | 自定义右侧区域内容 |
items 整体为一个数组，数组内包含一系列描述分类的对象，每个分类里，text表示当前分类的名称，children表示分类里的可选项。
[ { // 导航名称 text: '所有城市', // 导航名称右上角徽标 badge: 3, // 是否在导航名称右上角显示小红点 dot: true, // 导航节点额外类名 className: 'my-class', // 该导航下所有的可选项 children: [ { // 名称 text: '温州', // id，作为匹配选中状态的标识符 id: 1, // 禁用选项 disabled: true, }, { text: '杭州', id: 2, }, ], },];组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tree-select-font-size | var(--van-font-size-md) | - |
| --van-tree-select-nav-background-color | var(--van-background-color) | - |
| --van-tree-select-content-background-color | var(--van-white) | - |
| --van-tree-select-nav-item-padding | 14px var(--van-padding-sm) | - |
| --van-tree-select-item-height | 48px | - |
| --van-tree-select-item-active-color | var(--van-danger-color) | - |
| --van-tree-select-item-disabled-color | var(--van-gray-5) | - |
| --van-tree-select-item-selected-size | 16px | - |
收货地址编辑组件，用于新建、更新、删除收货地址。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { AddressEdit } from 'vant';const app = createApp();app.use(AddressEdit);<van-address-edit :area-list="areaList" show-postal show-delete show-set-default show-search-result :search-result="searchResult" :area-columns-placeholder="['请选择', '请选择', '请选择']" @save="onSave" @delete="onDelete" @change-detail="onChangeDetail"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const searchResult = ref([]); const onSave = () => Toast('save'); const onDelete = () => Toast('delete'); const onChangeDetail = (val) => { if (val) { searchResult.value = [ { name: '黄龙万科中心', address: '杭州市西湖区', }, ]; } else { searchResult.value = []; } }; return { onSave, onDelete, areaList, searchResult, onChangeDetail, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| area-list | 地区列表 | object | - |
| area-columns-placeholder | 地区选择列占位提示文字 | string[] | [] |
| area-placeholder | 地区输入框占位提示文字 | string | 选择省 / 市 / 区 |
| address-info | 收货人信息初始值 | AddressInfo | {} |
| search-result | 详细地址搜索结果 | SearchResult[] | [] |
| show-postal | 是否显示邮政编码 | boolean | false |
| show-delete | 是否显示删除按钮 | boolean | false |
| show-set-default | 是否显示默认地址栏 | boolean | false |
| show-search-result | 是否显示搜索结果 | boolean | false |
| show-area | 是否显示地区 | boolean | true |
| show-detail | 是否显示详细地址 | boolean | true |
| disable-area | 是否禁用地区选择 | boolean | false |
| save-button-text | 保存按钮文字 | string | 保存 |
| delete-button-text | 删除按钮文字 | string | 删除 |
| detail-rows | 详细地址输入框行数 | number | string | 1 |
| detail-maxlength | 详细地址最大长度 | number | string | 200 |
| is-saving | 是否显示保存按钮加载动画 | boolean | false |
| is-deleting | 是否显示删除按钮加载动画 | boolean | false |
| tel-validator | 手机号格式校验函数 | string => boolean | - |
| tel-maxlength | 手机号最大长度 | number | string | - |
| postal-validator | 邮政编码格式校验函数 | string => boolean | - |
| validator | 自定义校验函数 | (key, val) => string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| save | 点击保存按钮时触发 | content：表单内容 |
| focus | 输入框聚焦时触发 | key: 聚焦的输入框对应的 key |
| delete | 确认删除地址时触发 | content：表单内容 |
| cancel-delete | 取消删除地址时触发 | content：表单内容 |
| select-search | 选中搜索结果时触发 | value: 搜索结果 |
| click-area | 点击收件地区时触发 | - |
| change-area | 修改收件地区时触发 | values: 地区信息 |
| change-detail | 修改详细地址时触发 | value: 详细地址内容 |
| change-default | 切换是否使用默认地址时触发 | value: 是否选中 |
| 名称 | 说明 |
|---|---|
| default | 在邮政编码下方插入内容 |
通过 ref 可以获取到 AddressEdit 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| setAddressDetail | 设置详细地址 | addressDetail: string | - |
通过 AddressEditInstance 获取 AddressEdit 实例的类型定义。
import { ref } from 'vue';import type { AddressEditInstance } from 'vant';const addressEditRef = ref<AddressEditInstance>();addressEditRef.value?.setAddressDetail('');注意：AddressInfo 仅作为初始值传入，表单最终内容可以在 save 事件中获取。
| key | 说明 | 类型 |
|---|---|---|
| name | 收货人姓名 | string |
| tel | 收货人手机号 | string |
| province | 省份 | string |
| city | 城市 | string |
| county | 区县 | string |
| addressDetail | 详细地址 | string |
| areaCode | 地区编码，通过 省市区选择 获取（必填） | string |
| postalCode | 邮政编码 | string |
| isDefault | 是否为默认地址 | boolean |
| key | 说明 | 类型 |
|---|---|---|
| name | 地名 | string |
| address | 详细地址 | string |
请参考 Area 组件。
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-address-edit-padding | var(--van-padding-sm) | - |
| --van-address-edit-buttons-padding | var(--van-padding-xl) var(--van-padding-base) | - |
| --van-address-edit-button-margin-bottom | var(--van-padding-sm) | - |
| --van-address-edit-button-font-size | var(--van-font-size-lg) | - |
| --van-address-edit-detail-finish-color | var(--van-primary-color) | - |
| --van-address-edit-detail-finish-font-size | var(--van-font-size-sm) | - |
展示收货地址列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { AddressList } from 'vant';const app = createApp();app.use(AddressList);<van-address-list v-model="chosenAddressId" :list="list" :disabled-list="disabledList" disabled-text="以下地址超出配送范围" default-tag-text="默认" @add="onAdd" @edit="onEdit"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const chosenAddressId = ref('1'); const list = [ { id: '1', name: '张三', tel: '13000000000', address: '浙江省杭州市西湖区文三路 138 号东方通信大厦 7 楼 501 室', isDefault: true, }, { id: '2', name: '李四', tel: '1310000000', address: '浙江省杭州市拱墅区莫干山路 50 号', }, ]; const disabledList = [ { id: '3', name: '王五', tel: '1320000000', address: '浙江省杭州市滨江区江南大道 15 号', }, ]; const onAdd = () => Toast('新增地址'); const onEdit = (item, index) => Toast('编辑地址:' + index); return { list, onAdd, onEdit, disabledList, chosenAddressId, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中地址的 id | string | - |
| list | 地址列表 | Address[] | [] |
| disabled-list | 不可配送地址列表 | Address[] | [] |
| disabled-text | 不可配送提示文案 | string | - |
| switchable | 是否允许切换地址 | boolean | true |
| add-button-text | 底部按钮文字 | string | 新增地址 |
| default-tag-text | 默认地址标签文字 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| add | 点击新增按钮时触发 | - |
| edit | 点击编辑按钮时触发 | item: Address, index: number |
| select | 切换选中的地址时触发 | item: Address, index: number |
| edit-disabled | 编辑不可配送的地址时触发 | item: Address, index: number |
| select-disabled | 选中不可配送的地址时触发 | item: Address, index: number |
| click-item | 点击任意地址时触发 | item: Address, index: number |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 每条地址的唯一标识 | number | string |
| name | 收货人姓名 | string |
| tel | 收货人手机号 | number | string |
| address | 收货地址 | string |
| isDefault | 是否为默认地址 | boolean |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 在列表下方插入内容 | - |
| top | 在顶部插入内容 | - |
| item-bottom | 在列表项底部插入内容 | item: Address |
tag v3.0.9 | 自定义列表项标签内容 | item: Address |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-address-list-padding | var(--van-padding-sm) var(--van-padding-sm) 80px | - |
| --van-address-list-disabled-text-color | var(--van-gray-6) | - |
| --van-address-list-disabled-text-padding | var(--van-padding-base) * 5 0 var(--van-padding-md) | - |
| --van-address-list-disabled-text-font-size | var(--van-font-size-md) | - |
| --van-address-list-disabled-text-line-height | var(--van-line-height-md) | - |
| --van-address-list-add-button-z-index | 999 | - |
| --van-address-list-item-padding | var(--van-padding-sm) | - |
| --van-address-list-item-text-color | var(--van-text-color) | - |
| --van-address-list-item-disabled-text-color | var(--van-gray-5) | - |
| --van-address-list-item-font-size | 13px | - |
| --van-address-list-item-line-height | var(--van-line-height-sm) | - |
| --van-address-list-item-radio-icon-color | var(--van-danger-color) | - |
| --van-address-list-edit-icon-size | 20px | - |
省市区三级联动选择，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Area } from 'vant';const app = createApp();app.use(Area);初始化省市区组件时，需要通过 area-list 属性传入省市区数据。
<van-area title="标题" :area-list="areaList" />areaList 为对象结构，包含 province_list、city_list、county_list 三个 key。
每项以地区码作为 key，省市区名字作为 value。地区码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。比如北京的地区码为 11，以 0 补足 6 位，为 110000。
示例数据如下：
const areaList = { province_list: { 110000: '北京市', 120000: '天津市', }, city_list: { 110100: '北京市', 120100: '天津市', }, county_list: { 110101: '东城区', 110102: '西城区', // .... },};Vant 官方提供了一份默认的省市区数据，可以通过 @vant/area-data 引入：
yarn add @vant/area-dataimport { areaList } from '@vant/area-data';export default { setup() { return { areaList }; },};如果想选中某个省市区，需要传入一个 value 属性，绑定对应的地区码。
<van-area title="标题" :area-list="areaList" value="110101" />可以通过 columns-num 属性配置省市区显示的列数，默认情况下会显示省市区，当你设置为 2，则只会显示省市选择。
<van-area title="标题" :area-list="areaList" :columns-num="2" />可以通过 columns-placeholder 属性配置每一列的占位提示文字。
<van-area title="标题" :area-list="areaList" :columns-placeholder="['请选择', '请选择', '请选择']"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 当前选中项对应的地区码 | string | - |
| title | 顶部栏标题 | string | - |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| area-list | 省市区数据，格式见下方 | object | - |
| columns-placeholder | 列占位提示文字 | string[] | [] |
| loading | 是否显示加载状态 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法切换选项 | boolean | false |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| columns-num | 显示列数，3-省市区，2-省市，1-省 | number | string | 3 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位 ms | number | string | 1000 |
| is-oversea-code | 根据地区码校验海外地址，海外地址会划分至单独的分类 | () => boolean | - |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击右上方完成按钮 | result: ConfirmResult |
| cancel | 点击取消按钮时 | - |
| change | 选项改变时触发 | 所有列选中值，当前列对应的索引 |
confirm 事件返回的数据整体为一个数组，数组每一项对应一列选项中被选中的数据。
[ { code: '110000', name: '北京市', }, { code: '110100', name: '北京市', }, { code: '110101', name: '东城区', },];| 名称 | 说明 | 参数 |
|---|---|---|
toolbar v3.1.2 | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
confirm v3.1.2 | 自定义确认按钮内容 | - |
cancel v3.1.2 | 自定义取消按钮内容 | - |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
通过 ref 可以获取到 Area 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| reset | 根据地区码重置所有选项，若不传地区码，则重置到第一项 | code?: string | - |
通过 AreaInstance 获取 Area 实例的类型定义。
import { ref } from 'vue';import type { AreaInstance } from 'vant';const areaRef = ref<AreaInstance>();areaRef.value?.reset();参见桌面端适配。
商品卡片，用于展示商品的图片、价格等信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Card } from 'vant';const app = createApp();app.use(Card);<van-card num="2" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg"/>通过 origin-price 设置商品原价，通过 tag 设置商品左上角标签。
<van-card num="2" tag="标签" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg" origin-price="10.00"/>Card 组件提供了多个插槽，可以灵活地自定义内容。
<van-card num="2" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg"> <template #tags> <van-tag plain type="danger">标签</van-tag> <van-tag plain type="danger">标签</van-tag> </template> <template #footer> <van-button size="mini">按钮</van-button> <van-button size="mini">按钮</van-button> </template></van-card>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| thumb | 左侧图片 URL | string | - |
| title | 标题 | string | - |
| desc | 描述 | string | - |
| tag | 图片角标 | string | - |
| num | 商品数量 | number | string | - |
| price | 商品价格 | number | string | - |
| origin-price | 商品划线原价 | number | string | - |
| centered | 内容是否垂直居中 | boolean | false |
| currency | 货币符号 | string | ¥ |
| thumb-link | 点击左侧图片后跳转的链接地址 | string | - |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| click-thumb | 点击自定义图片时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| title | 自定义标题 |
| desc | 自定义描述 |
| num | 自定义数量 |
| price | 自定义价格 |
| origin-price | 自定义商品原价 |
| price-top | 自定义价格上方区域 |
| bottom | 自定义价格下方区域 |
| thumb | 自定义图片 |
| tag | 自定义图片角标 |
| tags | 自定义描述下方标签区域 |
| footer | 自定义右下角内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-card-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-card-font-size | var(--van-font-size-sm) | - |
| --van-card-text-color | var(--van-text-color) | - |
| --van-card-background-color | var(--van-background-color-light) | - |
| --van-card-thumb-size | 88px | - |
| --van-card-thumb-border-radius | var(--van-border-radius-lg) | - |
| --van-card-title-line-height | 16px | - |
| --van-card-desc-color | var(--van-gray-7) | - |
| --van-card-desc-line-height | var(--van-line-height-md) | - |
| --van-card-price-color | var(--van-gray-8) | - |
| --van-card-origin-price-color | var(--van-gray-6) | - |
| --van-card-num-color | var(--van-gray-6) | - |
| --van-card-origin-price-font-size | var(--van-font-size-xs) | - |
| --van-card-price-font-size | var(--van-font-size-sm) | - |
| --van-card-price-integer-font-size | var(--van-font-size-lg) | - |
| --van-card-price-font-family | var(--van-price-integer-font-family) | - |
以卡片的形式展示联系人信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactCard } from 'vant';const app = createApp();app.use(ContactCard);<van-contact-card type="add" @click="onAdd" />import { Toast } from 'vant';export default { setup() { const onAdd = () => Toast('新增'); return { onAdd, }; },};<van-contact-card type="edit" :name="currentContact.name" :tel="currentContact.tel" @click="onEdit"/>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const currentContact = reactive({ name: '张三', tel: '13000000000', }); const onEdit = () => Toast('edit'); return { onEdit, currentContact, }; },};<van-contact-card type="edit" name="张三" tel="13000000000" :editable="false" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 卡片类型，可选值为 edit | string | add |
| name | 联系人姓名 | string | - |
| tel | 联系人手机号 | string | - |
| add-text | 添加时的文案提示 | string | 添加联系人 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-card-padding | var(--van-padding-md) | - |
| --van-contact-card-add-icon-size | 40px | - |
| --van-contact-card-add-icon-color | var(--van-primary-color) | - |
| --van-contact-card-value-line-height | var(--van-line-height-md) | - |
编辑并保存联系人信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactEdit } from 'vant';const app = createApp();app.use(ContactEdit);<van-contact-edit is-edit show-set-default :contact-info="editingContact" set-default-label="设为默认联系人" @save="onSave" @delete="onDelete"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const editingContact = ref({}); const onSave = (contactInfo) => Toast('保存'); const onDelete = (contactInfo) => Toast('删除'); return { onSave, onDelete, editingContact, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| contact-info | 联系人信息 | Contact | {} |
| is-edit | 是否为编辑联系人 | boolean | false |
| is-saving | 是否显示保存按钮加载动画 | boolean | false |
| is-deleting | 是否显示删除按钮加载动画 | boolean | false |
| tel-validator | 手机号格式校验函数 | (tel: string) => boolean | - |
| show-set-default | 是否显示默认联系人栏 | boolean | false |
| set-default-label | 默认联系人栏文案 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| save | 点击保存按钮时触发 | content：表单内容 |
| delete | 点击删除按钮时触发 | content：表单内容 |
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 联系人姓名 | string |
| tel | 联系人手机号 | number | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-edit-padding | var(--van-padding-md) | - |
| --van-contact-edit-fields-radius | var(--van-border-radius-md) | - |
| --van-contact-edit-buttons-padding | var(--van-padding-xl) 0 | - |
| --van-contact-edit-button-margin-bottom | var(--van-padding-sm) | - |
| --van-contact-edit-button-font-size | var(--van-font-size-lg) | - |
| --van-contact-edit-field-label-width | 4.1em | - |
展示联系人列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactList } from 'vant';const app = createApp();app.use(ContactList);<van-contact-list v-model="state.chosenContactId" :list="state.list" default-tag-text="默认" @add="onAdd" @edit="onEdit" @select="onSelect"/>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ chosenContactId: '1', list: [ { id: '1', name: '张三', tel: '13000000000', isDefault: true, }, { id: '2', name: '李四', tel: '1310000000', }, ], }); const onAdd = () => Toast('新增'); const onEdit = (contact) => Toast('编辑' + contact.id); const onSelect = (contact) => Toast('选择' + contact.id); return { state, onAdd, onEdit, onSelect, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中联系人的 id | number | string | - |
| list | 联系人列表 | Contact[] | [] |
| add-text | 新建按钮文案 | string | 新建联系人 |
| default-tag-text | 默认联系人标签文案 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| add | 点击新增按钮时触发 | - |
| edit | 点击编辑按钮时触发 | contact: Contact，index: number |
| select | 切换选中的联系人时触发 | contact: Contact，index: number |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 每位联系人的唯一标识 | number | string |
| name | 联系人姓名 | string |
| tel | 联系人手机号 | number | string |
| isDefault | 是否为默认联系人 | boolean |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-list-edit-icon-size | 16px | - |
| --van-contact-list-add-button-z-index | 999 | - |
| --van-contact-list-item-padding | var(--van-padding-md) | - |
| --van-contact-list-item-radio-icon-color | var(--van-danger-color) | - |
用于优惠券的兑换和选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { CouponCell, CouponList } from 'vant';const app = createApp();app.use(CouponCell);app.use(CouponList);<!-- 优惠券单元格 --><van-coupon-cell :coupons="state.coupons" :chosen-coupon="state.chosenCoupon" @click="state.showList = true"/><!-- 优惠券列表 --><van-popup v-model="state.showList" round position="bottom" style="height: 90%; padding-top: 4px;"> <van-coupon-list :coupons="state.coupons" :chosen-coupon="state.chosenCoupon" :disabled-coupons="disabledCoupons" @change="onChange" @exchange="onExchange" /></van-popup>import { reactive } from 'vue';const coupon = { available: 1, condition: '无使用门槛
最多优惠12元', reason: '', value: 150, name: '优惠券名称', startAt: 1489104000, endAt: 1514592000, valueDesc: '1.5', unitDesc: '元',};export default { setup() { const state = reactive({ coupons: [coupon], showList: false, chosenCoupon: -1, }); const onChange = (index) => { state.showList = false; state.chosenCoupon = index; }; const onExchange = (code) => { state.coupons.push(coupon); }; return { state, onChange, onExchange, disabledCoupons: [coupon], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 单元格标题 | string | 优惠券 |
| chosen-coupon | 当前选中优惠券的索引 | number | string | -1 |
| coupons | 可用优惠券列表 | Coupon[] | [] |
| editable | 能否切换优惠券 | boolean | true |
| border | 是否显示内边框 | boolean | true |
| currency | 货币符号 | string | ¥ |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:code | 当前输入的兑换码 | string | - |
| chosen-coupon | 当前选中优惠券的索引 | number | -1 |
| coupons | 可用优惠券列表 | Coupon[] | [] |
| disabled-coupons | 不可用优惠券列表 | Coupon[] | [] |
| enabled-title | 可用优惠券列表标题 | string | 可使用优惠券 |
| disabled-title | 不可用优惠券列表标题 | string | 不可使用优惠券 |
| exchange-button-text | 兑换按钮文字 | string | 兑换 |
| exchange-button-loading | 是否显示兑换按钮加载动画 | boolean | false |
| exchange-button-disabled | 是否禁用兑换按钮 | boolean | false |
| exchange-min-length | 兑换码最小长度 | number | 1 |
| displayed-coupon-index | 滚动至特定优惠券位置 | number | - |
| show-close-button | 是否显示列表底部按钮 | boolean | true |
| close-button-text | 列表底部按钮文字 | string | 不使用优惠 |
| input-placeholder | 输入框文字提示 | string | 请输入优惠码 |
| show-exchange-bar | 是否展示兑换栏 | boolean | true |
| currency | 货币符号 | string | ¥ |
| empty-image | 列表为空时的占位图 | string | https://img.yzcdn.cn/vant/coupon-empty.png |
| show-count | 是否展示可用 / 不可用数量 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 优惠券切换回调 | index, 选中优惠券的索引 |
| exchange | 兑换优惠券回调 | code, 兑换码 |
| 名称 | 说明 |
|---|---|
list-footer v3.0.18 | 优惠券列表底部 |
disabled-list-footer v3.0.18 | 不可用优惠券列表底部 |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 优惠券 id | string |
| name | 优惠券名称 | string |
| condition | 满减条件 | string |
| startAt | 卡有效开始时间 (时间戳, 单位秒) | number |
| endAt | 卡失效日期 (时间戳, 单位秒) | number |
| description | 描述信息，优惠券可用时展示 | string |
| reason | 不可用原因，优惠券不可用时展示 | string |
| value | 折扣券优惠金额，单位分 | number |
| valueDesc | 折扣券优惠金额文案 | string |
| unitDesc | 单位文案 | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-coupon-margin | 0 var(--van-padding-sm) var(--van-padding-sm) | - |
| --van-coupon-content-height | 84px | - |
| --van-coupon-content-padding | 14px 0 | - |
| --van-coupon-background-color | var(--van-white) | - |
| --van-coupon-active-background-color | var(--van-active-color) | - |
| --van-coupon-border-radius | var(--van-border-radius-lg) | - |
| --van-coupon-box-shadow | 0 0 4px rgba(0, 0, 0, 0.1) | - |
| --van-coupon-head-width | 96px | - |
| --van-coupon-amount-color | var(--van-danger-color) | - |
| --van-coupon-amount-font-size | 30px | - |
| --van-coupon-currency-font-size | 40% | - |
| --van-coupon-name-font-size | var(--van-font-size-md) | - |
| --van-coupon-disabled-text-color | var(--van-gray-6) | - |
| --van-coupon-description-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-coupon-description-border-color | var(--van-border-color) | - |
| --van-coupon-corner-checkbox-icon-color | var(--van-danger-color) | - |
| --van-coupon-list-background-color | var(--van-background-color) | - |
| --van-coupon-list-field-padding | 5px 0 5px var(--van-padding-md) | - |
| --van-coupon-list-exchange-button-height | 32px | - |
| --van-coupon-list-close-button-height | 40px | - |
| --van-coupon-list-empty-image-size | 200px | - |
| --van-coupon-list-empty-tip-color | var(--van-gray-6) | - |
| --van-coupon-list-empty-tip-font-size | var(--van-font-size-md) | - |
| --van-coupon-list-empty-tip-line-height | var(--van-line-height-md) | - |
| --van-coupon-cell-selected-text-color | var(--van-text-color) | - |
用于展示订单金额与提交订单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { SubmitBar } from 'vant';const app = createApp();app.use(SubmitBar);<van-submit-bar :price="3050" button-text="提交订单" @submit="onSubmit" />import { Toast } from 'vant';export default { setup() { const onSubmit = () => Toast('点击按钮'); return { onSubmit, }; },};禁用状态下不会触发 submit 事件。
<van-submit-bar disabled :price="3050" button-text="提交订单" tip="你的收货地址不支持同城送, 我们已为你推荐快递" tip-icon="info-o" @submit="onSubmit"/>加载状态下不会触发 submit 事件。
<van-submit-bar loading :price="3050" button-text="提交订单" @submit="onSubmit"/>通过插槽插入自定义内容。
<van-submit-bar :price="3050" button-text="提交订单" @submit="onSubmit"> <van-checkbox v-model="checked">全选</van-checkbox> <template #tip> 你的收货地址不支持同城送, <span @click="onClickLink">修改地址</span> </template></van-submit-bar>import { Toast } from 'vant';export default { setup() { const onSubmit = () => Toast('点击按钮'); const onClickLink = () => Toast('修改地址'); return { onSubmit, onClickLink, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| price | 金额（单位分） | number | - |
| decimal-length | 金额小数点位数 | number | string | 2 |
| label | 金额左侧文案 | string | 合计： |
| suffix-label | 金额右侧文案 | string | - |
| text-align | 金额文案对齐方向，可选值为 left | string | right |
| button-text | 按钮文字 | string | - |
| button-type | 按钮类型 | string | danger |
| button-color | 自定义按钮颜色 | string | - |
| tip | 在订单栏上方的提示文案 | string | - |
| tip-icon | 提示文案左侧的图标名称或图片链接 | string | - |
| currency | 货币符号 | string | ¥ |
| disabled | 是否禁用按钮 | boolean | false |
| loading | 是否显示将按钮显示为加载中状态 | boolean | false |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| submit | 按钮点击事件回调 | - |
| 名称 | 说明 |
|---|---|
| default | 自定义订单栏左侧内容 |
| button | 自定义按钮 |
| top | 自定义订单栏上方内容 |
| tip | 提示文案中的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-submit-bar-height | 50px | - |
| --van-submit-bar-z-index | 100 | - |
| --van-submit-bar-background-color | var(--van-white) | - |
| --van-submit-bar-button-width | 110px | - |
| --van-submit-bar-price-color | var(--van-danger-color) | - |
| --van-submit-bar-text-color | var(--van-text-color) | - |
| --van-submit-bar-text-font-size | var(--van-font-size-md) | - |
| --van-submit-bar-tip-padding | var(--van-padding-xs) var(--van-padding-sm) | - |
| --van-submit-bar-tip-font-size | var(--van-font-size-sm) | - |
| --van-submit-bar-tip-line-height | 1.5 | - |
| --van-submit-bar-tip-color | #f56723 | - |
| --van-submit-bar-tip-background-color | #fff7cc | - |
| --van-submit-bar-tip-icon-size | 12px | - |
| --van-submit-bar-button-height | 40px | - |
| --van-submit-bar-padding | 0 var(--van-padding-md) | - |
| --van-submit-bar-price-font-size | var(--van-font-size-sm) | - |
| --van-submit-bar-price-integer-font-size | 20px | - |
| --van-submit-bar-price-font-family | var(--van-price-integer-font-family) | - |
Vant 内置了一系列的组合式 API，对于安装了 vant 的项目，可以直接使用这些 API 进行开发。
下面是一个 Vant 组合式 API 的用法示例，我们从 @vant/use 这个包中引入 useWindowSize 方法，然后进行调用，即可获取到当前 Window 的宽度和高度。
import { useWindowSize } from '@vant/use';const { width, height } = useWindowSize();console.log(width.value); // -> 窗口宽度console.log(height.value); // -> 窗口高度下面是 Vant 对外提供的所有组合式 API，点击名称可以查看详细介绍：
| 名称 | 描述 |
|---|---|
| useClickAway | 监听点击元素外部的事件 |
| useCountDown | 提供倒计时管理能力 |
| useEventListener | 方便地进行事件绑定 |
| usePageVisibility | 获取页面的可见状态 |
| useRect | 获取元素的大小及其相对于视口的位置 |
| useRelation | 建立父子组件之间的关联关系 |
| useScrollParent | 获取元素最近的可滚动父元素 |
| useToggle | 用于在布尔值之间进行切换 |
| useWindowSize | 获取浏览器窗口的视口宽度和高度 |
用于在 true 和 false 之间进行切换。
import { useToggle } from '@vant/use';export default { setup() { const [state, toggle] = useToggle(); toggle(true); console.log(state.value); // -> true toggle(false); console.log(state.value); // -> false toggle(); console.log(state.value); // -> true },};import { useToggle } from '@vant/use';export default { setup() { const [state, toggle] = useToggle(true); console.log(state.value); // -> true },};function useToggle( defaultValue: boolean): [Ref<boolean>, (newValue: boolean) => void];| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| defaultValue | 默认值 | boolean | false |
| 参数 | 说明 | 类型 |
|---|---|---|
| state | 状态值 | Ref<boolean> |
| toggle | 切换状态值的函数 | (newValue?: boolean) => void |
提供倒计时管理能力。
<span>总时间：{{ current.total }}</span><span>剩余天数：{{ current.days }}</span><span>剩余小时：{{ current.hours }}</span><span>剩余分钟：{{ current.minutes }}</span><span>剩余秒数：{{ current.seconds }}</span><span>剩余毫秒：{{ current.milliseconds }}</span>import { useCountDown } from '@vant/use';export default { setup() { const countDown = useCountDown({ // 倒计时 24 小时 time: 24 * 60 * 60 * 1000, }); // 开始倒计时 countDown.start(); return { current: countDown.current, }; },};倒计时默认每秒渲染一次，设置 millisecond 选项可以开启毫秒级渲染。
import { useCountDown } from '@vant/use';export default { setup() { const countDown = useCountDown({ time: 24 * 60 * 60 * 1000, millisecond: true, }); countDown.start(); return { current: countDown.current, }; },};type CurrentTime = { days: number; hours: number; total: number; minutes: number; seconds: number; milliseconds: number;};type CountDown = { start: () => void; pause: () => void; reset: (totalTime: number) => void; current: ComputedRef<CurrentTime>;};type UseCountDownOptions = { time: number; millisecond?: boolean; onChange?: (current: CurrentTime) => void; onFinish?: () => void;};function useCountDown(options: UseCountDownOptions): CountDown;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| time | 倒计时时长，单位毫秒 | number | - |
| millisecond | 是否开启毫秒级渲染 | boolean | false |
| onChange | 倒计时改变时触发的回调函数 | (current: CurrentTime) => void | - |
| onFinish | 倒计时结束时触发的回调函数 | - |
| 参数 | 说明 | 类型 |
|---|---|---|
| current | 当前剩余的时间 | CurrentTime |
| start | 开始倒计时 | () => void |
| pause | 暂停倒计时 | () => void |
| reset | 重置倒计时，支持传入新的倒计时时长 | (time?: number): void |
| 名称 | 说明 | 类型 |
|---|---|---|
| total | 剩余总时间（单位毫秒） | number |
| days | 剩余天数 | number |
| hours | 剩余小时 | number |
| minutes | 剩余分钟 | number |
| seconds | 剩余秒数 | number |
| milliseconds | 剩余毫秒 | number |
用于自定义 Form 组件中的表单项。
如果需要自定义表单项，可以在 Field 组件的 input 插槽中插入你的自定义组件，并在自定义组件内部调用 useCustomFieldValue 方法。
首先，在你的自定义组件中，调用 useCustomFieldValue 方法，并传入一个回调函数，这个函数返回值为表单项的值。
// MyComponent.vueimport { useCustomFieldValue } from '@vant/use';export default { setup() { // 此处传入的值会替代 Field 组件内部的 value useCustomFieldValue(() => 'Some value'); },};接着，在 Form 组件中嵌入你的自定义组件，当提交表单时，即可获取到自定义表单项的值。
<van-form> <!-- 这是一个自定义表单项 --> <!-- 当表单提交时，会包括 useCustomFieldValue 中传入的值 --> <van-field name="my-field" label="自定义表单项"> <template #input> <my-component /> </template> </van-field></van-form>function useCustomFieldValue(customValue: () => unknown): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| customValue | 获取表单项值的函数 | () => unknown | - |
获取元素的大小及其相对于视口的位置，等价于 Element.getBoundingClientRect。
<div ref="root" />import { ref } from 'vue';import { useRect } from '@vant/use';export default { setup() { const root = ref(); const rect = useRect(); console.log(rect); // -> 元素的大小及其相对于视口的位置 return { root }; },};function useRect( element: Element | Window | Ref<Element | Window | undefined>): DOMRect;| 参数 | 说明 | 类型 |
|---|---|---|
| width | 宽度 | number |
| height | 高度 | number |
| top | 顶部与视图窗口左上角的距离 | number |
| left | 左侧与视图窗口左上角的距离 | number |
| right | 右侧与视图窗口左上角的距离 | number |
| bottom | 底部与视图窗口左上角的距离 | number |
方便地进行事件绑定，在组件 mounted 和 activated 时绑定事件，unmounted 和 deactivated 时解绑事件。
import { ref } from 'vue';import { useEventListener } from '@vant/use';export default { setup() { // 在 window 上绑定 resize 事件 // 未指定监听对象时，默认会监听 window 的事件 useEventListener('resize', () => { console.log('window resize'); }); // 在 body 元素上绑定 click 事件 useEventListener( 'click', () => { console.log('click body'); }, { target: document.body } ); },};type Options = { target?: EventTarget | Ref<EventTarget>; capture?: boolean; passive?: boolean;};function useEventListener( type: string, listener: EventListener, options?: Options): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 监听的事件类型 | string | - |
| listener | 点击外部时触发的回调函数 | EventListener | - |
| options | 可选的配置项 | Options | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| target | 绑定事件的元素 | EventTarget | Ref<EventTarget> | window |
| capture | 是否在事件捕获阶段触发 | boolean | false |
| passive | 设置为 true 时，表示 listener 永远不会调用 preventDefault | boolean | false |
获取页面的可见状态。
import { watch } from 'vue';import { usePageVisibility } from '@vant/use';export default { setup() { const pageVisibility = usePageVisibility(); watch(pageVisibility, (value) => { console.log('visibility: ', value); }); },};type VisibilityState = 'visible' | 'hidden';function usePageVisibility(): Ref<VisibilityState>;| 参数 | 说明 | 类型 |
|---|---|---|
| visibilityState | 页面当前的可见状态，visible 为可见，hidden 为隐藏 | Ref<VisibilityState> |
获取元素最近的可滚动父元素。
<div ref="root" />import { ref, watch } from 'vue';import { useScrollParent, useEventListener } from '@vant/use';export default { setup() { const root = ref(); const scrollParent = useScrollParent(root); useEventListener( 'scroll', () => { console.log('scroll'); }, { target: scrollParent } ); return { root }; },};function useScrollParent( element: Ref<Element | undefined>): Ref<Element | Window | undefined>;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| element | 当前元素 | Ref<Element> | - |
| 参数 | 说明 | 类型 |
|---|---|---|
| scrollParent | 最近的可滚动父元素 | Ref<Element> |
获取浏览器窗口的视口宽度和高度，并在窗口大小变化时自动更新。
import { watch } from 'vue';import { useWindowSize } from '@vant/use';export default { setup() { const { width, height } = useWindowSize(); console.log(width.value); // -> 窗口宽度 console.log(height.value); // -> 窗口高度 watch([width, height], () => { console.log('window resized'); }); },};function useWindowSize(): { width: Ref<number>; height: Ref<number>;};| 参数 | 说明 | 类型 |
|---|---|---|
| width | 浏览器窗口宽度 | Ref<number> |
| height | 浏览器窗口高度 | Ref<number> |
建立父子组件之间的关联关系，进行数据通信和方法调用，基于 provide 和 inject 实现。
在父组件中使用 useChildren 关联子组件:
import { ref } from 'vue';import { useChildren } from '@vant/use';const RELATION_KEY = Symbol('my-relation');export default { setup() { const { linkChildren } = useChildren(RELATION_KEY); const count = ref(0); const add = () => { count.value++; }; // 向子组件提供数据和方法 linkChildren({ add, count }); },};在子组件中使用 useParent 获取父组件提供的数据和方法:
import { useParent } from '@vant/use';export default { setup() { const { parent } = useParent(RELATION_KEY); // 调用父组件提供的数据和方法 if (parent) { parent.add(); console.log(parent.count.value); // -> 1 } },};function useParent<T>( key: string | symbol): { parent?: T; index?: Ref<number>;};function useChildren( key: string | symbol): { children: ComponentPublicInstance[]; linkChildren: (value: any) => void;};| 参数 | 说明 | 类型 |
|---|---|---|
| parent | 父组件提供的值 | any |
| index | 当前组件在父组件的所有子组件中对应的索引位置 | Ref<number> |
| 参数 | 说明 | 类型 |
|---|---|---|
| children | 子组件列表 | ComponentPublicInstance[] |
| linkChildren | 向子组件提供值的方法 | (value: any) => void |
监听点击元素外部的事件。
<div ref="root" />import { ref } from 'vue';import { useClickAway } from '@vant/use';export default { setup() { const root = ref(); useClickAway(root, () => { console.log('click outside!'); }); return { root }; },};通过 eventName 选项可以自定义需要监听的事件类型。
<div ref="root" />import { ref } from 'vue';import { useClickAway } from '@vant/use';export default { setup() { const root = ref(); useClickAway( root, () => { console.log('touch outside!'); }, { eventName: 'touchstart' } ); return { root }; },};type Options = { eventName?: string;};function useClickAway( target: Element | Ref<Element | undefined>, listener: EventListener, options?: Options): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| target | 绑定事件的元素 | Element | Ref<Element> | - |
| listener | 点击外部时触发的回调函数 | EventListener | - |
| options | 可选的配置项 | Options | 见下表 |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| eventName | 监听的事件类型 | string | click |
本文档已废弃，Vant 提供了更方便的 ConfigProvider 全局配置 组件进行主题配置。基于 Less 变量进行定制的方式将在下个大版本废弃。
Vant 提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以按照本文档进行主题定制。
我们提供了一个基于 Vue Cli 3 的示例工程，仓库地址为 Vant Demo，其中包含了定制主题的基本配置，可以作为参考。
Vant 使用了 Less 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。
下面是所有的基础样式变量，组件的样式变量请参考各个组件的文档，或查看组件源码目录下的 var.less 文件。
// Color Palette@black: #000;@white: #fff;@gray-1: #f7f8fa;@gray-2: #f2f3f5;@gray-3: #ebedf0;@gray-4: #dcdee0;@gray-5: #c8c9cc;@gray-6: #969799;@gray-7: #646566;@gray-8: #323233;@red: #ee0a24;@blue: #1989fa;@orange: #ff976a;@orange-dark: #ed6a0c;@orange-light: #fffbe8;@green: #07c160;// Gradient Colors@gradient-red: linear-gradient(to right, #ff6034, #ee0a24);@gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);// Component Colors@text-color: @gray-8;@active-color: @gray-2;@active-opacity: 0.7;@disabled-opacity: 0.5;@background-color: @gray-1;@background-color-light: #fafafa;@text-link-color: #576b95;// Padding@padding-base: 4px;@padding-xs: @padding-base * 2;@padding-sm: @padding-base * 3;@padding-md: @padding-base * 4;@padding-lg: @padding-base * 6;@padding-xl: @padding-base * 8;// Font@font-size-xs: 10px;@font-size-sm: 12px;@font-size-md: 14px;@font-size-lg: 16px;@font-weight-bold: 500;@line-height-xs: 14px;@line-height-sm: 18px;@line-height-md: 20px;@line-height-lg: 22px;@base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;@price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif;// Animation@animation-duration-base: 0.3s;@animation-duration-fast: 0.2s;@animation-timing-function-enter: ease-out;@animation-timing-function-leave: ease-in;// Border@border-color: @gray-3;@border-width-base: 1px;@border-radius-sm: 2px;@border-radius-md: 4px;@border-radius-lg: 8px;@border-radius-max: 999px;定制主题时，需要引入组件对应的 Less 样式文件，支持按需引入和手动引入两种方式。
在 babel.config.js 中配置按需引入样式源文件，注意 babel 6 不支持按需引入样式，请手动引入样式。
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: { // 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。 lessOptions: { modifyVars: { // 直接覆盖变量 'text-color': '#111', 'border-color': '#eee', // 或者可以通过 less 文件覆盖（文件路径为绝对路径） hack: `true; @import "your-less-file-path.less";`, }, }, }, }, ], }, ],};如果 vue-cli 搭建的项目，可以在 vue.config.js 中进行配置。
// vue.config.jsmodule.exports = { css: { loaderOptions: { less: { // 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。 lessOptions: { modifyVars: { // 直接覆盖变量 'text-color': '#111', 'border-color': '#eee', // 或者可以通过 less 文件覆盖（文件路径为绝对路径） hack: `true; @import "your-less-file-path.less";`, }, }, }, }, },};如果是 vite 项目，可以跳过以上步骤，直接在 vite.config.js 中添加如下配置即可。
// vite.config.jsimport vue from '@vitejs/plugin-vue';import styleImport from 'vite-plugin-style-import';export default { css: { preprocessorOptions: { less: { javascriptEnabled: true, // 覆盖样式变量 modifyVars: { 'text-color': '#111', 'border-color': '#eee', }, }, }, }, resolve: { alias: [{ find: /^~/, replacement: '' }], }, plugins: [ vue(), // 按需引入样式源文件 styleImport({ libs: [ { libraryName: 'vant', esModule: true, resolveStyle: (name) => `vant/es/${name}/style/less`, }, ], }), ],};Vant 是有赞前端团队开源的移动端组件库，于 2017 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。
目前 Vant 官方提供了 Vue 2 版本、Vue 3 版本和微信小程序版本，并由社区团队维护 React 版本和支付宝小程序版本。
请参考 快速上手 章节
修改代码请阅读我们的 贡献指南
使用过程中发现任何问题都可以提 Issue 给我们，当然，我们也非常欢迎你给我们发 PR
现代浏览器以及 Android 4.0+, iOS 8.0+
有赞前端团队是由一群年轻、皮实、对技术饱含热情的小伙伴组成的，目前共有 100 多名前端工程师，分布在业务中台、电商、零售、美业、资产、赋能等业务线。
我们热爱分享和开源，崇尚用工程师的方式解决问题，因此造了很多工具来解决我们遇到的问题，目前我们维护的开源产品有：
我们正在寻找更多优秀的小伙伴，一起拓展前端技术的边界，期待你的加入！
| 项目 | 描述 |
|---|---|
| vant-demo | Vant 官方示例合集 |
| vant-weapp | 微信小程序组件库 |
| vant-cli | 开箱即用的组件库搭建工具 |
| vant-icons | Vant 图标库 |
| vant-touch-emulator | 在桌面端使用 Vant 的辅助库 |
由社区维护的项目如下，欢迎补充：
| 项目 | 描述 |
|---|---|
| vant-react | Vant React 版 |
| vant-aliapp | Vant 支付宝小程序版 |
| taroify | Vant Taro 版 |
本项目基于 MIT 协议，请自由地享受和参与开源
在现有项目中使用 Vant 时，可以通过 npm 或 yarn 进行安装：
# Vue 2 项目，安装 Vant 2：npm i vant -S# Vue 3 项目，安装 Vant 3：npm i vant@next -S使用 Vant 最简单的方法是直接在 html 文件中引入 CDN 链接，之后你可以通过全局变量 vant 访问到所有组件。
<!-- 引入样式文件 --><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vant@next/lib/index.css" rel="external nofollow" target="_blank" /><!-- 引入 Vue 和 Vant 的 JS 文件 --><script src="https://cdn.jsdelivr.net/npm/vue@next" rel="external nofollow" ></script><script src="https://cdn.jsdelivr.net/npm/vant@next/lib/vant.min.js" rel="external nofollow" ></script><script> // 在 #app 标签下渲染一个按钮组件 const app = Vue.createApp({ template: `<van-button>按钮</van-button>`, }); app.use(vant); // 通过 CDN 引入时不会自动注册 Lazyload 组件 // 可以通过下面的方式手动注册 app.use(vant.Lazyload); // 调用函数组件，弹出一个 Toast vant.Toast('提示'); app.mount('#app');</script>你可以通过以下免费 CDN 服务来使用 Vant:
在新项目中使用 Vant 时，推荐使用 Vue 官方提供的脚手架 Vue Cli 创建项目并安装 Vant。
# 安装 Vue Clinpm install -g @vue/cli# 创建一个项目vue create hello-world# 创建完成后，可以通过命令打开图形化界面，如下图所示vue ui
在图形化界面中，点击 依赖 -> 安装依赖，然后将 vant 添加到依赖中即可。
我们提供了丰富的示例工程，通过示例工程你可以了解如下内容：
babel-plugin-import 是一款 babel 插件，它会在编译过程中将 import 语句自动转换为按需引入的方式。
# 安装插件npm i babel-plugin-import -D在.babelrc 或 babel.config.js 中添加配置：
{ "plugins": [ [ "import", { "libraryName": "vant", "libraryDirectory": "es", "style": true } ] ]}接着你可以在代码中直接引入 Vant 组件，插件会自动将代码转化为按需引入的形式。
// 原始代码import { Button } from 'vant';// 编译后代码import Button from 'vant/es/button';import 'vant/es/button/style';如果你在使用 TypeScript，可以使用 ts-import-plugin 实现按需引入。
对于 vite 项目，可以使用 vite-plugin-style-import 实现按需引入, 原理和 babel-plugin-import 类似。
# 安装插件npm i vite-plugin-style-import -D// vite.config.jsimport vue from '@vitejs/plugin-vue';import styleImport from 'vite-plugin-style-import';export default { plugins: [ vue(), styleImport({ libs: [ { libraryName: 'vant', esModule: true, resolveStyle: (name) => `vant/es/${name}/style`, }, ], }), ],};在不使用插件的情况下，可以手动引入需要使用的组件和样式。
// 引入组件import Button from 'vant/es/button';// 引入组件对应的样式，若组件没有样式文件，则无须引入import 'vant/es/button/style';Vant 支持一次性导入所有组件，引入所有组件会增加代码包体积，因此不推荐这种做法。
import { createApp } from 'vue';import Vant from 'vant';import 'vant/lib/index.css';const app = createApp();app.use(Vant);Tips: 配置按需引入后，将不允许直接导入所有组件。
Vant 基于 CSS 变量提供了主题定制的能力，可以对组件样式进行统一修改，详见 ConfigProvider 全局配置 组件。
如果主题定制不能满足你的需求，也可以通过自定义样式类来覆盖默认样式，参考下面的示例：
<template> <van-button class="my-button">按钮</van-button></template><style> /** 覆盖 Button 最外层元素的样式 */ .my-button { width: 200px; } /** 覆盖 Button 内部子元素的样式 */ .my-button .van-button__text { color: red; }</style>在 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 支持多种组件注册方式，请根据实际业务需要进行选择。
全局注册后，你可以在 app 下的任意子组件中使用注册的 Vant 组件。
import { Button } from 'vant';import { createApp } from 'vue';const app = createApp();// 方式一. 通过 app.use 注册// 注册完成后，在模板中通过 <van-button> 或 <VanButton> 标签来使用按钮组件app.use(Button);// 方式二. 通过 app.component 注册// 注册完成后，在模板中通过 <van-button> 标签来使用按钮组件app.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://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.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(); },};Vant 默认使用 px 作为样式单位，如果需要使用 viewport 单位 (vw, vh, vmin, vmax)，推荐使用 postcss-px-to-viewport 进行转换。
postcss-px-to-viewport 是一款 PostCSS 插件，用于将 px 单位转化为 vw/vh 单位。
下面提供了一份基本的 PostCSS 示例配置，可以在此配置的基础上根据项目需求进行修改。
// postcss.config.jsmodule.exports = { plugins: { 'postcss-px-to-viewport': { viewportWidth: 375, }, },};Tips: 在配置 postcss-loader 时，应避免 ignore node_modules 目录，否则将导致 Vant 样式无法被编译。
如果需要使用 rem 单位进行适配，推荐使用以下两个工具：
下面提供了一份基本的 PostCSS 示例配置，可以在此配置的基础上根据项目需求进行修改。
// postcss.config.jsmodule.exports = { plugins: { 'postcss-pxtorem': { rootValue: 37.5, propList: ['*'], }, },};如果设计稿的尺寸不是 375，而是 750 或其他大小，可以将 rootValue 配置调整为:
// postcss.config.jsmodule.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 />
提示
当前文档为 Vant 3 的更新日志，如需查询 Vant 2 的更新内容，请访问 Vant 2 更新日志。
Vant 遵循 Semver 语义化版本规范。
发布节奏
2021-07-26
Feature
Bug Fixes
2021-07-19
Feature
Bug Fixes
2021-07-11
Feature
Bug Fixes
2021-07-03
Feature
Bug Fixes
2021-06-27
Feature
2021-06-22
New Component
Feature
Bug Fixes
2021-06-03
Feature
Bug Fixes
2021-05-23
Feature
Bug Fixes
2021-05-03
Feature
Bug Fixes
2021-04-25
Feature
Bug Fixes
2021-04-18
Feature
Bug Fixes
2021-04-11
Feature
Types
Bug Fixes
2021-04-05
Feature
Bug Fixes
2021-03-30
Feature
Bug Fixes
2021-03-19
Feature
Feature
Bug Fixes
2021-03-08
Feature
Bug Fixes
2021-03-07
Types
Feature
Bug Fixes
2021-02-28
Feature
perf
Bug Fixes
2021-01-31
Feature
Bug Fixes
2021-01-24
Feature
style
Bug Fixes
2021-01-17
Feature
Bug Fixes
2021-01-10
Feature
Bug Fixes
2021-01-02
Feature
Bug Fixes
2020-12-27
Feature
Bug Fixes
2020-12-23
更新内容
2020-12-21
New Component
Feature
Types
2020-12-10
Breaking Change
perf
Bug Fixes
2020-12-04
perf
Bug Fixes
2020-12-01
Breaking Change
Feature
style
Bug Fixes
2020-11-22
Bug Fixes
2020-11-22
New Component
Feature
Bug Fixes
2020-11-15
Bug Fixes
2020-11-08
Bug Fixes
2020-11-01
Bug Fixes
2020-10-24
Bug Fixes
2020-10-18
refactor
style
Bug Fixes
2020-10-03
breaking changes
Feature
2020-09-28
Bug Fixes
2020-09-28
breaking changes
refactor
使用 Composition API 重构以下组件：
Feature
Bug Fixes
2020-09-18
breaking changes
refactor
使用 Composition API 重构以下组件：
Bug Fixes
2020-09-13
breaking changes
refactor
使用 Composition API 重构以下组件：
Feature
Bug Fixes
2020-09-06
breaking changes
refactor
使用 Composition API 重构以下组件：
Bug Fixes
2020-09-01
Feature
Vant 3 是基于 Vue 3 开发的，在使用 Vant 3 前，请将项目中的 Vue 升级到 3.0 以上版本。
Vant 2 到 Vant 3 存在一些不兼容更新，请仔细阅读下方的不兼容更新内容，并依次处理。
组件命名调整
GoodsAction 商品导航组件重命名为 ActionBar 行动栏。
<!-- Vant 2 --><van-goods-action> <van-goods-action-icon text="图标" /> <van-goods-action-button text="按钮" /></van-goods-action><!-- Vant 3 --><van-action-bar> <van-action-bar-icon text="图标" /> <van-action-bar-button text="按钮" /></van-action-bar>移除 SwitchCell 组件，可以直接使用 Cell 和 Switch 组件代替。
<!-- Vant 2 --><van-switch-cell title="标题" v-model="checked" /><!-- Vant 3 --><van-cell center title="标题"> <template #right-icon> <van-switch v-model="checked" size="24" /> </template></van-cell>为了适配 Vue 3 的 v-model API 用法变更，所有提供 v-model 属性的组件在用法上有一定调整。以下弹窗类组件的 v-model 被重命名为 v-model:show：
<!-- Vant 2 --><van-popup v-model="show" /><!-- Vant 3 --><van-popup v-model:show="show" />以下表单型组件 v-model 对应的 prop 重命名为 modelValue，event 重命名为 update:modelValue：
<!-- Vant 2 --><van-field :value="value" @input="onInput" /><!-- Vant 3 --><van-field :model-value="value" @update:model-value="onInput" />在之前的版本中，我们通过 info 属性来展示图标右上角的徽标信息，为了更符合社区的命名习惯，我们将这个属性重命名为 badge，影响以下组件：
同时内部使用的 Info 组件也会重命名为 Badge。
<!-- Vant 2 --><van-icon info="5" /><!-- Vant 3 --><van-icon badge="5" />Vue 3.0 中增加了 Teleport 组件，提供将组件渲染到任意 DOM 位置的能力，Vant 2 也通过 get-container 属性提供了类似的能力。为了与官方的 API 保持一致，Vant 中的 get-container 属性将重命名为 teleport。
<!-- Vant 2 --><template> <van-popup get-container="body" /> <van-popup :get-container="getContainer" /></template><script> export default { methods: { getContainer() { return document.querySelector('#container'); }, }, };</script><!-- Vant 3 --><template> <van-popup teleport="body" /> <van-popup :teleport="container" /></template><script> export default { beforeCreate() { this.container = document.querySelector('#container'); }, };</script>Vant 2 中默认提供了 $toast、$dialog 等全局方法，但 Vue 3.0 不再支持直接在 Vue 的原型链上挂载方法，因此从 Vant 3.0 开始，使用全局方法前必须先通过 app.use 将组件注册到对应的 app 上。
import { Toast, Dialog, Notify } from 'vant';// 将 Toast 等组件注册到 app 上app.use(Toast);app.use(Dialog);app.use(Notify);// app 内的子组件可以直接调用 $toast 等方法export default { mounted() { this.$toast('提示文案'); },};感谢你使用 Vant。
以下是关于向 Vant 提交反馈或代码的指南。在向 Vant 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下文字。
按照下面的步骤操作，即可在本地开发 Vant 组件。
# 克隆仓库# 默认为 dev 分支，包含 Vant 3 的代码# 如果需要在 Vant 2 上进行更改，请基于 2.x 分支进行开发git clone git@github.com:youzan/vant.git# 安装依赖cd vant && yarn# 进入开发模式，浏览器访问 http://localhost:8080npm run dev项目的主要目录结构如下所示：
vant├─ docs # 文档├─ packages # 基础包├─ src # 组件源代码├─ test # 单测工具类└─ vant.config.js # 文档网站配置组件代码位于 src 目录下，每个组件一个独立的文件夹。
添加新组件时，请按照下面的目录结构组织文件，并在 vant.config.js 中配置组件名称。
src└─ button ├─ demo # 示例代码 ├─ test # 单元测试 ├─ Component.ts # 组件 ├─ index.ts # 组件入口 ├─ index.less # 样式 ├─ var.less # 样式变量 ├─ README.md # 英文文档 └─ README.zh-CN.md # 中文文档如果你是第一次在 GitHub 上提 Pull Request ，可以阅读下面这两篇文章来学习：
提 Pull Request 前，请依照下面的流程同步主仓库的最新代码：
# 添加主仓库到 remote，作为 fork 后仓库的上游仓库git remote add upstream https://github.com/youzan/vant.git# 拉取主仓库最新代码git fetch upstream# 切换至 dev 分支git checkout dev# 合并主仓库代码git merge upstream/devVant 是基于有赞 Zan Design System 视觉规范实现的组件库，在这里可以下载 Vant 的设计资源。
包含 Sketch 格式的色彩规范、字体规范、组件设计规范。
包含 Sketch 格式的图标库资源。
Vant 的所有图标都托管在 iconfont.cn 上，点此查看：Vant 图标库。
Axure 元件库，由社区的 @axure-tczy 同学贡献。
在参与 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 的时候，其命名应该始终使用 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" />指令缩写，用 : 表示 v-bind: ，用 @ 表示 v-on:
<!-- bad --><input v-bind:value="value" v-on:input="onInput" /><!-- good --><input :value="value" @input="onInput" />标签的 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: '', components: {}, props: {}, emits: [], setup() {}, data() {}, computed: {}, watch: {}, created() {}, mounted() {}, unmounted() {}, 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/es/locale/lang/en-US';Locale.use('en-US', enUS);通过 Locale.add 方法可以实现文案的修改和扩展，示例如下：
import { Locale } from 'vant';const messages = { 'zh-CN': { vanPicker: { confirm: '关闭', // 将'确认'修改为'关闭' }, },};Locale.add(messages);目前支持的语言:
| 语言 | 文件名 |
|---|---|
| 简体中文 | zh-CN |
| 繁體中文（港） | zh-HK |
| 繁體中文（台） | zh-TW |
| 德语 | de-DE |
| 德语 (正式) | de-DE-formal |
| 英语 | en-US |
| 西班牙语 | es-ES |
| 日语 | ja-JP |
| 挪威语 | nb-NO |
| 罗马尼亚语 | ro-RO |
| 俄罗斯语 | ru-RU |
| 土耳其语 | tr-TR |
| 泰语 | th-TH |
| 法语 | fr-FR |
在 这里 查看所有的语言包源文件。
如果上方列表中没有你需要的语言，欢迎给我们提 Pull Request 来增加新的语言包，改动内容可以参考增加德语语言包 的 PR。
可以使用 vue-i18n 来实现。
目前没有提供 CDN 形式的语言包，可以手动拷贝语言包的内容来使用。
语言包中默认不包含 Sku 业务组件的语言配置，因此如果有 Sku 组件的国际化需求，请自行配置国际化文案。
按钮用于触发一个操作，如提交表单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Button } from 'vant';const app = createApp();app.use(Button);按钮支持 default、primary、success、warning、danger 五种类型，默认为 default。
<van-button type="primary">主要按钮</van-button><van-button type="success">成功按钮</van-button><van-button type="default">默认按钮</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="primary">朴素按钮</van-button>设置 hairline 属性可以展示 0.5px 的细边框。
<van-button plain hairline type="primary">细边框按钮</van-button><van-button plain hairline type="primary">细边框按钮</van-button>通过 disabled 属性来禁用按钮，禁用状态下按钮不可点击。
<van-button disabled type="primary">禁用状态</van-button><van-button disabled type="primary">禁用状态</van-button>通过 loading 属性设置按钮为加载状态，加载状态下默认会隐藏按钮文字，可以通过 loading-text 设置加载状态下的文字。
<van-button loading type="primary" /><van-button loading type="primary" loading-type="spinner" /><van-button loading type="primary" loading-text="加载中..." />通过 square 设置方形按钮，通过 round 设置圆形按钮。
<van-button square type="primary">方形按钮</van-button><van-button round type="primary">圆形按钮</van-button>通过 icon 属性设置按钮图标，支持 Icon 组件里的所有图标，也可以传入图标 URL。
<van-button icon="plus" type="primary" /><van-button icon="plus" type="primary">按钮</van-button><van-button icon="https://img.yzcdn.cn/vant/user-active.png" type="primary"> 按钮</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, #ff6034, #ee0a24)"> 渐变色按钮</van-button>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success warning danger | string | default |
| size | 尺寸，可选值为 large small mini | string | normal |
| text | 按钮文字 | string | - |
| color | 按钮颜色，支持传入 linear-gradient 渐变色 | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| icon-position | 图标展示位置，可选值为 right | string | left |
| tag | 按钮根节点的 HTML 标签 | string | button |
| native-type | 原生 button 标签的 type 属性 | string | button |
| block | 是否为块级元素 | boolean | false |
| plain | 是否为朴素按钮 | boolean | false |
| square | 是否为方形按钮 | boolean | false |
| round | 是否为圆形按钮 | boolean | false |
| disabled | 是否禁用按钮 | boolean | false |
| hairline | 是否使用 0.5px 边框 | boolean | false |
| loading | 是否显示为加载状态 | boolean | false |
| loading-text | 加载状态提示文字 | string | - |
| loading-type | 加载图标类型，可选值为 spinner | string | circular |
| loading-size | 加载图标大小 | string | 20px |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，同 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击按钮，且按钮状态不为加载或禁用时触发 | event: MouseEvent |
| touchstart | 开始触摸按钮时触发 | event: TouchEvent |
| 名称 | 说明 |
|---|---|
| default | 按钮内容 |
icon v3.0.18 | 自定义图标 |
| loading | 自定义加载图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-button-mini-height | 24px | - |
| --van-button-mini-padding | 0 var(--van-padding-base) | - |
| --van-button-mini-font-size | var(--van-font-size-xs) | - |
| --van-button-small-height | 32px | - |
| --van-button-small-padding | 0 var(--van-padding-xs) | - |
| --van-button-small-font-size | var(--van-font-size-sm) | - |
| --van-button-normal-font-size | var(--van-font-size-md) | - |
| --van-button-normal-padding | 0 15px | - |
| --van-button-large-height | 50px | - |
| --van-button-default-height | 44px | - |
| --van-button-default-line-height | 1.2 | - |
| --van-button-default-font-size | var(--van-font-size-lg) | - |
| --van-button-default-color | var(--van-text-color) | - |
| --van-button-default-background-color | var(--van-white) | - |
| --van-button-default-border-color | var(--van-border-color) | - |
| --van-button-primary-color | var(--van-white) | - |
| --van-button-primary-background-color | var(--van-primary-color) | - |
| --van-button-primary-border-color | var(--van-primary-color) | - |
| --van-button-success-color | var(--van-white) | - |
| --van-button-success-background-color | var(--van-success-color) | - |
| --van-button-success-border-color | var(--van-success-color) | - |
| --van-button-danger-color | var(--van-white) | - |
| --van-button-danger-background-color | var(--van-danger-color) | - |
| --van-button-danger-border-color | var(--van-danger-color) | - |
| --van-button-warning-color | var(--van-white) | - |
| --van-button-warning-background-color | var(--van-orange) | - |
| --van-button-warning-border-color | var(--van-orange) | - |
| --van-button-border-width | var(--van-border-width-base) | - |
| --van-button-border-radius | var(--van-border-radius-sm) | - |
| --van-button-round-border-radius | var(--van-border-radius-max) | - |
| --van-button-plain-background-color | var(--van-white) | - |
| --van-button-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-button-icon-size | 1.2em | - |
| --van-button-loading-icon-size | 20px | - |
单元格为列表中的单个展示项。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Cell, CellGroup } from 'vant';const app = createApp();app.use(Cell);app.use(CellGroup);Cell 可以单独使用，也可以与 CellGroup 搭配使用，CellGroup 可以为 Cell 提供上下外边框。
<van-cell-group> <van-cell title="单元格" value="内容" /> <van-cell title="单元格" value="内容" label="描述信息" /></van-cell-group>通过 CellGroup 的 inset 属性，可以将单元格转换为圆角卡片风格（从 3.1.0 版本开始支持）。
<van-cell-group inset> <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 时，内容会靠左对齐。
<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 #title> <span class="custom-title">单元格</span> <van-tag type="danger">标签</van-tag> </template></van-cell><van-cell title="单元格" icon="shop-o"> <!-- 使用 right-icon 插槽来自定义右侧图标 --> <template #right-icon> <van-icon name="search" class="search-icon" /> </template></van-cell><style> .custom-title { margin-right: 4px; vertical-align: middle; } .search-icon { font-size: 16px; line-height: inherit; }</style>通过 center 属性可以让 Cell 的左右内容都垂直居中。
<van-cell center title="单元格" value="内容" label="描述信息" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 分组标题 | string | - |
inset v3.1.0 | 是否展示为圆角卡片风格 | boolean | false |
| border | 是否显示外边框 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 左侧标题 | number | string | - |
| value | 右侧内容 | number | string | - |
| label | 标题下方的描述信息 | string | - |
| size | 单元格大小，可选值为 large | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，同 vue-router 的 to 属性 | string | object | - |
| border | 是否显示内边框 | boolean | true |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| clickable | 是否开启点击反馈 | boolean | null |
| is-link | 是否展示右侧箭头并开启点击反馈 | boolean | false |
| required | 是否显示表单必填星号 | boolean | false |
| center | 是否使内容垂直居中 | boolean | false |
| arrow-direction | 箭头方向，可选值为 left up down | string | right |
| title-style | 左侧标题额外样式 | string | Array | object | - |
| title-class | 左侧标题额外类名 | string | Array | object | - |
| value-class | 右侧内容额外类名 | string | Array | object | - |
| label-class | 描述信息额外类名 | string | Array | object | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击单元格时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 默认插槽 |
| title | 自定义分组标题 |
| 名称 | 说明 |
|---|---|
| title | 自定义左侧标题 |
value v3.1.1 | 自定义右侧内容 |
| label | 自定义标题下方的描述信息 |
| icon | 自定义左侧图标 |
| right-icon | 自定义右侧图标 |
| extra | 自定义单元格最右侧的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-cell-font-size | var(--van-font-size-md) | - |
| --van-cell-line-height | 24px | - |
| --van-cell-vertical-padding | 10px | - |
| --van-cell-horizontal-padding | var(--van-padding-md) | - |
| --van-cell-text-color | var(--van-text-color) | - |
| --van-cell-background-color | var(--van-white) | - |
| --van-cell-border-color | var(--van-border-color) | - |
| --van-cell-active-color | var(--van-active-color) | - |
| --van-cell-required-color | var(--van-danger-color) | - |
| --van-cell-label-color | var(--van-gray-6) | - |
| --van-cell-label-font-size | var(--van-font-size-sm) | - |
| --van-cell-label-line-height | var(--van-line-height-sm) | - |
| --van-cell-label-margin-top | var(--van-padding-base) | - |
| --van-cell-value-color | var(--van-gray-6) | - |
| --van-cell-icon-size | 16px | - |
| --van-cell-right-icon-color | var(--van-gray-6) | - |
| --van-cell-large-vertical-padding | var(--van-padding-sm) | - |
| --van-cell-large-title-font-size | var(--van-font-size-lg) | - |
| --van-cell-large-label-font-size | var(--van-font-size-md) | - |
| --van-cell-group-background-color | var(--van-white) | - |
| --van-cell-group-title-color | var(--van-gray-6) | - |
| --van-cell-group-title-padding | var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) | - |
| --van-cell-group-title-font-size | var(--van-font-size-md) | - |
| --van-cell-group-title-line-height | 16px | - |
| --van-cell-group-inset-padding | 0 var(--van-padding-md) | - |
| --van-cell-group-inset-border-radius | var(--van-border-radius-lg) | - |
| --van-cell-group-inset-title-padding | var(--van-padding-md) var(--van-padding-md) var(--van-padding-xs) var(--van-padding-xl) | - |
用于配置 Vant 组件的主题样式，从 3.1.0 版本开始支持。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ConfigProvider } from 'vant';const app = createApp();app.use(ConfigProvider);Vant 组件通过丰富的 CSS 变量 来组织样式，通过覆盖这些 CSS 变量，可以实现定制主题、动态切换主题等效果。
以 Button 组件为例，查看组件的样式，可以看到 .van-button--primary 类名上存在以下变量：
.van-button--primary { color: var(--van-button-primary-color); background-color: var(--van-button-primary-background-color);}这些变量的默认值被定义在 root 节点上，HTML 文档的任何节点都可以访问到这些变量：
:root { --van-white: #fff; --van-blue: #1989fa; --van-button-primary-color: var(--van-white); --van-button-primary-background-color: var(--van-primary-color);}你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：
/* 添加这段样式后，Primary Button 会变成红色 */:root { --van-button-primary-background-color: red;}ConfigProvider 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 ConfigProvider 组件，并通过 theme-vars 属性来配置一些主题变量。
<van-config-provider :theme-vars="themeVars"> <van-form> <van-field name="rate" label="评分"> <template #input> <van-rate v-model="rate" /> </template> </van-field> <van-field name="slider" label="滑块"> <template #input> <van-slider v-model="slider" /> </template> </van-field> <div style="margin: 16px"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div> </van-form></van-config-provider>import { ref } from 'vue';export default { setup() { const rate = ref(4); const slider = ref(50); // themeVars 内的值会被转换成对应 CSS 变量 // 比如 sliderBarHeight 会转换成 `--van-slider-bar-height` const themeVars = { rateIconFullColor: '#07c160', sliderBarHeight: '4px', sliderButtonWidth: '20px', sliderButtonHeight: '20px', sliderActiveBackgroundColor: '#07c160', buttonPrimaryBorderColor: '#07c160', buttonPrimaryBackgroundColor: '#07c160', }; return { rate, slider, themeVars, }; },};注意：ConfigProvider 仅影响它的子组件的样式，不影响全局 root 节点。
Vant 中的 CSS 变量分为 基础变量 和 组件变量。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。
由于 CSS 变量继承机制的原因， 两者的修改方式有一定差异：
下面是所有的基础变量：
// Color Palette--van-black: #000;--van-white: #fff;--van-gray-1: #f7f8fa;--van-gray-2: #f2f3f5;--van-gray-3: #ebedf0;--van-gray-4: #dcdee0;--van-gray-5: #c8c9cc;--van-gray-6: #969799;--van-gray-7: #646566;--van-gray-8: #323233;--van-red: #ee0a24;--van-blue: #1989fa;--van-orange: #ff976a;--van-orange-dark: #ed6a0c;--van-orange-light: #fffbe8;--van-green: #07c160;// Gradient Colors--van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24);--van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);// Component Colors--van-primary-color: var(--van-blue);--van-success-color: var(--van-green);--van-danger-color: var(--van-red);--van-warning-color: var(--van-orange);--van-text-color: var(--van-gray-8);--van-active-color: var(--van-gray-2);--van-active-opacity: 0.7;--van-disabled-opacity: 0.5;--van-background-color: var(--van-gray-1);--van-background-color-light: #fafafa;--van-text-link-color: #576b95;// Padding--van-padding-base: 4px;--van-padding-xs: 8px;--van-padding-sm: 12px;--van-padding-md: 16px;--van-padding-lg: 24px;--van-padding-xl: 32px;// Font--van-font-size-xs: 10px;--van-font-size-sm: 12px;--van-font-size-md: 14px;--van-font-size-lg: 16px;--van-font-weight-bold: 500;--van-line-height-xs: 14px;--van-line-height-sm: 18px;--van-line-height-md: 20px;--van-line-height-lg: 22px;--van-base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;--van-price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif;// Animation--van-animation-duration-base: 0.3s;--van-animation-duration-fast: 0.2s;--van-animation-timing-function-enter: ease-out;--van-animation-timing-function-leave: ease-in;// Border--van-border-color: var(--van-gray-3);--van-border-width-base: 1px;--van-border-radius-sm: 2px;--van-border-radius-md: 4px;--van-border-radius-lg: 8px;--van-border-radius-max: 999px;你可以在各个组件文档底部的表格中查看组件变量。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| theme-vars | 自定义主题变量 | object | - |
tag v3.1.2 | 根节点对应的 HTML 标签名 | string | div |
icon-prefix v3.1.3 | 所有图标的类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过 icon 属性引用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Icon } from 'vant';const app = createApp();app.use(Icon);通过 name 属性来指定需要使用的图标，Vant 内置了一套图标库（见右侧示例），可以直接传入对应的名称来使用。
<van-icon name="chat-o" />你也可以直接在 name 属性中传入一个图片 URL 来作为图标。
<van-icon name="https://b.yzcdn.cn/vant/icon-demo-1126.png" />设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-icon name="chat-o" dot /><van-icon name="chat-o" badge="9" /><van-icon name="chat-o" badge="99+" />通过 color 属性来设置图标的颜色。
<van-icon name="cart-o" color="#1989fa" /><van-icon name="fire-o" color="#ee0a24" />通过 size 属性来设置图标的尺寸大小，可以指定任意 CSS 单位。
<!-- 不指定单位，默认使用 px --><van-icon name="chat-o" size="40" /><!-- 指定使用 rem 单位 --><van-icon name="chat-o" size="3rem" />如果需要在现有 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" />https://vant-contrib.gitee.io/vant/v3/mobile.html#/zh-CN/icon有vant的默认自带的图标可供选用！
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 图标名称或图片链接 | string | - |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| color | 图标颜色 | string | inherit |
| size | 图标大小，如 20px 2em，默认单位为 px | number | string | inherit |
| class-prefix | 类名前缀，用于使用自定义图标 | string | van-icon |
| tag | 根节点对应的 HTML 标签名 | string | i |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击图标时触发 | event: MouseEvent |
增强版的 img 标签，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Image as VanImage } from 'vant';const app = createApp();app.use(VanImage);基础用法与原生 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 { createApp } from 'vue';import { Lazyload } from 'vant';const app = createApp();app.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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| src | 图片链接 | string | - |
| fit | 图片填充模式 | string | fill |
| alt | 替代文本 | string | - |
| width | 宽度，默认单位为 px | number | string | - |
| height | 高度，默认单位为 px | number | string | - |
| radius | 圆角大小，默认单位为 px | number | string | 0 |
| round | 是否显示为圆形 | boolean | false |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| show-error | 是否展示图片加载失败提示 | boolean | true |
| show-loading | 是否展示图片加载中提示 | boolean | true |
| error-icon | 失败时提示的图标名称或图片链接 | string | photo-fail |
| loading-icon | 加载时提示的图标名称或图片链接 | string | photo |
icon-size v3.0.11 | 加载图标和失败图标的大小 | number | string | 32px |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| 名称 | 含义 |
|---|---|
| contain | 保持宽高缩放图片，使图片的长边能完全显示出来 |
| cover | 保持宽高缩放图片，使图片的短边能完全显示出来，裁剪长边 |
| fill | 拉伸图片，使图片填满元素 |
| none | 保持图片原有尺寸 |
| scale-down | 取 none 或 contain 中较小的一个 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击图片时触发 | event: MouseEvent |
| load | 图片加载完毕时触发 | - |
| error | 图片加载失败时触发 | - |
| 名称 | 说明 |
|---|---|
| default | 自定义图片下方的内容 |
| loading | 自定义加载中的提示内容 |
| error | 自定义加载失败时的提示内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-image-placeholder-text-color | var(--van-gray-6) | - |
| --van-image-placeholder-font-size | var(--van-font-size-md) | - |
| --van-image-placeholder-background-color | var(--van-background-color) | - |
| --van-image-loading-icon-size | 32px | - |
| --van-image-loading-icon-color | var(--van-gray-4) | - |
| --van-image-error-icon-size | 32px | - |
| --van-image-error-icon-color | var(--van-gray-4) | - |
在 .vue 文件中通过相对路径引用本地图片时，需要在图片的链接外包上一层 require()，将图片 URL 转换为 webpack 模块请求，并结合 file-loader 或者 url-loader 进行处理。
<!-- 错误写法 --><van-image src="./image.png" /><!-- 正确写法 --><van-image :src="require('./image.png')" /> 对此更详细的解释可以参考 vue-loader 的处理资源路径章节。
使用 Image 组件时，可能会遇到将 <image> 作为标签名时无法渲染的问题，比如下面的写法：
<template> <image src="xxx" /></template><script>import { Image } from 'vant';export default { components: { Image, },};<script>这是因为 <image> 标签是原生的 SVG 标签，Vue 不允许将原生标签名注册为组件名，使用 <van-image> 即可规避这个问题。
Layout 提供了 van-row 和 van-col 两个组件来进行行列布局。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Col, Row } from 'vant';const app = createApp();app.use(Col);app.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>通过 justify 属性可以设置主轴上内容的对齐方式，等价于 flex 布局中的 justify-content 属性。
<!-- 居中 --><van-row 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 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 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 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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| gutter | 列元素之间的间距（单位为 px） | number | string | - |
| tag | 自定义元素标签 | string | div |
| justify | 主轴对齐方式，可选值为 end centerspace-around space-between | string | start |
| align | 交叉轴对齐方式，可选值为 center bottom | string | top |
wrap v3.0.11 | 是否自动换行 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| span | 列元素宽度 | number | string | - |
| offset | 列元素偏移距离 | number | string | - |
| tag | 自定义元素标签 | string | div |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Popup } from 'vant';const app = createApp();app.use(Popup);通过 v-model:show 控制弹出层是否展示。
<van-cell is-link @click="showPopup">展示弹出层</van-cell><van-popup v-model:show="show">内容</van-popup>import { ref } from 'vue';export default { setup() { const show = ref(false); const showPopup = () => { show.value = true; }; return { show, showPopup, }; },};通过 position 属性设置弹出位置，默认居中弹出，可以设置为 top、bottom、left、right。
<van-popup v-model:show="show" position="top" :style="{ height: '30%' }" />设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用 close-icon-position 属性可以自定义图标位置。
<van-popup v-model:show="show" closeable position="bottom" :style="{ height: '30%' }"/><!-- 自定义图标 --><van-popup v-model:show="show" closeable close-icon="close" position="bottom" :style="{ height: '30%' }"/><!-- 图标位置 --><van-popup v-model:show="show" closeable close-icon-position="top-left" position="bottom" :style="{ height: '30%' }"/>设置 round 属性后，弹窗会根据弹出位置添加不同的圆角样式。
<van-popup v-model:show="show" round position="bottom" :style="{ height: '30%' }"/>弹出层默认挂载到组件标签所在位置，可以通过 teleport 属性指定挂载位置。
<!-- 挂载到 body 节点下 --><van-popup v-model:show="show" teleport="body" /><!-- 挂载到 #app 节点下 --><van-popup v-model:show="show" teleport="#app" /><!-- 挂载到指定的元素下 --><van-popup v-model:show="show" :teleport="myContainer" />export default { setup() { const myContainer = document.querySelector('.my-container'); return { myContainer, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示弹出层 | boolean | false |
| overlay | 是否显示遮罩层 | boolean | true |
| position | 弹出位置，可选值为 top bottom right left | string | center |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| duration | 动画时长，单位秒 | number | string | 0.3 |
| round | 是否显示圆角 | boolean | false |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | false |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| closeable | 是否显示关闭图标 | boolean | false |
| close-icon | 关闭图标名称或图片链接 | string | cross |
| close-icon-position | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
icon-prefix v3.0.18 | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| transition-appear | 是否在初始渲染时启用过渡动画 | boolean | false |
| teleport | 指定挂载的节点 | string | Element | - |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击弹出层时触发 | event: MouseEvent |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| click-close-icon | 点击关闭图标时触发 | event: MouseEvent |
| open | 打开弹出层时触发 | - |
| close | 关闭弹出层时触发 | - |
| opened | 打开弹出层且动画结束后触发 | - |
| closed | 关闭弹出层且动画结束后触发 | - |
| 名称 | 说明 |
|---|---|
| default | 弹窗内容 |
overlay-content v3.0.18 | 遮罩层的内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-popup-background-color | var(--van-white) | - |
| --van-popup-transition | transform var(--van-animation-duration-base) | - |
| --van-popup-round-border-radius | 16px | - |
| --van-popup-close-icon-size | 22px | - |
| --van-popup-close-icon-color | var(--van-gray-5) | - |
| --van-popup-close-icon-active-color | var(--van-gray-6) | - |
| --van-popup-close-icon-margin | 16px | - |
| --van-popup-close-icon-z-index | 1 | - |
Vant 中默认包含了一些常用样式，可以直接通过 className 的方式使用。
当文本内容长度超过容器最大宽度时，自动省略多余的文本。
<!-- 最多显示一行 --><div class="van-ellipsis">这是一段最多显示一行的文字，多余的内容会被省略</div><!-- 最多显示两行 --><div class="van-multi-ellipsis--l2"> 这是一段最多显示两行的文字，多余的内容会被省略</div><!-- 最多显示三行 --><div class="van-multi-ellipsis--l3"> 这是一段最多显示三行的文字，多余的内容会被省略</div>为元素添加 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>为元素添加底部安全区适配。
<div class="van-safe-area-bottom"></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>在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Toast } from 'vant';const app = createApp();app.use(Toast);
Toast('提示内容');使用 Toast.loading 方法展示加载提示，通过 forbidClick 属性可以禁用背景点击。
Toast.loading({ message: '加载中...', forbidClick: true,});使用 Toast.success 方法展示成功提示，使用 Toast.fail 方法展示失败提示。
Toast.success('成功文案');Toast.fail('失败文案');通过 icon 选项可以自定义图标，支持传入图标名称或图片链接，通过loadingType 属性可以自定义加载图标类型。
Toast({ message: '自定义图标', icon: 'like-o',});Toast({ message: '自定义图片', icon: 'https://img.yzcdn.cn/vant/logo.png',});Toast.loading({ message: '加载中...', forbidClick: true, loadingType: 'spinner',});Toast 默认渲染在屏幕正中位置，通过 position 属性可以控制 Toast 展示的位置。
Toast({ message: '顶部展示', position: 'top',});Toast({ message: '底部展示', position: 'bottom',});执行 Toast 方法时会返回对应的 Toast 实例，通过修改实例上的 message 属性可以实现动态更新提示的效果。
const toast = Toast.loading({ duration: 0, forbidClick: true, message: '倒计时 3 秒',});let second = 3;const timer = setInterval(() => { second--; if (second) { toast.message = `倒计时 ${second} 秒`; } else { clearInterval(timer); Toast.clear(); }}, 1000);通过 app.use 全局注册 Toast 组件后，会自动在 app 的所有子组件上挂载 $toast 方法，便于在组件内调用。
export default { mounted() { this.$toast('提示文案'); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例：
Toast.allowMultiple();const toast1 = Toast('第一个 Toast');const toast2 = Toast.success('第二个 Toast');toast1.clear();toast2.clear();通过 Toast.setDefaultOptions 函数可以全局修改 Toast 的默认配置。
Toast.setDefaultOptions({ duration: 2000 });Toast.setDefaultOptions('loading', { forbidClick: true });Toast.resetDefaultOptions();Toast.resetDefaultOptions('loading');| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Toast | 展示提示 | options | message | toast 实例 |
| Toast.loading | 展示加载提示 | options | message | toast 实例 |
| Toast.success | 展示成功提示 | options | message | toast 实例 |
| Toast.fail | 展示失败提示 | options | message | toast 实例 |
| Toast.clear | 关闭提示 | clearAll: boolean | void |
| Toast.allowMultiple | 允许同时存在多个 Toast | - | void |
| Toast.setDefaultOptions | 修改默认配置，对所有 Toast 生效。 传入 type 可以修改指定类型的默认配置 | type | options | void |
| Toast.resetDefaultOptions | 重置默认配置，对所有 Toast 生效。 传入 type 可以重置指定类型的默认配置 | type | void |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 提示类型，可选值为 loading successfail html | string | text |
| position | 位置，可选值为 top bottom | string | middle |
| message | 文本内容，支持通过
换行 | string | '' |
| icon | 自定义图标，支持传入图标名称或图片链接 | string | - |
| iconSize | 图标大小，如 20px 2em，默认单位为 px | number | string | 36px |
| iconPrefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| overlay | 是否显示背景遮罩层 | boolean | false |
| forbidClick | 是否禁止背景点击 | boolean | false |
| closeOnClick | 是否在点击后关闭 | boolean | false |
| closeOnClickOverlay | 是否在点击遮罩层后关闭 | boolean | false |
| loadingType | 加载图标类型, 可选值为 spinner | string | circular |
| duration | 展示时长(ms)，值为 0 时，toast 不会消失 | number | 2000 |
| className | 自定义类名 | string | Array | object | - |
overlayClass v3.0.4 | 自定义遮罩层类名 | string | Array | object | - |
overlayStyle v3.0.4 | 自定义遮罩层样式 | object | - |
| onOpened | 完全展示后的回调函数 | Function | - |
| onClose | 关闭时的回调函数 | Function | - |
| transition | 动画类名，等价于 transition 的name属性 | string | van-fade |
| teleport | 指定挂载的节点，用法示例 | string | Element | body |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-toast-max-width | 70% | - |
| --van-toast-font-size | var(--van-font-size-md) | - |
| --van-toast-text-color | var(--van-white) | - |
| --van-toast-loading-icon-color | var(--van-white) | - |
| --van-toast-line-height | var(--van-line-height-md) | - |
| --van-toast-border-radius | var(--van-border-radius-lg) | - |
| --van-toast-background-color | fade(var(--van-black), 70%) | - |
| --van-toast-icon-size | 36px | - |
| --van-toast-text-min-width | 96px | - |
| --van-toast-text-padding | var(--van-padding-xs) var(--van-padding-sm) | - |
| --van-toast-default-padding | var(--van-padding-md) | - |
| --van-toast-default-width | 88px | - |
| --van-toast-default-min-height | 88px | - |
| --van-toast-position-top-distance | 20% | - |
| --van-toast-position-bottom-distance | 20% | - |
日历组件用于选择日期或日期区间。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Calendar } from 'vant';const app = createApp();app.use(Calendar);下面演示了结合单元格来使用日历组件的用法，日期选择完成后会触发 confirm 事件。
<van-cell title="选择单个日期" :value="date" @click="show = true" /><van-calendar v-model:show="show" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const date = ref(''); const show = ref(false); const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`; const onConfirm = (value) => { show.value = false; date.value = formatDate(value); }; return { date, show, onConfirm, }; },};设置 type 为 multiple 后可以选择多个日期，此时 confirm 事件返回的 date 为数组结构，数组包含若干个选中的日期。
<van-cell title="选择多个日期" :value="text" @click="show = true" /><van-calendar v-model:show="show" type="multiple" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const text = ref(''); const show = ref(false); const onConfirm = (dates) => { show.value = false; text.value = `选择了 ${dates.length} 个日期`; }; return { text, show, onConfirm, }; },};设置 type 为 range 后可以选择日期区间，此时 confirm 事件返回的 date 为数组结构，数组第一项为开始时间，第二项为结束时间。
<van-cell title="选择日期区间" :value="date" @click="show = true" /><van-calendar v-model:show="show" type="range" @confirm="onConfirm" />import { ref } from 'vue';export default { setup() { const date = ref(''); const show = ref(false); const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`; const onConfirm = (values) => { const [start, end] = values; show.value = false; date.value = `${formatDate(start)} - ${formatDate(end)}`; }; return { date, show, onConfirm, }; },};Tips: 默认情况下，日期区间的起止时间不能为同一天，可以通过设置 allow-same-day 属性来允许选择同一天。
将 show-confirm 设置为 false 可以隐藏确认按钮，这种情况下选择完成后会立即触发 confirm 事件。
<van-calendar v-model:show="show" :show-confirm="false" />通过 color 属性可以自定义日历的颜色，对选中日期和底部按钮生效。
<van-calendar v-model:show="show" color="#1989fa" />通过 min-date 和 max-date 定义日历的范围。
<van-calendar v-model:show="show" :min-date="minDate" :max-date="maxDate" />import { ref } from 'vue';export default { setup() { const show = ref(false); return { show, minDate: new Date(2010, 0, 1), maxDate: new Date(2010, 0, 31), }; },};通过 confirm-text 设置按钮文字，通过 confirm-disabled-text 设置按钮禁用时的文字。
<van-calendar v-model:show="show" type="range" confirm-text="完成" confirm-disabled-text="请选择结束时间"/>通过传入 formatter 函数来对日历上每一格的内容进行格式化。
<van-calendar v-model:show="show" type="range" :formatter="formatter" />export default { setup() { const 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; }; return { formatter, }; },};通过 position 属性自定义弹出层的弹出位置，可选值为 top、left、right。
<van-calendar v-model:show="show" :round="false" position="right" />选择日期区间时，可以通过 max-range 属性来指定最多可选天数，选择的范围超过最多可选天数时，会弹出相应的提示文案。
<van-calendar type="range" :max-range="3" :style="{ height: '500px' }" />通过 first-day-of-week 属性设置一周从哪天开始。
<van-calendar first-day-of-week="1" />将 poppable 设置为 false，日历会直接展示在页面内，而不是以弹层的形式出现。
<van-calendar title="日历" :poppable="false" :show-confirm="false" :style="{ height: '500px' }"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 选择类型: single 表示选择单个日期， multiple 表示选择多个日期， range 表示选择日期区间 | string | single |
| title | 日历标题 | string | 日期选择 |
| color | 主题色，对底部按钮和选中日期生效 | string | #ee0a24 |
| min-date | 可选择的最小日期 | Date | 当前日期 |
| max-date | 可选择的最大日期 | Date | 当前日期的六个月后 |
| default-date | 默认选中的日期，type 为 multiple 或 range 时为数组，传入 null 表示默认不选择 | Date | Date[] | null | 今天 |
| row-height | 日期行高 | number | string | 64 |
| formatter | 日期格式化函数 | (day: Day) => Day | - |
| poppable | 是否以弹层的形式展示日历 | boolean | true |
| lazy-render | 是否只渲染可视区域的内容 | boolean | true |
| show-mark | 是否显示月份背景水印 | boolean | true |
| show-title | 是否展示日历标题 | boolean | true |
| show-subtitle | 是否展示日历副标题（年月） | boolean | true |
| show-confirm | 是否展示确认按钮 | boolean | true |
| readonly | 是否为只读状态，只读状态下不能选择日期 | boolean | false |
| confirm-text | 确认按钮的文字 | string | 确定 |
| confirm-disabled-text | 确认按钮处于禁用状态时的文字 | string | 确定 |
| first-day-of-week | 设置周起始日 | 0-6 | 0 |
当 Calendar 的 poppable 为 true 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示日历弹窗 | boolean | false |
| position | 弹出位置，可选值为 top right left | string | bottom |
| round | 是否显示圆角弹窗 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，用法示例 | string | Element | - |
当 Calendar 的 type 为 range 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| max-range | 日期区间最多可选天数 | number | string | 无限制 |
| range-prompt | 范围选择超过最多可选天数时的提示文案 | string | 选择天数不能超过 xx 天 |
| show-range-prompt | 范围选择超过最多可选天数时，是否展示提示文案 | boolean | true |
| allow-same-day | 是否允许日期范围的起止时间为同一天 | boolean | false |
当 Calendar 的 type 为 multiple 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| max-range | 日期最多可选天数 | number | string | 无限制 |
| range-prompt | 选择超过最多可选天数时的提示文案 | string | 选择天数不能超过 xx 天 |
日历中的每个日期都对应一个 Day 对象，通过formatter属性可以自定义 Day 对象的内容
| 键名 | 说明 | 类型 |
|---|---|---|
| date | 日期对应的 Date 对象 | Date |
| type | 日期类型，可选值为 selected、start、middle、end、disabled | string |
| text | 中间显示的文字 | string |
| topInfo | 上方的提示信息 | string |
| bottomInfo | 下方的提示信息 | string |
| className | 额外类名 | string |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击并选中任意日期时触发 | value: Date | Date[] |
| confirm | 日期选择完成后触发，若 show-confirm 为 true，则点击确认按钮后触发 | value: Date | Date[] |
| open | 打开弹出层时触发 | - |
| close | 关闭弹出层时触发 | - |
| opened | 打开弹出层且动画结束后触发 | - |
| closed | 关闭弹出层且动画结束后触发 | - |
| unselect | 当日历组件的 type 为 multiple 时，取消选中日期时触发 | value: Date |
| month-show | 当某个月份进入可视区域时触发 | { date: Date, title: string } |
| over-range | 范围选择超过最多可选天数时触发 | - |
click-subtitle v3.1.3 | 点击日历副标题时触发 | event: MouseEvent |
| 名称 | 说明 | 参数 |
|---|---|---|
| title | 自定义标题 | - |
subtitle v3.1.3 | 自定义日历副标题 | - |
| footer | 自定义底部区域内容 | - |
top-info v3.0.17 | 自定义日期上方的提示信息 | day: Day |
bottom-info v3.0.17 | 自定义日期下方的提示信息 | day: Day |
通过 ref 可以获取到 Calendar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| reset | 将选中的日期重置到指定日期，未传参时会重置到默认日期 | date?: Date | Date[] | - |
| scrollToDate | 滚动到某个日期 | date: Date | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-calendar-background-color | var(--van-white) | - |
| --van-calendar-popup-height | 80% | - |
| --van-calendar-header-box-shadow | 0 2px 10px rgba(125, 126, 128, 0.16) | - |
| --van-calendar-header-title-height | 44px | - |
| --van-calendar-header-title-font-size | var(--van-font-size-lg) | - |
| --van-calendar-header-subtitle-font-size | var(--van-font-size-md) | - |
| --van-calendar-weekdays-height | 30px | - |
| --van-calendar-weekdays-font-size | var(--van-font-size-sm) | - |
| --van-calendar-month-title-font-size | var(--van-font-size-md) | - |
| --van-calendar-month-mark-color | fade(var(--van-gray-2), 80%) | - |
| --van-calendar-month-mark-font-size | 160px | - |
| --van-calendar-day-height | 64px | - |
| --van-calendar-day-font-size | var(--van-font-size-lg) | - |
| --van-calendar-range-edge-color | var(--van-white) | - |
| --van-calendar-range-edge-background-color | var(--van-danger-color) | - |
| --van-calendar-range-middle-color | var(--van-danger-color) | - |
| --van-calendar-range-middle-background-opacity | 0.1 | - |
| --van-calendar-selected-day-size | 54px | - |
| --van-calendar-selected-day-color | var(--van-white) | - |
| --van-calendar-info-font-size | var(--van-font-size-xs) | - |
| --van-calendar-info-line-height | var(--van-line-height-xs) | - |
| --van-calendar-selected-day-background-color | var(--van-danger-color) | - |
| --van-calendar-day-disabled-color | var(--van-gray-5) | - |
| --van-calendar-confirm-button-height | 36px | - |
| --van-calendar-confirm-button-margin | 7px 0 | - |
如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
级联选择框，用于多层级数据的选择，典型场景为省市区选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Cascader } from 'vant';const app = createApp();app.use(Cascader);级联选择组件可以搭配 Field 和 Popup 组件使用，示例如下：
<van-field v-model="state.fieldValue" is-link readonly label="地区" placeholder="请选择所在地区" @click="state.show = true"/><van-popup v-model:show="state.show" round position="bottom"> <van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="options" @close="state.show = false" @finish="onFinish" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, fieldValue: '', cascaderValue: '', }); // 选项列表，children 代表子选项，支持多级嵌套 const options = [ { text: '浙江省', value: '330000', children: [{ text: '杭州市', value: '330100' }], }, { text: '江苏省', value: '320000', children: [{ text: '南京市', value: '320100' }], }, ]; // 全部选项选择完毕后，会触发 finish 事件 const onFinish = ({ selectedOptions }) => { state.show = false; state.fieldValue = selectedOptions.map((option) => option.text).join('/'); }; return { state, options, onFinish, }; },};通过 active-color 属性来设置选中状态的高亮颜色。
<van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="options" active-color="#1989fa" @close="state.show = false" @finish="onFinish"/>可以监听 change 事件并动态设置 options，实现异步加载选项。
<van-field v-model="state.fieldValue" is-link readonly label="地区" placeholder="请选择所在地区" @click="state.show = true"/><van-popup v-model:show="state.show" round position="bottom"> <van-cascader v-model="state.cascaderValue" title="请选择所在地区" :options="state.options" @close="state.show = false" @change="onChange" @finish="onFinish" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, fieldValue: '', cascaderValue: '', options: [ { text: '浙江省', value: '330000', children: [], }, ], }); const onChange = ({ value }) => { if (value === state.options[0].value) { setTimeout(() => { state.options[0].children = [ { text: '杭州市', value: '330100' }, { text: '宁波市', value: '330200' }, ]; }, 500); } }; const onFinish = ({ selectedOptions }) => { state.show = false; state.fieldValue = selectedOptions.map((option) => option.text).join('/'); }; return { state, onChange, onFinish, }; },};通过 field-names 属性可以自定义 options 里的字段名称。
<van-cascader v-model="code" title="请选择所在地区" :options="options" :field-names="fieldNames"/>import { ref } from 'vue';export default { setup() { const code = ref(''); const fieldNames = { text: 'name', value: 'code', children: 'items', }; const options = [ { name: '浙江省', code: '330000', items: [{ name: '杭州市', code: '330100' }], }, { name: '江苏省', code: '320000', items: [{ name: '南京市', code: '320100' }], }, ]; return { code, options, fieldNames, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 顶部标题 | string | - |
| value | 选中项的值 | string | number | - |
| options | 可选项数据源 | Option[] | [] |
| placeholder | 未选中时的提示文案 | string | 请选择 |
| active-color | 选中状态的高亮颜色 | string | #ee0a24 |
swipeable v3.0.11 | 是否开启手势左右滑动切换 | boolean | false |
| closeable | 是否显示关闭图标 | boolean | true |
close-icon v3.0.10 | 关闭图标名称或图片链接 | string | cross |
field-names v3.0.4 | 自定义 options 结构中的字段 | object | { text: 'text', value: 'value', children: 'children' } |
options 属性是一个由对象构成的数组，数组中的每个对象配置一个可选项，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 选项文字（必填） | string |
| value | 选项对应的值（必填） | string | number |
color v3.1.0 | 选项文字颜色 | string |
| children | 子选项列表 | Option[] |
disabled v3.1.2 | 是否禁用选项 | boolean |
className v3.1.0 | 为对应列添加额外的 class | string | Array | object |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| change | 选中项变化时触发 | { value, selectedOptions, tabIndex } |
| finish | 全部选项选择完成后触发 | { value, selectedOptions, tabIndex } |
| close | 点击关闭图标时触发 | - |
| click-tab | 点击标签时触发 | tabIndex: number, title: string |
| 名称 | 说明 | 参数 |
|---|---|---|
| title | 自定义顶部标题 | - |
option v3.1.4 | 自定义选项文字 | { option: Option, selected: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-cascader-header-height | 48px | - |
| --van-cascader-header-padding | 0 var(--van-padding-md) | - |
| --van-cascader-title-font-size | var(--van-font-size-lg) | - |
| --van-cascader-title-line-height | 20px | - |
| --van-cascader-close-icon-size | 22px | - |
| --van-cascader-close-icon-color | var(--van-gray-5) | - |
| --van-cascader-close-icon-active-color | var(--van-gray-6) | - |
| --van-cascader-selected-icon-size | 18px | - |
| --van-cascader-tabs-height | 48px | - |
| --van-cascader-active-color | var(--van-danger-color) | - |
| --van-cascader-options-height | 384px | - |
| --van-cascader-option-disabled-color | van(--van-gray-5) | - |
| --van-cascader-tab-color | var(--van-text-color) | - |
| --van-cascader-unselected-tab-color | var(--van-gray-6) | - |
在一组备选项中进行多选。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Checkbox, CheckboxGroup } from 'vant';const app = createApp();app.use(Checkbox);app.use(CheckboxGroup);通过 v-model 绑定复选框的勾选状态。
<van-checkbox v-model="checked">复选框</van-checkbox>import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked }; },};通过设置 disabled 属性可以禁用复选框。
<van-checkbox v-model="checked" disabled>复选框</van-checkbox>将 shape 属性设置为 square，复选框的形状会变成方形。
<van-checkbox v-model="checked" shape="square">复选框</van-checkbox>通过 checked-color 属性设置选中状态的图标颜色。
<van-checkbox v-model="checked" checked-color="#ee0a24">复选框</van-checkbox>通过 icon-size 属性可以自定义图标的大小。
<van-checkbox v-model="checked" icon-size="24px">复选框</van-checkbox>通过 icon 插槽自定义图标，可以通过 slotProps 判断是否为选中状态.
<van-checkbox v-model="checked"> 自定义图标 <template #icon="props"> <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" /> </template></van-checkbox><style> .img-icon { height: 20px; }</style>import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked, activeIcon: 'https://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png', }; },};设置 label-disabled 属性后，点击图标以外的内容不会触发复选框切换。
<van-checkbox v-model="checked" label-disabled>复选框</van-checkbox>复选框可以与复选框组一起使用，复选框组通过 v-model 数组绑定复选框的勾选状态。
<van-checkbox-group v-model="checked"> <van-checkbox name="a">复选框 a</van-checkbox> <van-checkbox name="b">复选框 b</van-checkbox></van-checkbox-group>import { ref } from 'vue';export default { setup() { const checked = ref(['a', 'b']); return { checked }; },};将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。
<van-checkbox-group v-model="checked" direction="horizontal"> <van-checkbox name="a">复选框 a</van-checkbox> <van-checkbox name="b">复选框 b</van-checkbox></van-checkbox-group>import { ref } from 'vue';export default { setup() { const checked = ref([]); return { checked }; },};通过 max 属性可以限制复选框组的最大可选数。
<van-checkbox-group v-model="checked" :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="checked" 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="primary" @click="toggleAll">反选</van-button>import { ref } from 'vue';export default { setup() { const checked = ref([]); const checkboxGroup = ref(null); const checkAll = () => { checkboxGroup.value.toggleAll(true); } const toggleAll = () => { checkboxGroup.value.toggleAll(); }, return { checked, checkAll, toggleAll, checkboxGroup, }; },};此时你需要再引入 Cell 和 CellGroup 组件，并通过 Checkbox 实例上的 toggle 方法触发切换。
<van-checkbox-group v-model="checked"> <van-cell-group> <van-cell v-for="(item, index) in list" clickable :key="item" :title="`复选框 ${item}`" @click="toggle(index)" > <template #right-icon> <van-checkbox :name="item" :ref="el => checkboxRefs[index] = el" @click.stop /> </template> </van-cell> </van-cell-group></van-checkbox-group>import { ref, onBeforeUpdate } from 'vue';export default { setup() { const checked = ref([]); const checkboxRefs = ref([]); const toggle = (index) => { checkboxRefs.value[index].toggle(); }; onBeforeUpdate(() => { checkboxRefs.value = []; }); return { list: ['a', 'b'], toggle, checked, checkboxRefs, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 是否为选中状态 | boolean | false |
| name | 标识符 | any | - |
| shape | 形状，可选值为 square | string | round |
| disabled | 是否禁用复选框 | boolean | false |
| label-disabled | 是否禁用复选框文本点击 | boolean | false |
| label-position | 文本位置，可选值为 left | string | right |
| icon-size | 图标大小，默认单位为 px | number | string | 20px |
| checked-color | 选中状态颜色 | string | #1989fa |
| bind-group | 是否与复选框组绑定 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 所有选中项的标识符 | any[] | - |
| disabled | 是否禁用所有复选框 | boolean | false |
| max | 最大可选数，0 为无限制 | number | string | 0 |
| direction | 排列方向，可选值为 horizontal | string | vertical |
| icon-size | 所有复选框的图标大小，默认单位为 px | number | string | 20px |
| checked-color | 所有复选框的选中状态颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | checked: boolean |
| click | 点击复选框时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | names: any[] |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义文本 | - |
| icon | 自定义图标 | { checked: boolean, disabled: boolean } |
通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggleAll | 切换所有复选框，传 true 为选中，false 为取消选中，不传参为取反 | options?: boolean | object | - |
const { checkboxGroup } = this.$refs;// 全部反选checkboxGroup.toggleAll();// 全部选中checkboxGroup.toggleAll(true);// 全部取消checkboxGroup.toggleAll(false);// 全部反选，并跳过禁用的复选框checkboxGroup.toggleAll({ skipDisabled: true,});// 全部选中，并跳过禁用的复选框checkboxGroup.toggleAll({ checked: true, skipDisabled: true,});通过 ref 可以获取到 Checkbox 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换选中状态，传 true 为选中，false 为取消选中，不传参为取反 | checked?: boolean | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-checkbox-size | 20px | - |
| --van-checkbox-border-color | var(--van-gray-5) | - |
| --van-checkbox-transition-duration | var(--van-animation-duration-fast) | - |
| --van-checkbox-label-margin | var(--van-padding-xs) | - |
| --van-checkbox-label-color | var(--van-text-color) | - |
| --van-checkbox-checked-icon-color | var(--van-primary-color) | - |
| --van-checkbox-disabled-icon-color | var(--van-gray-5) | - |
| --van-checkbox-disabled-label-color | var(--van-gray-5) | - |
| --van-checkbox-disabled-background-color | var(--van-border-color) | - |
时间选择器，支持日期、年月、时分等维度，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { DatetimePicker } from 'vant';const app = createApp();app.use(DatetimePicker);DatetimePicker 通过 type 属性来定义需要选择的时间类型，type 为 date 表示选择年月日。通过 min-date 和 max-date 属性可以确定可选的时间范围。
<van-datetime-picker v-model="currentDate" type="date" title="选择年月日" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date(2021, 0, 17)); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};将 type 设置为 year-month 即可选择年份和月份。通过传入 formatter 函数，可以对选项文字进行格式化处理。
<van-datetime-picker v-model="currentDate" type="year-month" title="选择年月" :min-date="minDate" :max-date="maxDate" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'year') { return `${val}年`; } if (type === 'month') { return `${val}月`; } return val; }; return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), formatter, currentDate, }; },};将 type 设置为 month-day 即可选择月份和日期。
<van-datetime-picker v-model="currentDate" type="month-day" title="选择月日" :min-date="minDate" :max-date="maxDate" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'month') { return `${val}月`; } if (type === 'day') { return `${val}日`; } return val; }; return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), formatter, currentDate, }; },};将 type 设置为 time 即可选择时间（小时和分钟）。
<van-datetime-picker v-model="currentTime" type="time" title="选择时间" :min-hour="10" :max-hour="20"/>import { ref } from 'vue';export default { setup() { const currentTime = ref('12:00'); return { currentTime }; },};将 type 设置为 datetime 即可选择完整时间，包括年月日和小时、分钟。
<van-datetime-picker v-model="currentDate" type="datetime" title="选择完整时间" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};将 type 设置为 datehour 即可选择日期和小时，包括年月日和小时。
<van-datetime-picker v-model="currentDate" type="datehour" title="选择年月日小时" :min-date="minDate" :max-date="maxDate"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); return { minDate: new Date(2020, 0, 1), maxDate: new Date(2025, 10, 1), currentDate, }; },};通过传入 filter 函数，可以对选项数组进行过滤，实现自定义时间间隔。
<van-datetime-picker v-model="currentTime" type="time" :filter="filter" />import { ref } from 'vue';export default { setup() { const currentTime = ref('12:00'); const filter = (type, options) => { if (type === 'minute') { return options.filter((option) => Number(option) % 5 === 0); } return options; }; return { filter, currentTime, }; },};
<van-datetime-picker v-model="currentDate" type="date" title="自定义列排序" :columns-order="['month', 'day', 'year']" :formatter="formatter"/>import { ref } from 'vue';export default { setup() { const currentDate = ref(new Date()); const formatter = (type, val) => { if (type === 'year') { return val + '年'; } if (type === 'month') { return val + '月'; } if (type === 'day') { return val + '日'; } return val; }; return { formatter, currentDate, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 时间类型，可选值为 date timeyear-month month-day datehour | string | datetime |
| title | 顶部栏标题 | string | '' |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| show-toolbar | 是否显示顶部栏 | boolean | true |
| loading | 是否显示加载状态 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法切换选项 | boolean | false |
| filter | 选项过滤函数 | (type: string, values: string[]) => string[] | - |
| formatter | 选项格式化函数 | (type: string, value: string) => string | - |
| columns-order | 自定义列排序数组, 子项可选值为 year、month、day、hour、minute | string[] | - |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位ms | number | string | 1000 |
当时间选择器类型为 date 或 datetime 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| min-date | 可选的最小时间，精确到分钟 | Date | 十年前 |
| max-date | 可选的最大时间，精确到分钟 | Date | 十年后 |
当时间选择器类型为 time 时，支持以下 props:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| min-hour | 可选的最小小时 | number | string | 0 |
| max-hour | 可选的最大小时 | number | string | 23 |
| min-minute | 可选的最小分钟 | number | string | 0 |
| max-minute | 可选的最大分钟 | number | string | 59 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当值变化时触发的事件 | value: 当前选中的时间 |
| confirm | 点击完成按钮时触发的事件 | value: 当前选中的时间 |
| cancel | 点击取消按钮时触发的事件 | - |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | option: string | object |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
通过 ref 可以获取到 DatetimePicker 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| getPicker | 获取 Picker 实例，用于调用 Picker 的实例方法 | - | - |
请注意不要在模板中直接使用类似min-date="new Date()"的写法，这样会导致每次渲染组件时传入一个新的 Date 对象，而传入新的数据会触发下一次渲染，从而陷入死循环。
正确的做法是将min-date作为一个数据定义在data函数中。
如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
参见桌面端适配。
如果仅需要选择年份或者月份，建议直接使用 Picker 组件。
用户可以在文本框内输入或编辑文字。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Field, CellGroup } from 'vant';const app = createApp();app.use(Field);app.use(CellGroup);可以通过 v-model 双向绑定输入框的值，通过 placeholder 设置占位提示文字。
<!-- 可以使用 CellGroup 作为容器 --><van-cell-group inset> <van-field v-model="value" label="文本" placeholder="请输入用户名" /></van-cell-group>import { ref } from 'vue';export default { setup() { const value = ref(''); return { value }; },};根据 type 属性定义不同类型的输入框，默认值为 text。
<van-cell-group inset> <!-- 输入任意文本 --> <van-field v-model="state.text" label="文本" /> <!-- 输入手机号，调起手机号键盘 --> <van-field v-model="state.tel" type="tel" label="手机号" /> <!-- 允许输入正整数，调起纯数字键盘 --> <van-field v-model="state.digit" type="digit" label="整数" /> <!-- 允许输入数字，调起带符号的纯数字键盘 --> <van-field v-model="state.number" type="number" label="数字" /> <!-- 输入密码 --> <van-field v-model="state.password" type="password" label="密码" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ tel: '', text: '', digit: '', number: '', password: '', }); return { state }; },};通过 readonly 将输入框设置为只读状态，通过 disabled 将输入框设置为禁用状态。
<van-cell-group inset> <van-field label="文本" model-value="输入框只读" readonly /> <van-field label="文本" model-value="输入框已禁用" disabled /></van-cell-group>通过 left-icon 和 right-icon 配置输入框两侧的图标，通过设置 clearable 在输入过程中展示清除图标。
<van-cell-group inset> <van-field v-model="state.value1" label="文本" left-icon="smile-o" right-icon="warning-o" placeholder="显示图标" /> <van-field v-model="state.value2" clearable label="文本" left-icon="music-o" placeholder="显示清除图标" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: '', value2: '123', }); return { state }; },};设置 required 属性表示这是一个必填项，可以配合 error 或 error-message 属性显示对应的错误提示。
<van-cell-group inset> <van-field v-model="username" error required label="用户名" placeholder="请输入用户名" /> <van-field v-model="phone" required label="手机号" placeholder="请输入手机号" error-message="手机号格式错误" /></van-cell-group>通过 button 插槽可以在输入框尾部插入按钮。
<van-cell-group inset> <van-field v-model="sms" center clearable label="短信验证码" placeholder="请输入短信验证码" > <template #button> <van-button size="small" type="primary">发送验证码</van-button> </template> </van-field></van-cell-group>通过 formatter 属性可以对输入的内容进行格式化，通过 format-trigger 属性可以指定执行格式化的时机，默认在输入时进行格式化。
<van-cell-group inset> <van-field v-model="state.value1" label="文本" :formatter="formatter" placeholder="在输入时执行格式化" /> <van-field v-model="state.value2" label="文本" :formatter="formatter" format-trigger="onBlur" placeholder="在失焦时执行格式化" /></van-cell-group>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: '', value2: '', }); // 过滤输入的数字 const formatter = (value) => value.replace(/d/g, ''); return { state, formatter, }; },};对于 textarea，可以通过 autosize 属性设置高度自适应。
<van-cell-group inset> <van-field v-model="message" rows="1" autosize label="留言" type="textarea" placeholder="请输入留言" /></van-cell-group>设置 maxlength 和 show-word-limit 属性后会在底部显示字数统计。
<van-cell-group inset> <van-field v-model="message" rows="2" autosize label="留言" type="textarea" maxlength="50" placeholder="请输入留言" show-word-limit /></van-cell-group>通过 input-align 属性可以设置输入框内容的对齐方式，可选值为 center、right。
<van-cell-group inset> <van-field v-model="value" label="文本" placeholder="输入框内容右对齐" input-align="right" /></van-cell-group>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入的值 | number | string | - |
| label | 输入框左侧文本 | string | - |
| name | 名称，提交表单的标识符 | string | - |
| type | 输入框类型, 可选值为 tel digitnumber textarea password 等 | string | text |
| size | 大小，可选值为 large | string | - |
| maxlength | 输入的最大字符数 | number | string | - |
| placeholder | 输入框占位提示文字 | string | - |
| border | 是否显示内边框 | boolean | true |
| disabled | 是否禁用输入框 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法输入内容 | boolean | false |
| colon | 是否在 label 后面添加冒号 | boolean | false |
| required | 是否显示表单必填星号 | boolean | false |
| center | 是否使内容垂直居中 | boolean | false |
| clearable | 是否启用清除图标，点击清除图标后会清空输入框 | boolean | false |
clear-icon v3.0.12 | 清除图标名称或图片链接 | string | clear |
| clear-trigger | 显示清除图标的时机，always 表示输入框不为空时展示， focus 表示输入框聚焦且不为空时展示 | string | focus |
| clickable | 是否开启点击反馈 | boolean | false |
| is-link | 是否展示右侧箭头并开启点击反馈 | boolean | false |
| autofocus | 是否自动聚焦，iOS 系统不支持该属性 | boolean | false |
| show-word-limit | 是否显示字数统计，需要设置 maxlength 属性 | boolean | false |
| error | 是否将输入内容标红 | boolean | false |
| error-message | 底部错误提示文案，为空时不展示 | string | - |
| error-message-align | 错误提示文案对齐方式，可选值为 center right | string | left |
| formatter | 输入内容格式化函数 | (val: string) => string | - |
| format-trigger | 格式化函数触发的时机，可选值为 onBlur | string | onChange |
| arrow-direction | 箭头方向，可选值为 left up down | string | right |
| label-class | 左侧文本额外类名 | string | Array | object | - |
| label-width | 左侧文本宽度，默认单位为 px | number | string | 6.2em |
| label-align | 左侧文本对齐方式，可选值为 center right | string | left |
| input-align | 输入框对齐方式，可选值为 center right | string | left |
| autosize | 是否自适应内容高度，只对 textarea 有效， 可传入对象,如 { maxHeight: 100, minHeight: 50 }， 单位为 px | boolean | object | false |
| left-icon | 左侧图标名称或图片链接 | string | - |
| right-icon | 右侧图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| rules | 表单校验规则，详见 Form 组件 | Rule[] | - |
autocomplete v3.0.3 | input 标签原生的自动完成属性 | string | - |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 输入框内容变化时触发 | value: string (当前输入的值) |
| focus | 输入框获得焦点时触发 | event: Event |
| blur | 输入框失去焦点时触发 | event: Event |
| clear | 点击清除按钮时触发 | event: MouseEvent |
| click | 点击组件时触发 | event: MouseEvent |
| click-input | 点击输入区域时触发 | event: MouseEvent |
| click-left-icon | 点击左侧图标时触发 | event: MouseEvent |
| click-right-icon | 点击右侧图标时触发 | event: MouseEvent |
通过 ref 可以获取到 Field 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 获取输入框焦点 | - | - |
| blur | 取消输入框焦点 | - | - |
| 名称 | 说明 |
|---|---|
| label | 自定义输入框左侧文本 |
| input | 自定义输入框，使用此插槽后，与输入框相关的属性和事件将失效。 在 Form 组件进行表单校验时，会使用 input 插槽中子组件的 value，而不是 Field 组件的 value。 |
| left-icon | 自定义输入框头部图标 |
| right-icon | 自定义输入框尾部图标 |
| button | 自定义输入框尾部按钮 |
| extra | 自定义输入框最右侧的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-field-label-width | 6.2em | - |
| --van-field-label-color | var(--van-gray-7) | - |
| --van-field-label-margin-right | var(--van-padding-sm) | - |
| --van-field-input-text-color | var(--van-text-color) | - |
| --van-field-input-error-text-color | var(--van-danger-color) | - |
| --van-field-input-disabled-text-color | var(--van-gray-5) | - |
| --van-field-placeholder-text-color | var(--van-gray-5) | - |
| --van-field-icon-size | 16px | - |
| --van-field-clear-icon-size | 16px | - |
| --van-field-clear-icon-color | var(--van-gray-5) | - |
| --van-field-right-icon-color | var(--van-gray-6) | - |
| --van-field-error-message-color | var(--van-danger-color) | - |
| --van-field-error-message-text-color | 12px | - |
| --van-field-text-area-min-height | 60px | - |
| --van-field-word-limit-color | var(--van-gray-7) | - |
| --van-field-word-limit-font-size | var(--van-font-size-sm) | - |
| --van-field-word-limit-line-height | 16px | - |
| --van-field-disabled-text-color | var(--van-gray-5) | - |
| --van-field-required-mark-color | var(--van-red) | - |
HTML 原生的 type="number" 属性在 iOS 和 Android 系统上都存在一定问题，比如 maxlength 属性不生效、无法获取到完整的输入内容等。因此设置 type 为 number 时，Field 不会使用原生的 type="number" 属性，而是用现代浏览器支持的 inputmode 属性来控制输入键盘的类型。
清除按钮监听是的移动端 Touch 事件，参见桌面端适配。
用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型，需要与 Field 输入框 组件搭配使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Form, Field, CellGroup } from 'vant';const app = createApp();app.use(Form);app.use(Field);app.use(CellGroup);在表单中，每个 Field 组件 代表一个表单项，使用 Field 的 rules 属性定义校验规则。
<van-form @submit="onSubmit"> <van-cell-group inset> <van-field v-model="state.username" name="用户名" label="用户名" placeholder="用户名" :rules="[{ required: true, message: '请填写用户名' }]" /> <van-field v-model="state.password" type="password" name="密码" label="密码" placeholder="密码" :rules="[{ required: true, message: '请填写密码' }]" /> </van-cell-group> <div style="margin: 16px;"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div></van-form>import { reactive } from 'vue';export default { setup() { const state = reactive({ username: '', password: '', }); const onSubmit = (values) => { console.log('submit', values); }; return { state, onSubmit, }; },};通过 rules 定义表单校验规则，所有可用字段见下方表格。
<van-form @failed="onFailed"> <van-cell-group inset> <!-- 通过 pattern 进行正则校验 --> <van-field v-model="state.value1" name="pattern" placeholder="正则校验" :rules="[{ pattern, message: '请输入正确内容' }]" /> <!-- 通过 validator 进行函数校验 --> <van-field v-model="state.value2" name="validator" placeholder="函数校验" :rules="[{ validator, message: '请输入正确内容' }]" /> <!-- 通过 validator 返回错误提示 --> <van-field v-model="state.value3" name="validatorMessage" placeholder="校验函数返回错误提示" :rules="[{ validator: validatorMessage }]" /> <!-- 通过 validator 进行异步函数校验 --> <van-field v-model="state.value4" name="asyncValidator" placeholder="异步函数校验" :rules="[{ validator: asyncValidator, message: '请输入正确内容' }]" /> </van-cell-group> <div style="margin: 16px;"> <van-button round block type="primary" native-type="submit"> 提交 </van-button> </div></van-form>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ value1: '', value2: '', value3: '', value4: '', }); const pattern = /d{6}/; // 校验函数返回 true 表示校验通过，false 表示不通过 const validator = (val) => /1d{10}/.test(val); // 校验函数可以直接返回一段错误提示 const validatorMessage = (val) => `${val} 不合法，请重新输入`; // 校验函数可以返回 Promise，实现异步校验 const asyncValidator = (val) => new Promise((resolve) => { Toast.loading('验证中...'); setTimeout(() => { Toast.clear(); resolve(/d{6}/.test(val)); }, 1000); }); const onFailed = (errorInfo) => { console.log('failed', errorInfo); }; return { state, pattern, onFailed, validator, asyncValidator, }; },};在表单中使用 Switch 组件。
<van-field name="switch" label="开关"> <template #input> <van-switch v-model="checked" size="20" /> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref(false); return { checked }; },};在表单中使用 Checkbox 组件。
<van-field name="checkbox" label="复选框"> <template #input> <van-checkbox v-model="checked" shape="square" /> </template></van-field><van-field name="checkboxGroup" label="复选框组"> <template #input> <van-checkbox-group v-model="groupChecked" direction="horizontal"> <van-checkbox name="1" shape="square">复选框 1</van-checkbox> <van-checkbox name="2" shape="square">复选框 2</van-checkbox> </van-checkbox-group> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref(false); const groupChecked = ref([]); return { checked, groupChecked, }; },};在表单中使用 Radio 组件。
<van-field name="radio" label="单选框"> <template #input> <van-radio-group v-model="checked" direction="horizontal"> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio> </van-radio-group> </template></van-field>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked }; },};在表单中使用 Stepper 组件。
<van-field name="stepper" label="步进器"> <template #input> <van-stepper v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(1); return { value }; },};在表单中使用 Rate 组件。
<van-field name="rate" label="评分"> <template #input> <van-rate v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(3); return { value }; },};在表单中使用 Slider 组件。
<van-field name="slider" label="滑块"> <template #input> <van-slider v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref(50); return { value }; },};在表单中使用 Uploader 组件。
<van-field name="uploader" label="文件上传"> <template #input> <van-uploader v-model="value" /> </template></van-field>import { ref } from 'vue';export default { setup() { const value = ref([{ url: 'https://img.yzcdn.cn/vant/leaf.jpg' }]); return { value }; },};在表单中使用 Picker 组件。
<van-field v-model="state.value" readonly clickable name="picker" label="选择器" placeholder="点击选择城市" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" position="bottom"> <van-picker :columns="columns" @confirm="onConfirm" @cancel="state.showPicker = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showPicker: false, }); const columns = ['杭州', '宁波', '温州', '嘉兴', '湖州']; const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, columns, onConfirm, }; },};在表单中使用 DatetimePicker 组件。
<van-field v-model="state.value" readonly clickable name="datetimePicker" label="时间选择" placeholder="点击选择时间" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" position="bottom"> <van-datetime-picker type="time" @confirm="onConfirm" @cancel="state.showPicker = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showPicker: false, }); const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, onConfirm, }; },};在表单中使用 Area 组件。
<van-field v-model="state.value" readonly clickable name="area" label="地区选择" placeholder="点击选择省市区" @click="state.showArea = true"/><van-popup v-model:show="state.showArea" position="bottom"> <van-area :area-list="areaList" @confirm="onConfirm" @cancel="state.showArea = false" /></van-popup>import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showArea: false, }); const onConfirm = (value) => { state.showArea = false; state.value = values .filter((item) => !!item) .map((item) => item.name) .join('/'); }; return { state, areaList: {}, // 数据格式见 Area 组件文档 onConfirm, }; },};在表单中使用 Calendar 组件。
<van-field v-model="state.value" readonly clickable name="calendar" label="日历" placeholder="点击选择日期" @click="state.showCalendar = true"/><van-calendar v-model:show="state.showCalendar" @confirm="onConfirm" />import { reactive } from 'vue';export default { setup() { const state = reactive({ value: '', showCalendar: false, }); const onConfirm = (date) => { state.value = `${date.getMonth() + 1}/${date.getDate()}`; state.showCalendar = false; }; return { state, onConfirm, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label-width | 表单项 label 宽度，默认单位为px | number | string | 6.2em |
| label-align | 表单项 label 对齐方式，可选值为 center right | string | left |
| input-align | 输入框对齐方式，可选值为 center right | string | left |
| error-message-align | 错误提示文案对齐方式，可选值为 center right | string | left |
| validate-trigger | 表单校验触发时机，可选值为 onChange、onSubmit，详见下表 | string | onBlur |
| colon | 是否在 label 后面添加冒号 | boolean | false |
| disabled | 是否禁用表单中的所有输入框 | boolean | false |
| readonly | 是否将表单中的所有输入框设置为只读状态 | boolean | false |
| validate-first | 是否在某一项校验不通过时停止校验 | boolean | false |
| scroll-to-error | 是否在提交表单且校验不通过时滚动至错误的表单项 | boolean | false |
| show-error | 是否在校验不通过时标红输入框 | boolean | false |
| show-error-message | 是否在校验不通过时在输入框下方展示错误提示 | boolean | true |
| submit-on-enter | 是否在按下回车键时提交表单 | boolean | true |
表单项的 API 参见：Field 组件
使用 Field 的rules属性可以定义校验规则，可选属性如下:
| 键名 | 说明 | 类型 |
|---|---|---|
| required | 是否为必选字段 | boolean |
| message | 错误提示文案 | string | (value, rule) => string |
| validator | 通过函数进行校验 | (value, rule) => boolean | string | Promise |
| pattern | 通过正则表达式进行校验 | RegExp |
| trigger | 本项规则的触发时机，可选值为 onChange、onBlur | string |
| formatter | 格式化函数，将表单项的值转换后进行校验 | (value, rule) => any |
通过 validate-trigger 属性可以自定义表单校验的触发时机。
| 值 | 描述 |
|---|---|
| onSubmit | 仅在提交表单时触发校验 |
| onBlur | 在提交表单和输入框失焦时触发校验 |
| onChange | 在提交表单和输入框内容变化时触发校验 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| submit | 提交表单且验证通过后触发 | values: object |
| failed | 提交表单且验证不通过后触发 | errorInfo: { values: object, errors: object[] } |
通过 ref 可以获取到 Form 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| submit | 提交表单，与点击提交按钮的效果等价 | - | - |
| validate | 验证表单，支持传入 name 来验证单个或部分表单项 | name?: string | string[] | Promise |
| resetValidation | 重置表单项的验证提示，支持传入 name 来重置单个或部分表单项 | name?: string | string[] | - |
| scrollToField | 滚动到对应表单项的位置，默认滚动到顶部，第二个参数传 false 可滚动至底部 | name: string, alignToTop: boolean | - |
| 名称 | 说明 |
|---|---|
| default | 表单内容 |
虚拟数字键盘，可以配合密码输入框组件或自定义的输入框组件使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NumberKeyboard } from 'vant';const app = createApp();app.use(NumberKeyboard);数字键盘提供了 input、delete、blur 事件，分别对应输入内容、删除内容和失去焦点的动作。
<van-cell @touchstart.stop="show = true">弹出默认键盘</van-cell><van-number-keyboard :show="show" @blur="show = false" @input="onInput" @delete="onDelete"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(true); const onInput = (value) => Toast(value); const onDelete = () => Toast('删除'); return { show, onInput, onDelete, }; },};点击键盘以外的区域时，键盘会自动收起，通过阻止元素上的 touchstart 事件冒泡可以避免键盘收起。
将 theme 属性设置为 custom 来展示键盘的右侧栏，常用于输入金额的场景。
<van-number-keyboard :show="show" theme="custom" extra-key="." close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 extra-key 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 extra-key 设置为 X。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出身份证号键盘</van-cell><van-number-keyboard :show="show" extra-key="X" close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 title 属性可以设置键盘标题。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出带标题的键盘</van-cell><van-number-keyboard :show="show" title="键盘标题" extra-key="." close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>当 theme 为 custom 时，支持以数组的形式配置两个 extra-key。
<van-cell plain type="primary" @touchstart.stop="show = true"> 弹出配置多个按键的键盘</van-cell><van-number-keyboard :show="show" :extra-key="['00', '.']" close-button-text="完成" @blur="show = false" @input="onInput" @delete="onDelete"/>通过 random-key-order 属性可以随机排序数字键盘，常用于安全等级较高的场景。
<van-cell @touchstart.stop="show = true"> 弹出配置随机数字的键盘 </van-cell><van-number-keyboard :show="show" random-key-order @blur="show = false" @input="onInput" @delete="onDelete"/>可以通过 v-model 绑定键盘当前输入值，并通过 maxlength 属性来限制输入长度。
<van-field v-model="value" readonly clickable @touchstart.stop="show = true" /><van-number-keyboard v-model="value" :show="show" :maxlength="6" @blur="show = false"/>import { ref } from 'vue';export default { setup() { const show = ref(true); const value = ref(''); return { show, value, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入值 | string | - |
| show | 是否显示键盘 | boolean | - |
| title | 键盘标题 | string | - |
| theme | 样式风格，可选值为 custom | string | default |
| maxlength | 输入值最大长度 | number | string | - |
| transition | 是否开启过场动画 | boolean | true |
| z-index | 键盘 z-index 层级 | number | string | 100 |
| extra-key | 底部额外按键的内容 | string | string[] | '' |
| close-button-text | 关闭按钮文字，空则不展示 | string | - |
| delete-button-text | 删除按钮文字，空则展示删除图标 | string | - |
| close-button-loading | 是否将关闭按钮设置为加载中状态，仅在 theme="custom" 时有效 | boolean | false |
| show-delete-key | 是否展示删除图标 | boolean | true |
blur-on-close v3.0.6 | 是否在点击关闭按钮时触发 blur 事件 | boolean | true |
| hide-on-click-outside | 是否在点击外部时收起键盘 | boolean | true |
| teleport | 指定挂载的节点，用法示例 | string | Element | - |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| random-key-order | 是否将通过随机顺序展示按键 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| input | 点击按键时触发 | key: 按键内容 |
| delete | 点击删除键时触发 | - |
| close | 点击关闭按钮时触发 | - |
| blur | 点击关闭按钮或非键盘区域时触发 | - |
| show | 键盘完全弹出时触发 | - |
| hide | 键盘完全收起时触发 | - |
| 名称 | 说明 |
|---|---|
| delete | 自定义删除按键内容 |
| extra-key | 自定义左下角按键内容 |
| title-left | 自定义标题栏左侧内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-number-keyboard-background-color | var(--van-gray-2) | - |
| --van-number-keyboard-key-height | 48px | - |
| --van-number-keyboard-key-font-size | 28px | - |
| --van-number-keyboard-key-active-color | var(--van-gray-3) | - |
| --van-number-keyboard-delete-font-size | var(--van-font-size-lg) | - |
| --van-number-keyboard-title-color | var(--van-gray-7) | - |
| --van-number-keyboard-title-height | 34px | - |
| --van-number-keyboard-title-font-size | var(--van-font-size-lg) | - |
| --van-number-keyboard-close-padding | 0 var(--van-padding-md) | - |
| --van-number-keyboard-close-color | var(--van-text-link-color) | - |
| --van-number-keyboard-close-font-size | var(--van-font-size-md) | - |
| --van-number-keyboard-button-text-color | var(--van-white) | - |
| --van-number-keyboard-button-background-color | var(--van-primary-color) | - |
| --van-number-keyboard-z-index | 100 | - |
参见桌面端适配。
带网格的输入框组件，可以用于输入密码、短信验证码等场景，通常与数字键盘组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { PasswordInput, NumberKeyboard } from 'vant';const app = createApp();app.use(PasswordInput);app.use(NumberKeyboard);搭配数字键盘组件来实现密码输入功能。
<!-- 密码输入框 --><van-password-input :value="value" :focused="showKeyboard" @focus="showKeyboard = true"/><!-- 数字键盘 --><van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false"/>import { ref } from 'vue';export default { setup() { const value = ref('123'); const showKeyboard = ref(true); return { value, showKeyboard, }; },};通过 length 属性来设置密码长度。
<van-password-input :value="value" :length="4" :focused="showKeyboard" @focus="showKeyboard = true"/>通过 gutter 属性来设置格子之间的间距。
<van-password-input :value="value" :gutter="10" :focused="showKeyboard" @focus="showKeyboard = true"/>将 mask 设置为 false 可以明文展示输入的内容，适用于短信验证码等场景。
<van-password-input :value="value" :mask="false" :focused="showKeyboard" @focus="showKeyboard = true"/>通过 info 属性设置提示信息，通过 error-info 属性设置错误提示，例如当输入六位时提示密码错误。
<van-password-input :value="value" info="密码为 6 位数字" :error-info="errorInfo" :focused="showKeyboard" @focus="showKeyboard = true"/><van-number-keyboard v-model="value" :show="showKeyboard" @blur="showKeyboard = false"/>import { ref, watch } from 'vue';export default { setup() { const value = ref('123'); const errorInfo = ref(''); const showKeyboard = ref(true); watch(value, (newVal) => { if (newVal.length === 6 && newVal !== '123456') { errorInfo.value = '密码错误'; } else { errorInfo.value = ''; } }); return { value, errorInfo, showKeyboard, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 密码值 | string | '' |
| info | 输入框下方文字提示 | string | - |
| error-info | 输入框下方错误提示 | string | - |
| length | 密码最大长度 | number | string | 6 |
| gutter | 输入框格子之间的间距，如 20px 2em，默认单位为px | number | string | 0 |
| mask | 是否隐藏密码内容 | boolean | true |
| focused | 是否已聚焦，聚焦时会显示光标 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| focus | 输入框聚焦时触发 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-password-input-height | 50px | - |
| --van-password-input-margin | 0 var(--van-padding-md) | - |
| --van-password-input-font-size | 20px | - |
| --van-password-input-border-radius | 6px | - |
| --van-password-input-background-color | var(--van-white) | - |
| --van-password-input-info-color | var(--van-gray-6) | - |
| --van-password-input-info-font-size | var(--van-font-size-md) | - |
| --van-password-input-error-info-color | var(--van-danger-color) | - |
| --van-password-input-dot-size | 10px | - |
| --van-password-input-dot-color | var(--van-black) | - |
| --van-password-input-cursor-color | var(--van-text-color) | - |
| --van-password-input-cursor-width | 1px | - |
| --van-password-input-cursor-height | 40% | - |
| --van-password-input-cursor-animation-duration | 1s | - |
提供多个选项集合供用户选择，支持单列选择和多列级联，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Picker } from 'vant';const app = createApp();app.use(Picker);Picker 组件通过 columns 属性配置选项数据，columns 是一个包含字符串或对象的数组。
顶部栏包含标题、确认按钮和取消按钮，点击确认按钮触发 confirm 事件，点击取消按钮触发 cancel 事件。
<van-picker title="标题" :columns="columns" @confirm="onConfirm" @cancel="onCancel" @change="onChange"/>import { Toast } from 'vant';export default { setup() { const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华']; const onConfirm = (value, index) => { Toast(`当前值: ${value}, 当前索引: ${index}`); }; const onChange = (value, index) => { Toast(`当前值: ${value}, 当前索引: ${index}`); }; const onCancel = () => Toast('取消'); return { columns, onChange, onCancel, onConfirm, }; },};单列选择时，可以通过 default-index 属性设置初始选中项的索引。
<van-picker title="标题" :columns="columns" :default-index="2" />columns 属性可以通过对象数组的形式配置多列选择，对象中可以配置选项数据、初始选中项等，详细格式见下方表格。
<van-picker title="标题" :columns="columns" />export default { setup() { const columns = [ // 第一列 { values: ['周一', '周二', '周三', '周四', '周五'], defaultIndex: 2, }, // 第二列 { values: ['上午', '下午', '晚上'], defaultIndex: 1, }, ]; return { columns }; },};使用 columns 的 children 字段可以实现选项级联的效果。如果级联层级较多，推荐使用 Cascader 级联选项组件。
<van-picker title="标题" :columns="columns" />export default { setup() { const columns = [ { text: '浙江', children: [ { text: '杭州', children: [{ text: '西湖区' }, { text: '余杭区' }], }, { text: '温州', children: [{ text: '鹿城区' }, { text: '瓯海区' }], }, ], }, { text: '福建', children: [ { text: '福州', children: [{ text: '鼓楼区' }, { text: '台江区' }], }, { text: '厦门', children: [{ text: '思明区' }, { text: '海沧区' }], }, ], }, ]; return { columns }; },};级联选择的数据嵌套深度需要保持一致，如果部分选项没有子选项，可以使用空字符串进行占位。
选项可以为对象结构，通过设置 disabled 来禁用该选项。
<van-picker :columns="columns" />export default { setup() { const columns = [ { text: '杭州', disabled: true }, { text: '宁波' }, { text: '温州' }, ]; return { columns }; },};通过 Picker 上的实例方法可以更灵活地控制选择器，比如使用 setColumnValues 方法实现多列联动。
<van-picker ref="picker" :columns="columns" @change="onChange" />import { ref } from 'vue';export default { setup() { const picker = ref(null); const cities = { 浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'], 福建: ['福州', '厦门', '莆田', '三明', '泉州'], }; const columns = [ { values: Object.keys(cities) }, { values: cities['浙江'] }, ]; const onChange = (values) => { picker.value.setColumnValues(1, cities[values[0]]); }; return { picker, columns, onChange, }; },};若选择器数据是异步获取的，可以通过 loading 属性显示加载提示。
<van-picker :columns="state.columns" :loading="state.loading" />import { reactive } from 'vue';export default { setup() { const state = reactive({ columns: [], loading: true, }); setTimeout(() => { state.loading = false; state.columns = ['选项']; }, 1000); return { state }; },};在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
<van-field v-model="state.value" readonly clickable label="城市" placeholder="选择城市" @click="state.showPicker = true"/><van-popup v-model:show="state.showPicker" round position="bottom"> <van-picker :columns="columns" @cancel="state.showPicker = false" @confirm="onConfirm" /></van-popup>import { reactive } from 'vue';export default { setup() { const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华']; const state = reactive({ value: '', showPicker: false, }); const onConfirm = (value) => { state.value = value; state.showPicker = false; }; return { state, columns, onConfirm, }; },};
<van-picker :title="标题" :columns="columns" :columns-field-names="customFieldName"/>export default { setup() { const columns = [ { cityName: '浙江', cities: [ { cityName: '杭州', cities: [{ cityName: '西湖区' }, { cityName: '余杭区' }], }, { cityName: '温州', cities: [{ cityName: '鹿城区' }, { cityName: '瓯海区' }], }, ], }, { cityName: '福建', cities: [ { cityName: '福州', cities: [{ cityName: '鼓楼区' }, { cityName: '台江区' }], }, { cityName: '厦门', cities: [{ cityName: '思明区' }, { cityName: '海沧区' }], }, ], }, ]; const customFieldName = { text: 'cityName', children: 'cities', }; return { columns, customFieldName, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| columns | 对象数组，配置每一列显示的数据 | Column[] | [] |
| columns-field-names | 自定义 columns 结构中的字段 | object | { text: 'text', values: 'values', children: 'children' } |
| title | 顶部栏标题 | string | - |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| toolbar-position | 顶部栏位置，可选值为 bottom | string | top |
| loading | 是否显示加载状态 | boolean | false |
| show-toolbar | 是否显示顶部栏 | boolean | true |
| allow-html | 是否允许选项内容中渲染 HTML | boolean | false |
| default-index | 单列选择时，默认选中项的索引 | number | string | 0 |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位 ms | number | string | 1000 |
当选择器有多列时，事件回调参数会返回数组。
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，所有列选中值对应的索引 |
| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，所有列选中值对应的索引 |
| change | 选项改变时触发 | 单列：选中值，选中值对应的索引 多列：所有列选中值，当前列对应的索引 |
| 名称 | 说明 | 参数 |
|---|---|---|
toolbar v3.1.2 | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | option: string | object |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
当传入多列数据时，columns 为一个对象数组，数组中的每一个对象配置每一列，每一列有以下 key:
| 键名 | 说明 | 类型 |
|---|---|---|
| values | 列中对应的备选值 | Array<string | number> |
| defaultIndex | 初始选中项的索引，默认为 0 | number |
| className | 为对应列添加额外的类名 | string | Array | object |
| children | 级联选项 | Column |
通过 ref 可以获取到 Picker 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| getValues | 获取所有列选中的值 | - | values |
| setValues | 设置所有列选中的值 | values | - |
| getIndexes | 获取所有列选中值对应的索引 | - | indexes |
| setIndexes | 设置所有列选中值对应的索引 | indexes | - |
| getColumnValue | 获取对应列选中的值 | columnIndex | value |
| setColumnValue | 设置对应列选中的值 | columnIndex, value | - |
| getColumnIndex | 获取对应列选中项的索引 | columnIndex | optionIndex |
| setColumnIndex | 设置对应列选中项的索引 | columnIndex, optionIndex | - |
| getColumnValues | 获取对应列中所有选项 | columnIndex | values |
| setColumnValues | 设置对应列中所有选项 | columnIndex, values | - |
| confirm | 停止惯性滚动并触发 confirm 事件 | - | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-picker-background-color | var(--van-white) | - |
| --van-picker-toolbar-height | 44px | - |
| --van-picker-title-font-size | var(--van-font-size-lg) | - |
| --van-picker-title-line-height | var(--van-line-height-md) | - |
| --van-picker-action-padding | 0 var(--van-padding-md) | - |
| --van-picker-action-font-size | var(--van-font-size-md) | - |
| --van-picker-confirm-action-color | var(--van-text-link-color) | - |
| --van-picker-cancel-action-color | var(--van-gray-6) | - |
| --van-picker-option-padding | 0 var(--van-padding-base) | - |
| --van-picker-option-font-size | var(--van-font-size-lg) | - |
| --van-picker-option-text-color | var(--van-black) | - |
| --van-picker-option-disabled-opacity | 0.3 | - |
| --van-picker-loading-icon-color | var(--van-primary-color) | - |
| --van-picker-loading-mask-color | rgba(255, 255, 255, 0.9) | - |
参见桌面端适配。
在一组备选项中进行单选。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { RadioGroup, Radio } from 'vant';const app = createApp();app.use(Radio);app.use(RadioGroup);通过 v-model 绑定值当前选中项的 name。
<van-radio-group v-model="checked"> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio></van-radio-group>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked }; },};将 direction 属性设置为 horizontal 后，单选框组会变成水平排列。
<van-radio-group v-model="checked" 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="checked" disabled> <van-radio name="1">单选框 1</van-radio> <van-radio name="2">单选框 2</van-radio></van-radio-group>将 shape 属性设置为 square，单选框的形状会变成方形。
<van-radio-group v-model="checked"> <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="checked"> <van-radio name="1" checked-color="#ee0a24">单选框 1</van-radio> <van-radio name="2" checked-color="#ee0a24">单选框 2</van-radio></van-radio-group>通过 icon-size 属性可以自定义图标的大小。
<van-radio-group v-model="checked"> <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="checked"> <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>import { ref } from 'vue';export default { setup() { const checked = ref('1'); return { checked, activeIcon: 'https://img.yzcdn.cn/vant/user-active.png', inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.png', }; },};设置 label-disabled 属性后，点击图标以外的内容不会触发单选框切换。
<van-radio-group v-model="checked"> <van-radio name="1" label-disabled>单选框 1</van-radio> <van-radio name="2" label-disabled>单选框 2</van-radio></van-radio-group>此时你需要再引入 Cell 和 CellGroup 组件。
<van-radio-group v-model="checked"> <van-cell-group> <van-cell title="单选框 1" clickable @click="checked = '1'"> <template #right-icon> <van-radio name="1" /> </template> </van-cell> <van-cell title="单选框 2" clickable @click="checked = '2'"> <template #right-icon> <van-radio name="2" /> </template> </van-cell> </van-cell-group></van-radio-group>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符 | any | - |
| shape | 形状，可选值为 square | string | round |
| disabled | 是否为禁用状态 | boolean | false |
| label-disabled | 是否禁用文本内容点击 | boolean | false |
| label-position | 文本位置，可选值为 left | string | right |
| icon-size | 图标大小，默认单位为px | number | string | 20px |
| checked-color | 选中状态颜色 | string | #1989fa |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中项的标识符 | any | - |
| disabled | 是否禁用所有单选框 | boolean | false |
| direction | 排列方向，可选值为horizontal | string | vertical |
| icon-size | 所有单选框的图标大小，默认单位为px | number | string | 20px |
| checked-color | 所有单选框的选中状态颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击单选框时触发 | event: MouseEvent |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | name: string |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义文本 | - |
| icon | 自定义图标 | { checked: boolean, disabled: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-radio-size | 20px | - |
| --van-radio-border-color | var(--van-gray-5) | - |
| --van-radio-transition-duration | var(--van-animation-duration-fast) | - |
| --van-radio-label-margin | var(--van-padding-xs) | - |
| --van-radio-label-color | var(--van-text-color) | - |
| --van-radio-checked-icon-color | var(--van-primary-color) | - |
| --van-radio-disabled-icon-color | var(--van-gray-5) | - |
| --van-radio-disabled-label-color | var(--van-gray-5) | - |
| --van-radio-disabled-background-color | var(--van-border-color) | - |
用于对事物进行评级操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Rate } from 'vant';const app = createApp();app.use(Rate);通过 v-model 来绑定当前评分值。
<van-rate v-model="value" />import { ref } from 'vue';export default { setup() { const value = ref(3); return { value }; },};通过 icon 属性设置选中时的图标，void-icon 属性设置未选中时的图标。
<van-rate v-model="value" icon="like" void-icon="like-o" />通过 size 属性设置图标大小，color 属性设置选中时的颜色，void-color 设置未选中时的颜色。
<van-rate v-model="value" :size="25" color="#ffd21e" void-icon="star" void-color="#eee"/>设置 allow-half 属性后可以选中半星。
<van-rate v-model="value" allow-half />import { ref } from 'vue';export default { setup() { const value = ref(2.5); return { value }; },};通过 count 属性设置评分总数。
<van-rate v-model="value" :count="6" />通过 disabled 属性来禁用评分。
<van-rate v-model="value" disabled />通过 readonly 属性将评分设置为只读状态。
<van-rate v-model="value" readonly />设置 readonly 和 allow-half 属性后，Rate 组件可以展示任意小数结果。
<van-rate v-model="value" readonly allow-half />import { ref } from 'vue';export default { setup() { const value = ref(3.3); return { value }; },};评分变化时，会触发 change 事件。
<van-rate v-model="value" @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(3); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前分值 | number | - |
| count | 图标总数 | number | string | 5 |
| size | 图标大小，默认单位为px | number | string | 20px |
| gutter | 图标间距，默认单位为px | number | string | 4px |
| color | 选中时的颜色 | string | #ee0a24 |
| void-color | 未选中时的颜色 | string | #c8c9cc |
| disabled-color | 禁用时的颜色 | string | #c8c9cc |
| icon | 选中时的图标名称或图片链接 | string | star |
| void-icon | 未选中时的图标名称或图片链接 | string | star-o |
| icon-prefix | 图标类名前缀，同 Icon 组件的 class-prefix 属性 | string | van-icon |
| allow-half | 是否允许半选 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法修改评分 | boolean | false |
| disabled | 是否禁用评分 | boolean | false |
| touchable | 是否可以通过滑动手势选择评分 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当前分值变化时触发的事件 | 当前分值 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-rate-icon-size | 20px | - |
| --van-rate-icon-gutter | var(--van-padding-base) | - |
| --van-rate-icon-void-color | var(--van-gray-5) | - |
| --van-rate-icon-full-color | var(--van-danger-color) | - |
| --van-rate-icon-disabled-color | var(--van-gray-5) | - |
用于搜索场景的输入框组件。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Search } from 'vant';const app = createApp();app.use(Search);v-model 用于控制搜索框中的文字，background 可以自定义搜索框外部背景色。
<van-search v-model="value" placeholder="请输入搜索关键词" />import { ref } from 'vue';export default { setup() { const value = ref(''); return { value }; },};Search 组件提供了 search 和 cancel 事件，search 事件在点击键盘上的搜索/回车按钮后触发，cancel 事件在点击搜索框右侧取消按钮时触发。
<form action="/"> <van-search v-model="value" show-action placeholder="请输入搜索关键词" @search="onSearch" @cancel="onCancel" /></form>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(''); const onSearch = (val) => Toast(val); const onCancel = () => Toast('取消'); return { value, onSearch, onCancel, }; },};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 label="地址" placeholder="请输入搜索关键词" @search="onSearch"> <template #action> <div @click="onSearch">搜索</div> </template></van-search>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 搜索框左侧文本 | string | - |
| shape | 搜索框形状，可选值为 round | string | square |
| background | 搜索框外部背景色 | string | #f2f2f2 |
| maxlength | 输入的最大字符数 | number | string | - |
| placeholder | 占位提示文字 | string | - |
| clearable | 是否启用清除图标，点击清除图标后会清空输入框 | boolean | true |
clear-icon v3.0.12 | 清除图标名称或图片链接 | string | clear |
| clear-trigger | 显示清除图标的时机，always 表示输入框不为空时展示， focus 表示输入框聚焦且不为空时展示 | string | focus |
| autofocus | 是否自动聚焦，iOS 系统不支持该属性 | boolean | false |
| show-action | 是否在搜索框右侧显示取消按钮 | boolean | false |
| action-text | 取消按钮文字 | boolean | 取消 |
| disabled | 是否禁用输入框 | boolean | false |
| readonly | 是否将输入框设为只读状态，只读状态下无法输入内容 | boolean | false |
| error | 是否将输入内容标红 | boolean | false |
| error-message | 底部错误提示文案，为空时不展示 | string | - |
formatter v3.0.12 | 输入内容格式化函数 | (val: string) => string | - |
format-trigger v3.0.12 | 格式化函数触发的时机，可选值为 onBlur | string | onChange |
| input-align | 输入框内容对齐方式，可选值为 center right | string | left |
| left-icon | 输入框左侧图标名称或图片链接 | string | search |
| right-icon | 输入框右侧图标名称或图片链接 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| search | 确定搜索时触发 | value: string (当前输入的值) |
| update:model-value | 输入框内容变化时触发 | value: string (当前输入的值) |
| focus | 输入框获得焦点时触发 | event: Event |
| blur | 输入框失去焦点时触发 | event: Event |
| click-input | 点击输入区域时触发 | event: MouseEvent |
| clear | 点击清除按钮后触发 | event: MouseEvent |
| cancel | 点击取消按钮时触发 | - |
通过 ref 可以获取到 Search 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 获取输入框焦点 | - | - |
| blur | 取消输入框焦点 | - | - |
| 名称 | 说明 |
|---|---|
| left | 自定义左侧内容（搜索框外） |
| action | 自定义右侧内容（搜索框外），设置show-action属性后展示 |
| label | 自定义左侧文本（搜索框内） |
| left-icon | 自定义左侧图标（搜索框内） |
| right-icon | 自定义右侧图标（搜索框内） |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-search-padding | 10px var(--van-padding-sm) | - |
| --van-search-background-color | var(--van-white) | - |
| --van-search-content-background-color | var(--van-gray-1) | - |
| --van-search-input-height | 34px | - |
| --van-search-label-padding | 0 5px | - |
| --van-search-label-color | var(--van-text-color) | - |
| --van-search-label-font-size | var(--van-font-size-md) | - |
| --van-search-left-icon-color | var(--van-gray-6) | - |
| --van-search-action-padding | 0 var(--van-padding-xs) | - |
| --van-search-action-text-color | var(--van-text-color) | - |
| --van-search-action-font-size | var(--van-font-size-md) | - |
清除按钮监听是的移动端 Touch 事件，参见桌面端适配。
滑动输入条，用于在给定的范围内选择一个值。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Slider } from 'vant';const app = createApp();app.use(Slider);
<van-slider v-model="value" @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(50); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};添加 range 属性就可以开启双滑块模式，确保 value 的值是一个数组。
<van-slider v-model="value" range @change="onChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { // 双滑块模式时，值必须是数组 const value = ref([10, 50]); const onChange = (value) => Toast('当前值：' + value); return { value, onChange, }; },};
<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"> <template #button> <div class="custom-button">{{ value }}</div> </template></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>设置 vertical 属性后，滑块会垂直展示，且高度为 100% 父元素高度。
<div :style="{ height: '150px' }"> <van-slider v-model="value" vertical @change="onChange" /> <van-slider v-model="value2" range vertical style="margin-left: 100px;" @change="onChange" /></div>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(50); const value2 = ref([10, 50]); const onChange = (value) => Toast('当前值：' + value); return { value, value2, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前进度百分比，在双滑块模式下为数组格式 | number | [number, number] | 0 |
| max | 最大值 | number | string | 100 |
| min | 最小值 | number | string | 0 |
| step | 步长 | number | string | 1 |
| bar-height | 进度条高度，默认单位为 px | number | string | 2px |
| button-size | 滑块按钮大小，默认单位为 px | number | string | 24px |
| active-color | 进度条激活态颜色 | string | #1989fa |
| inactive-color | 进度条非激活态颜色 | string | #e5e5e5 |
| range | 是否开启双滑块模式 | boolean | false |
| disabled | 是否禁用滑块 | boolean | false |
readonly v3.0.5 | 是否为只读状态，只读状态下无法修改滑块的值 | boolean | false |
| vertical | 是否垂直展示 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:model-value | 进度变化时实时触发 | value: number |
| change | 进度变化且结束拖动后触发 | value: number |
| drag-start | 开始拖动时触发 | event: TouchEvent |
| drag-end | 结束拖动时触发 | event: TouchEvent |
| 名称 | 说明 | 参数 |
|---|---|---|
| button | 自定义滑块按钮 | { value: number } |
left-button v3.1.3 | 自定义左侧滑块按钮（双滑块模式下） | { value: number } |
right-button v3.1.3 | 自定义右侧滑块按钮 （双滑块模式下） | { value: number } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-slider-active-background-color | var(--van-primary-color) | - |
| --van-slider-inactive-background-color | var(--van-gray-3) | - |
| --van-slider-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-slider-bar-height | 2px | - |
| --van-slider-button-width | 24px | - |
| --van-slider-button-height | 24px | - |
| --van-slider-button-border-radius | 50% | - |
| --van-slider-button-background-color | var(--van-white) | - |
| --van-slider-button-box-shadow | 0 1px 2px rgba(0, 0, 0, 0.5) | - |
步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Stepper } from 'vant';const app = createApp();app.use(Stepper);通过 v-model 绑定输入值，可以通过 change 事件监听到输入值的变化。
<van-stepper v-model="value" />import { ref } from 'vue';export default { setup() { const value = ref(1); return { value }; },};通过 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 />通过设置 disable-input 属性来禁用输入框，此时按钮仍然可以点击。
<van-stepper v-model="value" disable-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" />通过 before-change 属性可以在输入值变化前进行校验和拦截。
<van-stepper v-model="value" :before-change="beforeChange" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const value = ref(1); const beforeChange = (value) => { Toast.loading({ forbidClick: true }); return new Promise((resolve) => { setTimeout(() => { Toast.clear(); // 在 resolve 函数中返回 true 或 false resolve(true); }, 500); }); }; return { value, beforeChange, }; },};将 theme 设置为 round 来展示圆角风格的步进器。
<van-stepper v-model="value" theme="round" button-size="22" disable-input />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前输入的值 | number | string | - |
| min | 最小值 | number | string | 1 |
| max | 最大值 | number | string | - |
| default-value | 初始值，当 v-model 为空时生效 | number | string | 1 |
| step | 步长，每次点击时改变的值 | number | string | 1 |
| name | 标识符，可以在 change 事件回调参数中获取 | number | string | - |
| input-width | 输入框宽度，默认单位为 px | number | string | 32px |
| button-size | 按钮大小以及输入框高度，默认单位为 px | number | string | 28px |
| decimal-length | 固定显示的小数位数 | number | string | - |
| theme | 样式风格，可选值为 round | string | - |
| placeholder | 输入框占位提示文字 | string | - |
| integer | 是否只允许输入整数 | boolean | false |
| disabled | 是否禁用步进器 | boolean | false |
| disable-plus | 是否禁用增加按钮 | boolean | false |
| disable-minus | 是否禁用减少按钮 | boolean | false |
| disable-input | 是否禁用输入框 | boolean | false |
| before-change | 输入值变化前的回调函数，返回 false 可阻止输入，支持返回 Promise | (value: number | string) => boolean | Promise<boolean> | false |
| show-plus | 是否显示增加按钮 | boolean | true |
| show-minus | 是否显示减少按钮 | boolean | true |
| show-input | 是否显示输入框 | boolean | true |
| long-press | 是否开启长按手势 | boolean | true |
| allow-empty | 是否允许输入的值为空 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | value: string, detail: { name: string } |
| overlimit | 点击不可用的按钮时触发 | - |
| plus | 点击增加按钮时触发 | - |
| minus | 点击减少按钮时触发 | - |
| focus | 输入框聚焦时触发 | event: Event |
| blur | 输入框失焦时触发 | event: Event |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-stepper-active-color | #e8e8e8 | - |
| --van-stepper-background-color | var(--van-active-color) | - |
| --van-stepper-button-icon-color | var(--van-text-color) | - |
| --van-stepper-button-disabled-color | var(--van-background-color) | - |
| --van-stepper-button-disabled-icon-color | var(--van-gray-5) | - |
| --van-stepper-button-round-theme-color | var(--van-danger-color) | - |
| --van-stepper-input-width | 32px | - |
| --van-stepper-input-height | 28px | - |
| --van-stepper-input-font-size | var(--van-font-size-md) | - |
| --van-stepper-input-line-height | normal | - |
| --van-stepper-input-text-color | var(--van-text-color) | - |
| --van-stepper-input-disabled-text-color | var(--van-gray-5) | - |
| --van-stepper-input-disabled-background-color | var(--van-active-color) | - |
| --van-stepper-border-radius | var(--van-border-radius-md) | - |
这是因为用户输入过程中可能出现小数点或空值，比如 1.，这种情况下组件会抛出字符串类型。
如果希望 value 保持 number 类型，可以在 v-model 上添加 number 修饰符：
<van-stepper v-model.number="value" />用于在打开和关闭状态之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Switch } from 'vant';const app = createApp();app.use(Switch);通过 v-model 绑定开关的选中状态，true 表示开，false 表示关。
<van-switch v-model="checked" />import { ref } from 'vue';export default { setup() { const checked = ref(true); return { checked }; },};通过 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="#ee0a24" inactive-color="#dcdee0" />需要异步控制开关时，可以使用 modelValue 属性和 update:model-value 事件代替 v-model，并在事件回调函数中手动处理开关状态。
<van-switch :model-value="checked" @update:model-value="onUpdateValue" />import { ref } from 'vue';import { Dialog } from 'vant';export default { setup() { const checked = ref(true); const onUpdateValue = (newValue) => { Dialog.confirm({ title: '提醒', message: '是否切换开关？', }).then(() => { checked.value = newValue; }); }; return { checked, onUpdateValue, }; },};<van-cell center title="标题"> <template #right-icon> <van-switch v-model="checked" size="24" /> </template></van-cell>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 开关选中状态 | any | false |
| loading | 是否为加载状态 | boolean | false |
| disabled | 是否为禁用状态 | boolean | false |
| size | 开关尺寸，默认单位为px | number | string | 30px |
| active-color | 打开时的背景色 | string | #1989fa |
| inactive-color | 关闭时的背景色 | string | white |
| active-value | 打开时对应的值 | any | true |
| inactive-value | 关闭时对应的值 | any | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 开关状态切换时触发 | value: any |
| click | 点击时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-switch-size | 30px | - |
| --van-switch-width | 2em | - |
| --van-switch-height | 1em | - |
| --van-switch-node-size | 1em | - |
| --van-switch-node-background-color | var(--van-white) | - |
| --van-switch-node-box-shadow | 0 3px 1px 0 rgba(0, 0, 0, 0.05) | - |
| --van-switch-background-color | var(--van-white) | - |
| --van-switch-on-background-color | var(--van-primary-color) | - |
| --van-switch-transition-duration | var(--van-animation-duration-base) | - |
| --van-switch-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-switch-border | var(--van-border-width-base) solid rgba(0, 0, 0, 0.1) | - |
用于将本地的图片或文件上传至服务器，并在上传过程中展示预览图和上传进度。目前 Uploader 组件不包含将文件上传至服务器的接口逻辑，该步骤需要自行实现。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Uploader } from 'vant';const app = createApp();app.use(Uploader);文件上传完毕后会触发 after-read 回调函数，获取到对应的 file 对象。
<van-uploader :after-read="afterRead" />export default { setup() { const afterRead = (file) => { // 此时可以自行将文件上传至服务器 console.log(file); }; return { afterRead, }; },};通过 v-model 可以绑定已经上传的文件列表，并展示文件列表的预览图。
<van-uploader v-model="fileList" multiple />import { ref } from 'vue';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg' }, // Uploader 根据文件后缀来判断是否为图片文件 // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明 { url: 'https://cloud-image', isImage: true }, ]); return { fileList, }; },};通过 status 属性可以标识上传状态，uploading 表示上传中，failed 表示上传失败，done 表示上传完成。
<van-uploader v-model="fileList" :after-read="afterRead" />import { ref } from 'vue';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg', status: 'uploading', message: '上传中...', }, { url: 'https://img.yzcdn.cn/vant/tree.jpg', status: 'failed', message: '上传失败', }, ]); const afterRead = (file) => { file.status = 'uploading'; file.message = '上传中...'; setTimeout(() => { file.status = 'failed'; file.message = '上传失败'; }, 1000); }; return { fileList, afterRead, }; },};通过 max-count 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。
<van-uploader v-model="fileList" multiple :max-count="2" />import { ref } from 'vue';export default { setup() { const fileList = ref([]); return { fileList, }; },};通过 max-size 属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过 oversize 事件获取。
<van-uploader multiple :max-size="500 * 1024" @oversize="onOversize" />import { Toast } from 'vant';export default { setup() { const onOversize = (file) => { console.log(file); Toast('文件大小不能超过 500kb'); }; return { onOversize, }; },};如果需要针对不同类型的文件来作出不同的大小限制，可以在 max-size 属性中传入一个函数，在函数中通过 file.type 区分文件类型，返回 true 表示超出限制，false 表示未超出限制。
<van-uploader multiple :max-size="isOverSize" />import { Toast } from 'vant';export default { setup() { const isOverSize = (file) => { const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024; return file.size >= maxSize; }; return { isOverSize, }; },};通过默认插槽可以自定义上传区域的样式。
<van-uploader> <van-button icon="plus" type="primary">上传文件</van-button></van-uploader>通过 preview-cover 插槽可以自定义覆盖在预览区域上方的内容。
<van-uploader v-model="fileList"> <template #preview-cover="{ file }"> <div class="preview-cover van-ellipsis">{{ file.name }}</div> </template></van-uploader><style> .preview-cover { position: absolute; bottom: 0; box-sizing: border-box; width: 100%; padding: 4px; color: #fff; font-size: 12px; text-align: center; background: rgba(0, 0, 0, 0.3); }</style>通过传入 beforeRead 函数可以在上传前进行校验和处理，返回 true 表示校验通过，返回 false 表示校验失败。支持返回 Promise 对 file 对象进行自定义处理，例如压缩图片。
<van-uploader :before-read="beforeRead" />import { Toast } from 'vant';export default { setup() { // 返回布尔值 const beforeRead = (file) => { if (file.type !== 'image/jpeg') { Toast('请上传 jpg 格式图片'); return false; } return true; }; // 返回 Promise const asyncBeforeRead = (file) => { return new Promise((resolve, reject) => { if (file.type !== 'image/jpeg') { Toast('请上传 jpg 格式图片'); reject(); } else { const img = new File(['foo'], 'bar.jpg', { type: 'image/jpeg', }); resolve(img); } }); }; return { beforeRead, asyncBeforeRead, }; },};通过 disabled 属性禁用文件上传。
<van-uploader disabled />在 v-model 数组中设置单个预览图片属性，支持 imageFit deletable previewSize beforeDelete。
<van-uploader v-model="fileList" :deletable="false" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const fileList = ref([ { url: 'https://img.yzcdn.cn/vant/leaf.jpg' }, { url: 'https://img.yzcdn.cn/vant/sand.jpg', deletable: true, beforeDelete: () => { Toast('自定义单个预览图片的事件和样式'); }, }, { url: 'https://img.yzcdn.cn/vant/tree.jpg', deletable: true, imageFit: 'contain', previewSize: 120, }, ]); return { fileList }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 已上传的文件列表 | FileListItem[] | - |
| accept | 允许上传的文件类型，详细说明 | string | image/* |
| name | 标识符，可以在回调函数的第二项参数中获取 | number | string | - |
| preview-size | 预览图和上传区域的尺寸，默认单位为 px | number | string | 80px |
| preview-image | 是否在上传完成后展示预览图 | boolean | true |
| preview-full-image | 是否在点击预览图后展示全屏图片预览 | boolean | true |
| preview-options | 全屏图片预览的配置项，可选值见 ImagePreview | object | - |
| multiple | 是否开启图片多选，部分安卓机型不支持 | boolean | false |
| disabled | 是否禁用文件上传 | boolean | false |
readonly v3.1.5 | 是否将上传区域设置为只读状态 | boolean | false |
| deletable | 是否展示删除按钮 | boolean | true |
| show-upload | 是否展示上传区域 | boolean | true |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| capture | 图片选取模式，可选值为 camera (直接调起摄像头) | string | - |
| after-read | 文件读取完成后的回调函数 | Function | - |
| before-read | 文件读取前的回调函数，返回 false 可终止文件读取， 支持返回 Promise | Function | - |
| before-delete | 文件删除前的回调函数，返回 false 可终止文件读取， 支持返回 Promise | Function | - |
max-size v3.0.17 | 文件大小限制，单位为 byte | number | string | (file: File) => boolean | - |
| max-count | 文件上传数量限制 | number | string | - |
| result-type | 文件读取结果类型，可选值为 file text | string | dataUrl |
| upload-text | 上传区域文字提示 | string | - |
| image-fit | 预览图裁剪模式，可选值见 Image 组件 | string | cover |
| upload-icon | 上传区域图标名称或图片链接 | string | photograph |
注意：accept、capture 和 multiple 为浏览器 input 标签的原生属性，移动端各种机型对这些属性的支持程度有所差异，因此在不同机型和 WebView 下可能出现一些兼容性问题。
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| oversize | 文件大小超过限制时触发 | 同 after-read |
click-upload v3.1.5 | 点击上传区域时触发 | event: MouseEvent |
| click-preview | 点击预览图时触发 | 同 after-read |
| close-preview | 关闭全屏图片预览时触发 | - |
| delete | 删除文件预览时触发 | 同 after-read |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义上传区域 | - |
| preview-cover | 自定义覆盖在预览区域上方的内容 | item: FileListItem |
before-read、after-read、before-delete 执行时会传递以下回调参数：
| 参数名 | 说明 | 类型 |
|---|---|---|
| file | file 对象 | object |
| detail | 额外信息，包含 name 和 index 字段 | object |
result-type 字段表示文件读取结果的类型，上传大文件时，建议使用 file 类型，避免卡顿。
| 值 | 描述 |
|---|---|
| file | 结果仅包含 File 对象 |
| text | 结果包含 File 对象，以及文件的文本内容 |
| dataUrl | 结果包含 File 对象，以及文件对应的 base64 编码 |
通过 ref 可以获取到 Uploader 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| closeImagePreview | 关闭全屏的图片预览 | - | - |
| chooseFile | 主动调起文件选择，由于浏览器安全限制，只有在用户触发操作的上下文中调用才有效 | - | - |
通过 UploaderInstance 获取 Uploader 实例的类型定义。
import { ref } from 'vue';import type { UploaderInstance } from 'vant';const uploaderRef = ref<UploaderInstance>();uploaderRef.value?.chooseFile();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-uploader-size | 80px | - |
| --van-uploader-icon-size | 24px | - |
| --van-uploader-icon-color | var(--van-gray-4) | - |
| --van-uploader-text-color | var(--van-gray-6) | - |
| --van-uploader-text-font-size | var(--van-font-size-sm) | - |
| --van-uploader-upload-background-color | var(--van-gray-1) | - |
| --van-uploader-upload-active-color | var(--van-active-color) | - |
| --van-uploader-delete-color | var(--van-white) | - |
| --van-uploader-delete-icon-size | 14px | - |
| --van-uploader-delete-background-color | rgba(0, 0, 0, 0.7) | - |
| --van-uploader-file-background-color | var(--van-background-color) | - |
| --van-uploader-file-icon-size | 20px | - |
| --van-uploader-file-icon-color | var(--van-gray-7) | - |
| --van-uploader-file-name-padding | 0 var(--van-padding-base) | - |
| --van-uploader-file-name-margin-top | var(--van-padding-xs) | - |
| --van-uploader-file-name-font-size | var(--van-font-size-sm) | - |
| --van-uploader-file-name-text-color | var(--van-gray-7) | - |
| --van-uploader-mask-text-color | var(--van-white) | - |
| --van-uploader-mask-background-color | fade(var(--van-gray-8), 88%) | - |
| --van-uploader-mask-icon-size | 22px | - |
| --van-uploader-mask-message-font-size | var(--van-font-size-sm) | - |
| --van-uploader-mask-message-line-height | var(--van-line-height-xs) | - |
| --van-uploader-loading-icon-size | 22px | - |
| --van-uploader-loading-icon-color | var(--van-white) | - |
| --van-uploader-disabled-opacity | var(--van-disabled-opacity) | - |
部分手机在拍照上传时会出现图片被旋转 90 度的问题，这个问题可以通过 compressorjs 或其他开源库进行处理。
compressorjs 是一个开源的图片处理库，提供了图片压缩、图片旋转等能力。
使用 compressorjs 进行处理的示例代码如下:
<van-uploader :before-read="beforeRead" />import Compressor from 'compressorjs';export default { setup() { const beforeRead = (file) => { return new Promise((resolve) => { // compressorjs 默认开启 checkOrientation 选项 // 会将图片修正为正确方向 new Compressor(file, { success: resolve, error(err) { console.log(err.message); }, }); }); }; return { beforeRead, }; },};目前 Chrome、Safari 等浏览器不支持展示 HEIC/HEIF 格式的图片，因此上传后无法在 Uploader 组件中进行预览。
[HEIF] 格式的兼容性请参考 caniuse。
底部弹起的模态面板，包含与当前情境相关的多个选项。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ActionSheet } from 'vant';const app = createApp();app.use(ActionSheet);动作面板通过 actions 属性来定义选项，actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象格式见文档下方表格。
<van-cell is-link title="基础用法" @click="show = true" /><van-action-sheet v-model:show="show" :actions="actions" @select="onSelect" />import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三' }, ]; const onSelect = (item) => { // 默认情况下点击选项时不会自动收起 // 可以通过 close-on-click-action 属性开启自动收起 show.value = false; Toast(item.name); }; return { show, actions, onSelect, }; },};设置 cancel-text 属性后，会在底部展示取消按钮，点击后关闭当前面板并触发 cancel 事件。
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" close-on-click-action @cancel="onCancel"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三' }, ]; const onCancel = () => Toast('取消'); return { show, actions, onCancel, }; },};通过 description 可以在菜单顶部显示描述信息，通过选项的 subname 属性可以在选项文字的右侧展示描述信息。
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" description="这是一段描述信息" close-on-click-action/>import { ref } from 'vue';export default { setup() { const show = ref(false); const actions = [ { name: '选项一' }, { name: '选项二' }, { name: '选项三', subname: '描述信息' }, ]; return { show, actions, }; },};可以通过 loading 和 disabled 将选项设置为加载状态或禁用状态，或者通过color设置选项的颜色
<van-action-sheet v-model:show="show" :actions="actions" cancel-text="取消" close-on-click-action/>import { ref } from 'vue';export default { setup() { const show = ref(false); const actions = [ { name: '着色选项', color: '#ee0a24' }, { name: '禁用选项', disabled: true }, { name: '加载选项', loading: true }, ]; return { show, actions, }; },};通过插槽可以自定义面板的展示内容，同时可以使用title属性展示标题栏
<van-action-sheet v-model:show="show" title="标题"> <div class="content">内容</div></van-action-sheet><style> .content { padding: 16px 16px 160px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示动作面板 | boolean | false |
| actions | 面板选项列表 | Action[] | [] |
| title | 顶部标题 | string | - |
| cancel-text | 取消按钮文字 | string | - |
| description | 选项上方的描述信息 | string | - |
| closeable | 是否显示关闭图标 | boolean | true |
| close-icon | 关闭图标名称或图片链接 | string | cross |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| round | 是否显示圆角 | boolean | true |
| overlay | 是否显示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | false |
| close-on-click-action | 是否在点击选项后关闭 | boolean | false |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 标题 | string |
| subname | 二级标题 | string |
| color | 选项文字颜色 | string |
| className | 为对应列添加额外的 class | string | Array | object |
| loading | 是否为加载状态 | boolean |
| disabled | 是否为禁用状态 | boolean |
| callback | 点击时触发的回调函数 | action: Action |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击选项时触发，禁用或加载状态下不会触发 | action: Action, index: number |
| cancel | 点击取消按钮时触发 | - |
| open | 打开面板时触发 | - |
| close | 关闭面板时触发 | - |
| opened | 打开面板且动画结束后触发 | - |
| closed | 关闭面板且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义面板的展示内容 |
| description | 自定义描述文案 |
cancel v3.0.10 | 自定义取消按钮内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-action-sheet-max-height | 80% | - |
| --van-action-sheet-header-height | 48px | - |
| --van-action-sheet-header-font-size | var(--van-font-size-lg) | - |
| --van-action-sheet-description-color | var(--van-gray-6) | - |
| --van-action-sheet-description-font-size | var(--van-font-size-md) | - |
| --van-action-sheet-description-line-height | var(--van-line-height-md) | - |
| --van-action-sheet-item-background | var(--van-white) | - |
| --van-action-sheet-item-font-size | var(--van-font-size-lg) | - |
| --van-action-sheet-item-line-height | var(--van-line-height-lg) | - |
| --van-action-sheet-item-text-color | var(--van-text-color) | - |
| --van-action-sheet-item-disabled-text-color | var(--van-gray-5) | - |
| --van-action-sheet-subname-color | var(--van-gray-6) | - |
| --van-action-sheet-subname-font-size | var(--van-font-size-sm) | - |
| --van-action-sheet-subname-line-height | var(--van-line-height-sm) | - |
| --van-action-sheet-close-icon-size | 22px | - |
| --van-action-sheet-close-icon-color | var(--van-gray-5) | - |
| --van-action-sheet-close-icon-active-color | var(--van-gray-6) | - |
| --van-action-sheet-close-icon-padding | 0 var(--van-padding-md) | - |
| --van-action-sheet-cancel-text-color | var(--van-gray-7) | - |
| --van-action-sheet-cancel-padding-top | var(--van-padding-xs) | - |
| --van-action-sheet-cancel-padding-color | var(--van-background-color) | - |
| --van-action-sheet-loading-icon-size | 22px | - |
弹出模态框，常用于消息提示、消息确认，或在当前页面内完成特定的交互操作，支持函数调用和组件调用两种方式。
Dialog 是一个函数，调用后会直接在页面中弹出相应的模态框。
import { Dialog } from 'vant';Dialog({ message: '提示' });通过组件调用 Dialog 时，可以通过下面的方式进行注册：
import { createApp } from 'vue';import { Dialog } from 'vant';// 全局注册const app = createApp();app.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 });将 theme 选项设置为 round-button 可以展示圆角按钮风格的弹窗。
Dialog.alert({ title: '标题', message: '弹窗内容', theme: 'round-button',}).then(() => { // on close});Dialog.alert({ message: '弹窗内容', theme: 'round-button',}).then(() => { // on close});通过 beforeClose 属性可以传入一个回调函数，在弹窗关闭前进行特定操作。
const beforeClose = (action) => new Promise((resolve) => { setTimeout(() => { if (action === 'confirm') { resolve(true); } else { // 拦截取消操作 resolve(false); } }, 1000); });Dialog.confirm({ title: '标题', message: '弹窗内容', beforeClose,});通过 app.use 全局注册 Dialog 组件后，会自动在 app 的所有子组件上挂载 $dialog 方法，在所有组件内部都可以直接调用此方法。
export default { mounted() { this.$dialog.alert({ message: '弹窗内容', }); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。
<van-dialog v-model:show="show" title="标题" show-cancel-button> <img src="https://img.yzcdn.cn/vant/apple-3.jpg" rel="external nofollow" /></van-dialog>import { ref } from 'vue';export default { setup() { const show = ref(false); return { show }; },};| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Dialog | 展示弹窗 | options: DialogOptions | Promise<void> |
| Dialog.alert | 展示消息提示弹窗 | options: DialogOptions | Promise<void> |
| Dialog.confirm | 展示消息确认弹窗 | options: DialogOptions | Promise<void> |
| Dialog.setDefaultOptions | 修改默认配置，对所有 Dialog 生效 | options: DialogOptions | void |
| Dialog.resetDefaultOptions | 重置默认配置，对所有 Dialog 生效 | - | void |
| Dialog.close | 关闭弹窗 | - | void |
通过函数调用 Dialog 时，支持传入以下选项：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | - |
| width | 弹窗宽度，默认单位为 px | number | string | 320px |
| message | 文本内容，支持通过
换行 | string | () => JSX.ELement | - |
| messageAlign | 内容对齐方式，可选值为 left right | string | center |
| theme | 样式风格，可选值为 round-button | string | default |
| className | 自定义类名 | string | Array | object | - |
| showConfirmButton | 是否展示确认按钮 | boolean | true |
| showCancelButton | 是否展示取消按钮 | boolean | false |
| confirmButtonText | 确认按钮文案 | string | 确认 |
| confirmButtonColor | 确认按钮颜色 | string | #ee0a24 |
| cancelButtonText | 取消按钮文案 | string | 取消 |
| cancelButtonColor | 取消按钮颜色 | string | black |
| overlay | 是否展示遮罩层 | boolean | true |
| overlayClass | 自定义遮罩层类名 | string | Array | object | - |
| overlayStyle | 自定义遮罩层样式 | object | - |
| closeOnPopstate | 是否在页面回退时自动关闭 | boolean | true |
| closeOnClickOverlay | 是否在点击遮罩层后关闭弹窗 | boolean | false |
| lockScroll | 是否锁定背景滚动 | boolean | true |
| allowHtml | 是否允许 message 内容中渲染 HTML | boolean | false |
| beforeClose | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | body |
通过组件调用 Dialog 时，支持以下 Props：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示弹窗 | boolean | - |
| title | 标题 | string | - |
| width | 弹窗宽度，默认单位为 px | number | string | 320px |
| message | 文本内容，支持通过
换行 | string | () => JSX.ELement | - |
| message-align | 内容水平对齐方式，可选值为 left right | string | center |
| theme | 样式风格，可选值为 round-button | string | default |
| show-confirm-button | 是否展示确认按钮 | boolean | true |
| show-cancel-button | 是否展示取消按钮 | boolean | false |
| confirm-button-text | 确认按钮文案 | string | 确认 |
| confirm-button-color | 确认按钮颜色 | string | #ee0a24 |
| cancel-button-text | 取消按钮文案 | string | 取消 |
| cancel-button-color | 取消按钮颜色 | string | black |
| overlay | 是否展示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭弹窗 | boolean | false |
| lazy-render | 是否在显示弹层时才渲染节点 | boolean | true |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| allow-html | 是否允许 message 内容中渲染 HTML | boolean | false |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
| transition | 动画类名，等价于 transition 的 name 属性 | string | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 Dialog 时，支持以下事件：
| 事件 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击确认按钮时触发 | - |
| cancel | 点击取消按钮时触发 | - |
| open | 打开弹窗时触发 | - |
| close | 关闭弹窗时触发 | - |
| opened | 打开弹窗且动画结束后触发 | - |
| closed | 关闭弹窗且动画结束后触发 | - |
通过组件调用 Dialog 时，支持以下插槽：
| 名称 | 说明 |
|---|---|
| default | 自定义内容 |
| title | 自定义标题 |
footer v3.0.10 | 自定义底部按钮区域 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-dialog-width | 320px | - |
| --van-dialog-small-screen-width | 90% | - |
| --van-dialog-font-size | var(--van-font-size-lg) | - |
| --van-dialog-transition | var(--van-animation-duration-base) | - |
| --van-dialog-border-radius | 16px | - |
| --van-dialog-background-color | var(--van-white) | - |
| --van-dialog-header-font-weight | var(--van-font-weight-bold) | - |
| --van-dialog-header-line-height | 24px | - |
| --van-dialog-header-padding-top | 26px | - |
| --van-dialog-header-isolated-padding | var(--van-padding-lg) 0 | - |
| --van-dialog-message-padding | var(--van-padding-lg) | - |
| --van-dialog-message-font-size | var(--van-font-size-md) | - |
| --van-dialog-message-line-height | var(--van-line-height-md) | - |
| --van-dialog-message-max-height | 60vh | - |
| --van-dialog-has-title-message-text-color | var(--van-gray-7) | - |
| --van-dialog-has-title-message-padding-top | var(--van-padding-xs) | - |
| --van-dialog-button-height | 48px | - |
| --van-dialog-round-button-height | 36px | - |
| --van-dialog-confirm-button-text-color | var(--van-danger-color) | - |
将 closeOnPopstate 属性设置为 false 即可。
Dialog.alert({ title: '标题', message: '弹窗内容', closeOnPopstate: false,}).then(() => { // on close});请注意 Dialog 是一个函数，Dialog.Component 才是 Dialog 对应的组件。JSX 调用弹窗的正确姿势如下：
export default { setup() { const show = ref(false); return () => <Dialog.Component v-model={[show, 'show']} />; },};向下弹出的菜单列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { DropdownMenu, DropdownItem } from 'vant';const app = createApp();app.use(DropdownMenu);app.use(DropdownItem);<van-dropdown-menu> <van-dropdown-item v-model="state.value1" :options="option1" /> <van-dropdown-item v-model="state.value2" :options="option2" /></van-dropdown-menu>import { reactive } from 'vue';export default { setup() { const state = reactive({ value1: 0, value2: 'a', }); const option1 = [ { text: '全部商品', value: 0 }, { text: '新款商品', value: 1 }, { text: '活动商品', value: 2 }, ]; const option2 = [ { text: '默认排序', value: 'a' }, { text: '好评排序', value: 'b' }, { text: '销量排序', value: 'c' }, ]; return { state, option1, option2, }; },};通过插槽可以自定义 DropdownItem 的内容，此时需要使用实例上的 toggle 方法手动控制菜单的显示。
<van-dropdown-menu> <van-dropdown-item v-model="value" :options="option" /> <van-dropdown-item title="筛选" ref="item"> <van-cell center title="包邮"> <template #right-icon> <van-switch v-model="switch1" size="24" active-color="#ee0a24" /> </template> </van-cell> <van-cell center title="团购"> <template #right-icon> <van-switch v-model="switch2" size="24" active-color="#ee0a24" /> </template> </van-cell> <div style="padding: 5px 16px;"> <van-button type="danger" block round @click="onConfirm"> 确认 </van-button> </div> </van-dropdown-item></van-dropdown-menu>import { ref, reactive } from 'vue';export default { setup() { const item = ref(null); const state = reactive({ value: 0, switch1: false, switch2: false, }); const options = [ { text: '全部商品', value: 0 }, { text: '新款商品', value: 1 }, { text: '活动商品', value: 2 }, ]; const onConfirm = () => { item.value.toggle(); }; return { item, state, options, onConfirm, }; },};通过 active-color 属性可以自定义菜单标题和选项的选中态颜色。
<van-dropdown-menu active-color="#1989fa"> <van-dropdown-item v-model="value1" :options="option1" /> <van-dropdown-item v-model="value2" :options="option2" /></van-dropdown-menu>将 direction 属性值设置为 up，菜单即可向上展开。
<van-dropdown-menu direction="up"> <van-dropdown-item v-model="value1" :options="option1" /> <van-dropdown-item v-model="value2" :options="option2" /></van-dropdown-menu><van-dropdown-menu> <van-dropdown-item v-model="value1" disabled :options="option1" /> <van-dropdown-item v-model="value2" disabled :options="option2" /></van-dropdown-menu>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| active-color | 菜单标题和选项的选中态颜色 | string | #ee0a24 |
| direction | 菜单展开方向，可选值为up | string | down |
| z-index | 菜单栏 z-index 层级 | number | string | 10 |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.2 |
| overlay | 是否显示遮罩层 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭菜单 | boolean | true |
| close-on-click-outside | 是否在点击外部元素后关闭菜单 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中项对应的 value | number | string | - |
| title | 菜单项标题 | string | 当前选中项文字 |
| options | 选项数组 | Option[] | [] |
| disabled | 是否禁用菜单 | boolean | false |
| lazy-render | 是否在首次展开时才渲染菜单内容 | boolean | true |
| title-class | 标题额外类名 | string | Array | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 点击选项导致 value 变化时触发 | value |
| open | 打开菜单栏时触发 | - |
| close | 关闭菜单栏时触发 | - |
| opened | 打开菜单栏且动画结束后触发 | - |
| closed | 关闭菜单栏且动画结束后触发 | - |
| 名称 | 说明 |
|---|---|
| default | 菜单内容 |
| title | 自定义菜单项标题 |
通过 ref 可以获取到 DropdownItem 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换菜单展示状态，传 true 为显示，false 为隐藏，不传参为取反 | show?: boolean | - |
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 文字 | string |
| value | 标识符 | number | string |
| icon | 左侧图标名称或图片链接 | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-dropdown-menu-height | 48px | - |
| --van-dropdown-menu-background-color | var(--van-white) | - |
| --van-dropdown-menu-box-shadow | 0 2px 12px fade(var(--van-gray-7), 12) | - |
| --van-dropdown-menu-title-font-size | 15px | - |
| --van-dropdown-menu-title-text-color | var(--van-text-color) | - |
| --van-dropdown-menu-title-active-text-color | var(--van-danger-color) | - |
| --van-dropdown-menu-title-disabled-text-color | var(--van-gray-6) | - |
| --van-dropdown-menu-title-padding | 0 var(--van-padding-xs) | - |
| --van-dropdown-menu-title-line-height | var(--van-line-height-lg) | - |
| --van-dropdown-menu-option-active-color | var(--van-danger-color) | - |
| --van-dropdown-menu-content-max-height | 80% | - |
| --van-dropdown-item-z-index | 10 | - |
把 DropdownMenu 嵌套在 Tabs 等组件内部使用时，可能会遇到下拉菜单位置错误的问题。这是因为在 Chrome 浏览器中，transform 元素内部的 fixed 布局会降级成 absolute 布局，导致下拉菜单的布局异常。
将 DropdownItem 的 teleport 属性设置为 body 即可避免此问题：
<van-dropdown-menu> <van-dropdown-item teleport="body" /> <van-dropdown-item teleport="body" /></van-dropdown-menu>加载图标，用于表示加载中的过渡状态。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Loading } from 'vant';const app = createApp();app.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>通过 color 或者 text-color 属性设置加载文案的颜色。
<!-- 可修改文案和加载图标的颜色 --><van-loading color="#0094ff" /><!-- 只修改文案颜色 --><van-loading text-color="#0094ff" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| color | 颜色 | string | #c9c9c9 |
| type | 类型，可选值为 spinner | string | circular |
| size | 加载图标大小，默认单位为 px | number | string | 30px |
| text-size | 文字大小，默认单位为 px | number | string | 14px |
| text-color | 文字颜色 | string | #c9c9c9 |
| vertical | 是否垂直排列图标和文字内容 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 加载文案 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-loading-text-color | var(--van-gray-6) | - |
| --van-loading-text-font-size | var(--van-font-size-md) | - |
| --van-loading-spinner-color | var(--van-gray-5) | - |
| --van-loading-spinner-size | 30px | - |
| --van-loading-spinner-animation-duration | 0.8s | - |
在页面顶部展示消息提示，支持函数调用和组件调用两种方式。
Notify 是一个函数，调用后会直接在页面中弹出相应的消息提示。
import { Notify } from 'vant';Notify('通知内容');通过组件调用 Notify 时，可以通过下面的方式进行注册：
import { createApp } from 'vue';import { Notify } from 'vant';// 全局注册const app = createApp();app.use(Notify);// 局部注册export default { components: { [Notify.Component.name]: Notify.Component, },};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,});通过 app.use 全局注册 Notify 组件后，会自动在 app 的所有子组件上挂载 $notify 方法，便于在组件内调用。
export default { mounted() { this.$notify('提示文案'); },};Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
如果需要在 Notify 内嵌入组件或其他自定义内容，可以使用组件调用的方式。
<van-button type="primary" text="组件调用" @click="showNotify" /><van-notify v-model:show="show" type="success"> <van-icon name="bell" style="margin-right: 4px;" /> <span>通知内容</span></van-notify>import { ref } from 'vue';export default { setup() { const show = ref(false); const showNotify = () => { show.value = true; setTimeout(() => { show.value = false; }, 2000); }; return { show, showNotify, }; },};| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| Notify | 展示提示 | options | message | notify 实例 |
| Notify.clear | 关闭提示 | - | void |
| Notify.setDefaultOptions | 修改默认配置，对所有 Notify 生效 | options | void |
| Notify.resetDefaultOptions | 重置默认配置，对所有 Notify 生效 | - | void |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success warning | string | danger |
| message | 展示文案，支持通过
换行 | string | - |
| duration | 展示时长(ms)，值为 0 时，notify 不会消失 | number | string | 3000 |
| color | 字体颜色 | string | white |
| background | 背景颜色 | string | - |
| className | 自定义类名 | string | Array | object | - |
lockScroll v3.0.7 | 是否锁定背景滚动 | boolean | false |
| onClick | 点击时的回调函数 | (event: MouseEvent): void | - |
| onOpened | 完全展示后的回调函数 | () => void | - |
| onClose | 关闭时的回调函数 | () => void | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-notify-text-color | var(--van-white) | - |
| --van-notify-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-notify-font-size | var(--van-font-size-md) | - |
| --van-notify-line-height | var(--van-line-height-md) | - |
| --van-notify-primary-background-color | var(--van-primary-color) | - |
| --van-notify-success-background-color | var(--van-success-color) | - |
| --van-notify-danger-background-color | var(--van-danger-color) | - |
| --van-notify-warning-background-color | var(--van-warning-color) | - |
创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Overlay } from 'vant';const app = createApp();app.use(Overlay);<van-button type="primary" text="显示遮罩层" @click="show = true" /><van-overlay :show="show" @click="show = false" />import { ref } from 'vue';export default { setup() { const show = ref(false); return { show }; },};通过默认插槽可以在遮罩层上嵌入任意内容。
<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>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| show | 是否展示遮罩层 | boolean | false |
| z-index | z-index 层级 | number | string | 1 |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| class-name | 自定义类名 | string | - |
| custom-style | 自定义样式 | object | - |
| lock-scroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 默认插槽，用于在遮罩层上方嵌入内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-overlay-z-index | 1 | - |
| --van-overlay-background-color | rgba(0, 0, 0, 0.7) | - |
用于提供下拉刷新的交互操作。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { PullRefresh } from 'vant';const app = createApp();app.use(PullRefresh);下拉刷新时会触发 refresh 事件，在事件的回调函数中可以进行同步或异步操作，操作完成后将 v-model 设置为 false，表示加载完成。
<van-pull-refresh v-model="state.loading" @refresh="onRefresh"> <p>刷新次数: {{ state.count }}</p></van-pull-refresh>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ count: 0, loading: false, }); const onRefresh = () => { setTimeout(() => { Toast('刷新成功'); state.loading = false; state.count++; }, 1000); }; return { state, onRefresh, }; },};通过 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 实现一个缩放效果 --> <template #pulling="props"> <img class="doge" src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow" rel="external nofollow" :style="{ transform: `scale(${props.distance / 80})` }" /> </template> <!-- 释放提示 --> <template #loosing> <img class="doge" src="https://img.yzcdn.cn/vant/doge.png" rel="external nofollow" rel="external nofollow" /> </template> <!-- 加载提示 --> <template #loading> <img class="doge" src="https://img.yzcdn.cn/vant/doge-fire.jpg" rel="external nofollow" /> </template> <p>刷新次数: {{ count }}</p></van-pull-refresh><style> .doge { width: 140px; height: 72px; margin-top: 8px; border-radius: 4px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 是否处于加载中状态 | boolean | - |
| pulling-text | 下拉过程提示文案 | string | 下拉即可刷新... |
| loosing-text | 释放过程提示文案 | string | 释放即可刷新... |
| loading-text | 加载过程提示文案 | string | 加载中... |
| success-text | 刷新成功提示文案 | string | - |
| success-duration | 刷新成功提示展示时长(ms) | number | string | 500 |
| animation-duration | 动画时长 | number | string | 300 |
| head-height | 顶部内容高度 | number | string | 50 |
pull-distance v3.0.8 | 触发下拉刷新的距离 | number | string | 与 head-height 一致 |
| disabled | 是否禁用下拉刷新 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| refresh | 下拉刷新时触发 | - |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义内容 | - |
| normal | 非下拉状态时顶部内容 | - |
| pulling | 下拉过程中顶部内容 | { distance: 当前下拉距离 } |
| loosing | 释放过程中顶部内容 | { distance: 当前下拉距离 } |
| loading | 加载过程中顶部内容 | { distance: 当前下拉距离 } |
| success | 刷新成功提示内容 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-pull-refresh-head-height | 50px | - |
| --van-pull-refresh-head-font-size | var(--van-font-size-md) | - |
| --van-pull-refresh-head-text-color | var(--van-gray-6) | - |
| --van-pull-refresh-loading-icon-size | 16px | - |
默认情况下，下拉区域的高度是和内容高度保持一致的，如果需要让下拉区域始终为全屏，可以给 PullRefresh 设置一个与屏幕大小相等的最小高度：
<van-pull-refresh style="min-height: 100vh;" />PullRefresh 的触发条件是「父级滚动元素的滚动条在顶部位置」。
参见桌面端适配。
底部弹起的分享面板，用于展示各分享渠道对应的操作按钮，不含具体的分享逻辑。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ShareSheet } from 'vant';const app = createApp();app.use(ShareSheet);分享面板通过 options 属性来定义分享选项，数组的每一项是一个对象，对象格式见文档下方表格。
<van-cell title="显示分享面板" @click="showShare = true" /><van-share-sheet v-model:show="showShare" title="立即分享给好友" :options="options" @select="onSelect"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const showShare = ref(false); const options = [ { name: '微信', icon: 'wechat' }, { name: '微博', icon: 'weibo' }, { name: '复制链接', icon: 'link' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, ]; const onSelect = (option) => { Toast(option.name); showShare.value = false; }; return { options, onSelect, showShare, }; },};当分享选项的数量较多时，可以将 options 定义为数组嵌套的格式，每个子数组会作为一行选项展示。
<van-share-sheet v-model:show="showShare" title="立即分享给好友" :options="options"/>import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ [ { name: '微信', icon: 'wechat' }, { name: '朋友圈', icon: 'wechat-moments' }, { name: '微博', icon: 'weibo' }, { name: 'QQ', icon: 'qq' }, ], [ { name: '复制链接', icon: 'link' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, { name: '小程序码', icon: 'weapp-qrcode' }, ], ]; return { options, showShare, }; },};除了使用内置的几种图标外，可以直接在 icon 中传入图片 URL 来使用自定义的图标。
<van-share-sheet v-model:show="showShare" :options="options" />import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-fire.png', }, { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-light.png', }, { name: '名称', icon: 'https://img.yzcdn.cn/vant/custom-icon-water.png', }, ]; return { options, showShare, }; },};通过 description 属性可以设置标题下方的描述文字, 在 options 内设置 description 属性可以添加分享选项描述。
<van-share-sheet v-model:show="showShare" :options="options" title="立即分享给好友" description="描述信息"/>import { ref } from 'vue';export default { setup() { const showShare = ref(false); const options = [ { name: '微信', icon: 'wechat' }, { name: '微博', icon: 'weibo' }, { name: '复制链接', icon: 'link', description: '描述信息' }, { name: '分享海报', icon: 'poster' }, { name: '二维码', icon: 'qrcode' }, ]; return { options, showShare, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否显示分享面板 | boolean | false |
| options | 分享选项 | Option[] | [] |
| title | 顶部标题 | string | - |
| cancel-text | 取消按钮文字，传入空字符串可以隐藏按钮 | string | '取消' |
| description | 标题下方的辅助描述文字 | string | - |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| overlay | 是否显示遮罩层 | boolean | true |
| overlay-class | 自定义遮罩层类名 | string | Array | object | - |
| overlay-style | 自定义遮罩层样式 | object | - |
| lock-scroll | 是否锁定背景滚动 | boolean | true |
| lazy-render | 是否在显示弹层时才渲染内容 | boolean | true |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| close-on-click-overlay | 是否在点击遮罩层后关闭 | boolean | true |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
before-close v3.1.4 | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (action: string) => boolean | Promise<boolean> | - |
options 属性为一个对象数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 分享渠道名称 | string |
| description | 分享选项描述 | string |
| icon | 图标，可选值为 wechat weibo qq link qrcode poster weapp-qrcode wechat-moments，支持传入图片 URL | string |
| className | 分享选项类名 | string |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击分享选项时触发 | option: Option, index: number |
| cancel | 点击取消按钮时触发 | - |
| open | 打开面板时触发 | - |
| close | 关闭面板时触发 | - |
| opened | 打开面板且动画结束后触发 | - |
| closed | 关闭面板且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| title | 自定义顶部标题 |
| description | 自定义描述文字 |
cancel v3.0.10 | 自定义取消按钮内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-share-sheet-header-padding | var(--van-padding-sm) var(--van-padding-md) var(--van-padding-base) | - |
| --van-share-sheet-title-color | var(--van-text-color) | - |
| --van-share-sheet-title-font-size | var(--van-font-size-md) | - |
| --van-share-sheet-title-line-height | var(--van-line-height-md) | - |
| --van-share-sheet-description-color | var(--van-gray-6) | - |
| --van-share-sheet-description-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-description-line-height | 16px | - |
| --van-share-sheet-icon-size | 48px | - |
| --van-share-sheet-option-name-color | var(--van-gray-7) | - |
| --van-share-sheet-option-name-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-option-description-color | var(--van-gray-5) | - |
| --van-share-sheet-option-description-font-size | var(--van-font-size-sm) | - |
| --van-share-sheet-cancel-button-font-size | var(--van-font-size-lg) | - |
| --van-share-sheet-cancel-button-height | 48px | - |
| --van-share-sheet-cancel-button-background | var(--van-white) | - |
在不同的 App 或浏览器中，存在各式各样的分享接口或分享方式，因此 ShareSheet 组件不提供具体的分享逻辑，需要开发者根据业务场景自行实现。
由于微信未提供分享相关的 API，需要引导用户点击右上角进行分享。
可以通过 JSBridge 调用原生应用的 SDK 进行分享。
可以通过 Popup 组件以弹层的形式展示图片，然后引导用户保存图片进行分享。
可以左右滑动来展示操作按钮的单元格组件。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { SwipeCell } from 'vant';const app = createApp();app.use(SwipeCell);SwipeCell 组件提供了 left 和 right 两个插槽，用于定义两侧滑动区域的内容。
<van-swipe-cell> <template #left> <van-button square type="primary" text="选择" /> </template> <van-cell :border="false" title="单元格" value="内容" /> <template #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" /> <template #right> <van-button square text="删除" type="danger" class="delete-button" /> </template></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 #left> <van-button square type="primary" text="选择" /> </template> <van-cell :border="false" title="单元格" value="内容" /> <template #right> <van-button square type="danger" text="删除" /> </template></van-swipe-cell>import { Dialog } from 'vant';export default { setup() { // position 为关闭时点击的位置 const beforeClose = ({ position }) => { switch (position) { case 'left': case 'cell': case 'outside': return true; case 'right': return new Promise((resolve) => { Dialog.confirm({ title: '确定删除吗？', }).then(resolve); }); } }; return { beforeClose }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符，可以在事件参数中获取到 | number | string | '' |
| left-width | 指定左侧滑动区域宽度，单位为 px | number | string | auto |
| right-width | 指定右侧滑动区域宽度，单位为 px | number | string | auto |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (args) => boolean | Promise<boolean> | - |
| disabled | 是否禁用滑动 | boolean | false |
| stop-propagation | 是否阻止滑动事件冒泡 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 默认显示的内容 |
| left | 左侧滑动区域的内容 |
| right | 右侧滑动区域的内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | position: 'left' | 'right' | 'cell' | 'outside' |
| open | 打开时触发 | { name: string | number, position: 'left' | 'right' } |
| close | 关闭时触发 | { name: string | number, position: 'left' | 'right' | 'cell' | 'outside' } |
beforeClose 的第一个参数为对象，对象中包含以下属性：
| 参数名 | 说明 | 类型 |
|---|---|---|
| name | 标识符 | string | number |
| position | 关闭时的点击位置 | 'left' | 'right' | 'cell' | 'outside' |
通过 ref 可以获取到 SwipeCell 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| open | 打开单元格侧边栏 | position: left | right | - |
| close | 收起单元格侧边栏 | - | - |
通过 SwipeCellInstance 获取 SwipeCell 实例的类型定义。
import { ref } from 'vue';import type { SwipeCellInstance } from 'vant';const swipeCellRef = ref<SwipeCellInstance>();swipeCellRef.value?.close();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-switch-cell-padding-top | var(--van-cell-vertical-padding) - 1px | - |
| --van-switch-cell-padding-bottom | var(--van-cell-vertical-padding) - 1px | - |
| --van-switch-cell-large-padding-top | var(--van-cell-large-vertical-padding) - 1px | - |
| --van-switch-cell-large-padding-bottom | var(--van-cell-large-vertical-padding) - 1px | - |
参见桌面端适配。
在右上角展示徽标数字或小红点。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Badge } from 'vant';const app = createApp();app.use(Badge);设置 content 属性后，Badge 会在子元素的右上角显示对应的徽标，也可以通过 dot 来显示小红点。
<van-badge :content="5"> <div class="child" /></van-badge><van-badge :content="10"> <div class="child" /></van-badge><van-badge content="Hot"> <div class="child" /></van-badge><van-badge dot> <div class="child" /></van-badge><style> .child { width: 40px; height: 40px; background: #f2f3f5; border-radius: 4px; }</style>设置 max 属性后，当 content 的数值超过最大值时，会自动显示为 {max}+。
<van-badge :content="20" max="9"> <div class="child" /></van-badge><van-badge :content="50" max="20"> <div class="child" /></van-badge><van-badge :content="200" max="99"> <div class="child" /></van-badge>通过 color 属性来设置徽标的颜色。
<van-badge :content="5" color="#1989fa"> <div class="child" /></van-badge><van-badge :content="10" color="#1989fa"> <div class="child" /></van-badge><van-badge dot color="#1989fa"> <div class="child" /></van-badge>通过 content 插槽可以自定义徽标的内容，比如插入一个图标。
<van-badge> <div class="child" /> <template #content> <van-icon name="success" class="badge-icon" /> </template></van-badge><van-badge> <div class="child" /> <template #content> <van-icon name="cross" class="badge-icon" /> </template></van-badge><van-badge> <div class="child" /> <template #content> <van-icon name="down" class="badge-icon" /> </template></van-badge>.badge-icon { display: block; font-size: 10px; line-height: 16px;}当 Badge 没有子元素时，会作为一个独立的元素进行展示。
<van-badge :content="20" /><van-badge :content="200" max="99" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 徽标内容 | number | string | - |
| color | 徽标背景颜色 | string | #ee0a24 |
| dot | 是否展示为小红点 | boolean | false |
| max | 最大值，超过最大值会显示 {max}+，仅当 content 为数字时有效 | number | string | - |
offset v3.0.5 | 设置徽标的偏移量，数组的两项分别对应水平和垂直方向的偏移量，默认单位为 px | [number | string, number | string] | - |
show-zero v3.0.10 | 当 content 为数字 0 时，是否展示徽标 | boolean | true |
| 名称 | 说明 |
|---|---|
| default | 徽标包裹的子元素 |
| content | 自定义徽标内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-badge-size | 16px | - |
| --van-badge-color | var(--van-white) | - |
| --van-badge-padding | 0 3px | - |
| --van-badge-font-size | var(--van-font-size-sm) | - |
| --van-badge-font-weight | var(--van-font-weight-bold) | - |
| --van-badge-border-width | var(--van-border-width-base) | - |
| --van-badge-background-color | var(--van-danger-color) | - |
| --van-badge-dot-color | var(--van-danger-color) | - |
| --van-badge-dot-size | 8px | - |
| --van-badge-font-family | -apple-system-font, Helvetica Neue, Arial, sans-serif | - |
圆环形的进度条组件，支持进度渐变动画。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Circle } from 'vant';const app = createApp();app.use(Circle);rate 属性表示进度条的目标进度，v-model:current-rate 表示动画过程中的实时进度。当 rate 发生变化时，v-model:current-rate 会以 speed 的速度变化，直至达到 rate 设定的值。
<van-circle v-model:current-rate="currentRate" :rate="30" :speed="100" :text="text"/>import { ref, computed } from 'vue';export default { setup() { const currentRate = ref(0); const text = computed(() => currentRate.value.toFixed(0) + '%'); return { text, currentRate, }; },};通过 stroke-width 属性来控制进度条宽度。
<van-circle v-model:current-rate="currentRate" :rate="rate" :stroke-width="60" text="宽度定制"/>通过 color 属性来控制进度条颜色，layer-color 属性来控制轨道颜色。
<van-circle v-model:current-rate="currentRate" :rate="rate" layer-color="#ebedf0" text="颜色定制"/>color 属性支持传入对象格式来定义渐变色。
<van-circle v-model:current-rate="currentRate" :rate="rate" :color="gradientColor" text="渐变色"/>import { ref } from 'vue';export default { setup() { const currentRate = ref(0); const gradientColor = { '0%': '#3fecff', '100%': '#6149f6', }; return { currentRate, gradientColor, }; },};将 clockwise 设置为 false，进度会从逆时针方向开始。
<van-circle v-model:current-rate="currentRate" :rate="rate" :clockwise="false" text="逆时针方向"/>通过 size 属性设置圆环直径。
<van-circle v-model:current-rate="currentRate" :rate="rate" size="120px" text="大小定制"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:current-rate | 当前进度 | number | - |
| rate | 目标进度 | number | string | 100 |
| size | 圆环直径，默认单位为 px | number | string | 100px |
| color | 进度条颜色，传入对象格式可以定义渐变色 | string | object | #1989fa |
| layer-color | 轨道颜色 | string | white |
| fill | 填充颜色 | string | none |
| speed | 动画速度（单位为 rate/s） | number | string | 0 |
| text | 文字 | string | - |
| stroke-width | 进度条宽度 | number | string | 40 |
| stroke-linecap | 进度条端点的形状，可选值为 square butt | string | round |
| clockwise | 是否顺时针增加 | boolean | true |
| 名称 | 说明 |
|---|---|
| default | 自定义文字内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-circle-size | 100px | - |
| --van-circle-color | var(--van-primary-color) | - |
| --van-circle-layer-color | var(--van-white) | - |
| --van-circle-text-color | var(--van-text-color) | - |
| --van-circle-text-font-weight | var(--van-font-weight-bold) | - |
| --van-circle-text-font-size | var(--van-font-size-md) | - |
| --van-circle-text-line-height | var(--van-line-height-md) | - |
将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Collapse, CollapseItem } from 'vant';const app = createApp();app.use(Collapse);app.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">内容</van-collapse-item></van-collapse>import { ref } from 'vue';export default { setup() { const activeNames = ref(['1']); return { activeNames }; },};通过 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>import { ref } from 'vue';export default { setup() { const activeName = ref('1'); return { activeName }; },};通过 disabled 属性来禁用单个面板。
<van-collapse v-model="activeNames"> <van-collapse-item title="标题1" name="1">内容</van-collapse-item> <van-collapse-item title="标题2" name="2" disabled>内容</van-collapse-item> <van-collapse-item title="标题3" name="3" disabled>内容</van-collapse-item></van-collapse>通过 title 插槽可以自定义标题栏的内容。
<van-collapse v-model="activeNames"> <van-collapse-item name="1"> <template #title> <div>标题1 <van-icon name="question-o" /></div> </template> 内容 </van-collapse-item> <van-collapse-item title="标题2" name="2" icon="shop-o"> 内容 </van-collapse-item></van-collapse>import { ref } from 'vue';export default { setup() { const activeNames = ref(['1']); return { activeNames }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前展开面板的 name | 手风琴模式：number | string 非手风琴模式：(number | string)[] | - |
| accordion | 是否开启手风琴模式 | boolean | false |
| border | 是否显示外边框 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换面板时触发 | activeNames: 类型与 v-model 绑定的值一致 |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 唯一标识符，默认为索引值 | number | string | index |
| icon | 标题栏左侧图标名称或图片链接 | string | - |
| size | 标题栏大小，可选值为 large | string | - |
| title | 标题栏左侧内容 | number | string | - |
| value | 标题栏右侧内容 | number | string | - |
| label | 标题栏描述信息 | number | string | - |
| border | 是否显示内边框 | boolean | true |
| is-link | 是否展示标题栏右侧箭头并开启点击反馈 | boolean | true |
| disabled | 是否禁用面板 | boolean | false |
readonly v3.0.12 | 是否为只读状态，只读状态下无法操作面板 | boolean | false |
| title-class | 左侧标题额外类名 | string | - |
| value-class | 右侧内容额外类名 | string | - |
| label-class | 描述信息额外类名 | string | - |
通过 ref 可以获取到 CollapseItem 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| toggle | 切换面试展开状态，传 true 为展开，false 为收起，不传参为切换 | expand?: boolean | - |
通过 CollapseItemInstance 获取 CollapseItem 实例的类型定义。
import { ref } from 'vue';import type { CollapseItemInstance } from 'vant';const collapseItemRef = ref<CollapseItemInstance>();collapseItemRef.value?.toggle();| 名称 | 说明 |
|---|---|
| default | 面板内容 |
| title | 自定义标题栏左侧内容 |
| value | 自定义标题栏右侧内容 |
label v3.1.1 | 自定义标题栏描述信息 |
| icon | 自定义标题栏左侧图标 |
| right-icon | 自定义标题栏右侧图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-collapse-item-transition-duration | var(--van-animation-duration-base) | - |
| --van-collapse-item-content-padding | var(--van-padding-sm) var(--van-padding-md) | - |
| --van-collapse-item-content-font-size | var(--van-font-size-md) | - |
| --van-collapse-item-content-line-height | 1.5 | - |
| --van-collapse-item-content-text-color | var(--van-gray-6) | - |
| --van-collapse-item-content-background-color | var(--van-white) | - |
| --van-collapse-item-title-disabled-color | var(--van-gray-5) | - |
用于实时展示倒计时数值，支持毫秒精度。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { CountDown } from 'vant';const app = createApp();app.use(CountDown);time 属性表示倒计时总时长，单位为毫秒。
<van-count-down :time="time" />import { ref } from 'vue';export default { setup() { const time = ref(30 * 60 * 60 * 1000); return { time }; },};通过 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 #default="timeData"> <span class="block">{{ timeData.hours }}</span> <span class="colon">:</span> <span class="block">{{ timeData.minutes }}</span> <span class="colon">:</span> <span class="block">{{ timeData.seconds }}</span> </template></van-count-down><style> .colon { display: inline-block; margin: 0 4px; color: #ee0a24; } .block { display: inline-block; width: 22px; color: #fff; font-size: 12px; text-align: center; background-color: #ee0a24; }</style>通过 ref 获取到组件实例后，可以调用 start、pause、reset 方法。
<van-count-down ref="countDown" millisecond :time="3000" :auto-start="false" format="ss:SSS" @finish="onFinish"/><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 { setup() { const countDown = ref(null); const start = () => { countDown.value.start(); }; const pause = () => { countDown.value.pause(); }; const reset = () => { countDown.value.reset(); }; const onFinish = () => Toast('倒计时结束'); return { start, pause, reset, onFinish, countDown, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| time | 倒计时时长，单位毫秒 | number | string | 0 |
| format | 时间格式 | string | HH:mm:ss |
| auto-start | 是否自动开始倒计时 | boolean | true |
| millisecond | 是否开启毫秒级渲染 | boolean | false |
| 格式 | 说明 |
|---|---|
| DD | 天数 |
| HH | 小时 |
| mm | 分钟 |
| ss | 秒数 |
| S | 毫秒（1 位） |
| SS | 毫秒（2 位） |
| SSS | 毫秒（3 位） |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| finish | 倒计时结束时触发 | - |
| change | 倒计时变化时触发 | currentTime: CurrentTime |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义内容 | currentTime: CurrentTime |
| 名称 | 说明 | 类型 |
|---|---|---|
| total | 剩余总时间（单位毫秒） | number |
| days | 剩余天数 | number |
| hours | 剩余小时 | number |
| minutes | 剩余分钟 | number |
| seconds | 剩余秒数 | number |
| milliseconds | 剩余毫秒 | number |
通过 ref 可以获取到 CountDown 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| start | 开始倒计时 | - | - |
| pause | 暂停倒计时 | - | - |
| reset | 重设倒计时，若 auto-start 为 true，重设后会自动开始倒计时 | - | - |
通过 CountDownInstance 获取 CountDown 实例的类型定义。
import { ref } from 'vue';import type { CountDownInstance } from 'vant';const countDownRef = ref<CountDownInstance>();countDownRef.value?.start();组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-count-down-text-color | var(--van-text-color) | - |
| --van-count-down-font-size | var(--van-font-size-md) | - |
| --van-count-down-line-height | var(--van-line-height-md) | - |
如果你遇到了在 iOS 上倒计时不生效的问题，请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是new Date('2020/01/01')。
对此问题的详细解释：stackoverflow。
用于将内容分隔为多个区域。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Divider } from 'vant';const app = createApp();app.use(Divider);默认渲染一条水平分割线。
<van-divider />通过插槽在可以分割线中间插入内容。
<van-divider>文字</van-divider>通过 content-position 指定内容所在位置。
<van-divider content-position="left">文字</van-divider><van-divider content-position="right">文字</van-divider>添加 dashed 属性使分割线渲染为虚线。
<van-divider dashed>文字</van-divider>可以直接通过 style 属性设置分割线的样式。
<van-divider :style="{ color: '#1989fa', borderColor: '#1989fa', padding: '0 16px' }"> 文字</van-divider>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| dashed | 是否使用虚线 | boolean | false |
| hairline | 是否使用 0.5px 线 | boolean | true |
| content-position | 内容位置，可选值为 left right | string | center |
| 名称 | 说明 |
|---|---|
| default | 内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-divider-margin | var(--van-padding-md) 0 | - |
| --van-divider-text-color | var(--van-gray-6) | - |
| --van-divider-font-size | var(--van-font-size-md) | - |
| --van-divider-line-height | 24px | - |
| --van-divider-border-color | var(--van-border-color) | - |
| --van-divider-content-padding | var(--van-padding-md) | - |
| --van-divider-content-left-width | 10% | - |
| --van-divider-content-right-width | 10% | - |
空状态时的占位提示。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Empty } from 'vant';const app = createApp();app.use(Empty);<van-empty description="描述文字" />Empty 组件内置了多种占位图片类型，可以在不同业务场景下使用。
<!-- 通用错误 --><van-empty image="error" description="描述文字" /><!-- 网络错误 --><van-empty image="network" description="描述文字" /><!-- 搜索提示 --><van-empty image="search" description="描述文字" />需要自定义图片时，可以在 image 属性中传入任意图片 URL。
<van-empty class="custom-image" image="https://img.yzcdn.cn/vant/custom-empty-image.png" description="描述文字"/><style> .custom-image .van-empty__image { width: 90px; height: 90px; }</style>通过默认插槽可以在 Empty 组件的下方插入内容。
<van-empty description="描述文字"> <van-button round type="danger" class="bottom-button">按钮</van-button></van-empty><style> .bottom-button { width: 160px; height: 40px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| image | 图片类型，可选值为 error network search，支持传入图片 URL | string | default |
| image-size | 图片大小，默认单位为 px | number | string | - |
| description | 图片下方的描述文字 | string | - |
| 名称 | 说明 |
|---|---|
| default | 自定义底部内容 |
| image | 自定义图标 |
| description | 自定义描述文字 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-empty-padding | var(--van-padding-xl) 0 | - |
| --van-empty-image-size | 160px | - |
| --van-empty-description-margin-top | var(--van-padding-md) | - |
| --van-empty-description-padding | 0 60px | - |
| --van-empty-description-color | var(--van-gray-6) | - |
| --van-empty-description-font-size | var(--van-font-size-md) | - |
| --van-empty-description-line-height | var(--van-line-height-md) | - |
| --van-empty-bottom-margin-top | 24px | - |
图片放大预览，支持函数调用和组件调用两种方式。
ImagePreview 是一个函数，调用函数后会直接在页面中展示图片预览界面。
import { ImagePreview } from 'vant';ImagePreview(['https://img.yzcdn.cn/vant/apple-1.jpg']);通过组件调用 ImagePreview 时，可以通过下面的方式进行注册。
import { createApp } from 'vue';import { ImagePreview } from 'vant';// 全局注册const app = createApp();app.use(ImagePreview);// 局部注册export default { components: { [ImagePreview.Component.name]: ImagePreview.Component, },};直接传入图片数组，即可展示图片预览。
ImagePreview([ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg',]);ImagePreview 支持传入配置对象，并通过 startPosition 选项指定图片的初始位置（索引值）。
ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], startPosition: 1,});设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用close-icon-position 属性可以自定义图标位置。
ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], closeable: true,});通过 onClose 选项监听图片预览的关闭事件。
import { Toast } from 'vant';ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], onClose() { Toast('关闭'); },});通过 beforeClose 属性可以拦截关闭行为。
const instance = ImagePreview({ images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], beforeClose: () => false,});setTimeout(() => { // 调用实例上的 close 方法手动关闭图片预览 instance.close();}, 2000);如果需要在图片预览内嵌入组件或其他自定义内容，可以使用组件调用的方式，调用前需要通过 app.use 注册组件。
<van-image-preview v-model:show="state.show" :images="state.images" @change="onChange"> <template v-slot:index>第{{ index }}页</template></van-image-preview>import { reactive } from 'vue';export default { setup() { const state = reactive({ show: false, index: 0, }); const onChange = (index) => { state.index = index; }; return { state, images: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], onChange, }; },};通过函数调用 ImagePreview 时，支持传入以下选项：
| 参数名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| images | 需要预览的图片 URL 数组 | string[] | [] |
| startPosition | 图片预览起始位置索引 | number | string | 0 |
| swipeDuration | 动画时长，单位为 ms | number | string | 300 |
| showIndex | 是否显示页码 | boolean | true |
| showIndicators | 是否显示轮播指示器 | boolean | false |
| loop | 是否开启循环播放 | boolean | true |
| onClose | 关闭时的回调函数 | Function | - |
| onChange | 切换图片时的回调函数，回调参数为当前索引 | Function | - |
| onScale | 缩放图片时的回调函数，回调参数为当前索引和当前缩放值组成的对象 | Function | - |
| beforeClose | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| closeOnPopstate | 是否在页面回退时自动关闭 | boolean | true |
| className | 自定义类名 | string | Array | object | - |
| maxZoom | 手势缩放时，最大缩放比例 | number | string | 3 |
| minZoom | 手势缩放时，最小缩放比例 | number | string | 1/3 |
| closeable | 是否显示关闭图标 | boolean | false |
| closeIcon | 关闭图标名称或图片链接 | string | clear |
| closeIconPosition | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
transition v3.0.8 | 动画类名，等价于 transition 的 name 属性 | string | van-fade |
overlay-style v3.0.8 | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下 Props：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否展示图片预览 | boolean | false |
| images | 需要预览的图片 URL 数组 | string[] | [] |
| start-position | 图片预览起始位置索引 | number | string | 0 |
| swipe-duration | 动画时长，单位为 ms | number | string | 300 |
| show-index | 是否显示页码 | boolean | true |
| show-indicators | 是否显示轮播指示器 | boolean | false |
| loop | 是否开启循环播放 | boolean | true |
| before-close | 关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean | true |
| class-name | 自定义类名 | string | Array | object | - |
| max-zoom | 手势缩放时，最大缩放比例 | number | string | 3 |
| min-zoom | 手势缩放时，最小缩放比例 | number | string | 1/3 |
| closeable | 是否显示关闭图标 | boolean | false |
| close-icon | 关闭图标名称或图片链接 | string | clear |
| close-icon-position | 关闭图标位置，可选值为 top-leftbottom-left bottom-right | string | top-right |
transition v3.0.8 | 动画类名，等价于 transition 的 name 属性 | string | van-fade |
overlay-style v3.0.8 | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下事件：
| 事件 | 说明 | 回调参数 |
|---|---|---|
| close | 关闭时触发 | { index: 索引, url: 图片链接 } |
| closed | 关闭且且动画结束后触发 | - |
| change | 切换当前图片时触发 | index: 当前图片的索引 |
| scale | 缩放当前图片时触发 | { index: 当前图片的索引, scale: 当前缩放的值 } |
通过组件调用 ImagePreview 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
swipeTo 2.9.0 | 切换到指定位置 | index: number, options: Options | - |
通过组件调用 ImagePreview 时，支持以下插槽：
| 名称 | 说明 | 参数 |
|---|---|---|
| index | 自定义页码内容 | { index: 当前图片的索引 } |
| cover | 自定义覆盖在图片预览上方的内容 | - |
| 参数名 | 说明 | 类型 |
|---|---|---|
| url | 当前图片 URL | string |
| index | 当前图片的索引值 | number |
| 参数名 | 说明 | 类型 |
|---|---|---|
| index | 当前图片的索引值 | number |
| scale | 当前图片的缩放值 | number |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-image-preview-index-text-color | var(--van-white) | - |
| --van-image-preview-index-font-size | var(--van-font-size-md) | - |
| --van-image-preview-index-line-height | var(--van-line-height-md) | - |
| --van-image-preview-index-text-shadow | 0 1px 1px var(--van-gray-8) | - |
| --van-image-preview-overlay-background-color | rgba(0, 0, 0, 0.9) | - |
| --van-image-preview-close-icon-size | 22px | - |
| --van-image-preview-close-icon-color | var(--van-gray-5) | - |
| --van-image-preview-close-icon-active-color | var(--van-gray-6) | - |
| --van-image-preview-close-icon-margin | var(--van-padding-md) | - |
| --van-image-preview-close-icon-z-index | 1 | - |
参见桌面端适配。
请注意 ImagePreview 是一个函数，ImagePreview.Component 才是 ImagePreview 对应的组件。JSX 调用图片预览的正确姿势如下：
export default { setup() { const show = ref(false); return () => <ImagePreview.Component v-model={[show, 'show']} />; },};当页面需要加载大量内容时，使用懒加载可以实现延迟加载页面可视区域外的内容，从而使页面加载更流畅。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
Lazyload 是 Vue 指令，使用前需要对指令进行注册。
import { createApp } from 'vue';import { Lazyload } from 'vant';const app = createApp();app.use(Lazyload);// 注册时可以配置额外的选项app.use(Lazyload, { lazyComponent: true,});将 v-lazy 指令的值设置为你需要懒加载的图片。
<img v-for="img in imageList" v-lazy="img" />export default { setup() { return { imageList: [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ], }; },};和图片懒加载不同，背景图懒加载需要使用 v-lazy:background-image，值设置为背景图片的地址，需要注意的是必须声明容器高度。
<div v-for="img in imageList" v-lazy:background-image="img" />将需要懒加载的组件放在 lazy-component 标签中，即可实现组件懒加载。
// 注册时设置`lazyComponent`选项app.use(Lazyload, { lazyComponent: true,});<lazy-component> <img v-for="img in imageList" v-lazy="img" /></lazy-component>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| loading | 加载时的图片 | string | - |
| error | 错误时的图片 | string | - |
| preload | 预加载高度的比例 | string | - |
| attempt | 尝试次数 | number | 3 |
| listenEvents | 监听的事件 | string[] | scroll等 |
| adapter | 适配器 | object | - |
| filter | 图片 URL 过滤 | object | - |
| lazyComponent | 是否能懒加载模块 | boolean | false |
更多内容请参照：vue-lazyload 官方文档
由于 Lazyload 组件在注册时可以传入一些配置项，所以我们不会自动注册 Lazyload 组件，需要手动进行注册：
const app = Vue.createApp();app.use(vant.Lazyload, { lazyComponent: true,});用于循环播放展示一组消息通知。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NoticeBar } from 'vant';const app = createApp();app.use(NoticeBar);通过 text 属性设置通知栏的内容，通过 left-icon 属性设置通知栏左侧的图标。
<van-notice-bar left-icon="volume-o" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>通知栏的内容长度溢出时会自动开启滚动播放，通过 scrollable 属性可以控制该行为。
<!-- 文字较短时，通过设置 scrollable 属性开启滚动播放 --><van-notice-bar scrollable text="技术是开发它的人的共同灵魂。" /><!-- 文字较长时，通过禁用 scrollable 属性关闭滚动播放 --><van-notice-bar :scrollable="false" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>文字较长时，可以通过设置 wrapable 属性来开启多行展示。
<van-notice-bar wrapable :scrollable="false" text="在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。"/>通知栏支持 closeable 和 link 两种模式。
<!-- closeable 模式，在右侧显示关闭按钮 --><van-notice-bar mode="closeable">技术是开发它的人的共同灵魂。</van-notice-bar><!-- link 模式，在右侧显示链接箭头 --><van-notice-bar mode="link">技术是开发它的人的共同灵魂。</van-notice-bar>通过 color 属性设置文本颜色，通过 background 属性设置背景色。
<van-notice-bar color="#1989fa" background="#ecf9ff" left-icon="info-o"> 技术是开发它的人的共同灵魂。</van-notice-bar>搭配 NoticeBar 和 Swipe 组件可以实现垂直滚动的效果。
<van-notice-bar left-icon="volume-o" :scrollable="false"> <van-swipe vertical class="notice-swipe" :autoplay="3000" :show-indicators="false" > <van-swipe-item>内容 1</van-swipe-item> <van-swipe-item>内容 2</van-swipe-item> <van-swipe-item>内容 3</van-swipe-item> </van-swipe></van-notice-bar><style> .notice-swipe { height: 40px; line-height: 40px; }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| mode | 通知栏模式，可选值为 closeable link | string | '' |
| text | 通知文本内容 | string | '' |
| color | 通知文本颜色 | string | #f60 |
| background | 滚动条背景 | string | #fff7cc |
| left-icon | 左侧图标名称或图片链接 | string | - |
| delay | 动画延迟时间 (s) | number | string | 1 |
| speed | 滚动速率 (px/s) | number | string | 60 |
| scrollable | 是否开启滚动播放，内容长度溢出时默认开启 | boolean | - |
| wrapable | 是否开启文本换行，只在禁用滚动时生效 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击通知栏时触发 | event: MouseEvent |
| close | 关闭通知栏时触发 | event: MouseEvent |
| replay | 每当滚动栏重新开始滚动时触发 | - |
通过 ref 可以获取到 NoticeBar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
reset v3.1.1 | 重置通知栏到初始状态 | - | - |
| 名称 | 内容 |
|---|---|
| default | 通知文本内容 |
| left-icon | 自定义左侧图标 |
| right-icon | 自定义右侧图标 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-notice-bar-height | 40px | - |
| --van-notice-bar-padding | 0 var(--van-padding-md) | - |
| --van-notice-bar-wrapable-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-notice-bar-text-color | var(--van-orange-dark) | - |
| --van-notice-bar-font-size | var(--van-font-size-md) | - |
| --van-notice-bar-line-height | 24px | - |
| --van-notice-bar-background-color | var(--van-orange-light) | - |
| --van-notice-bar-icon-size | 16px | - |
| --van-notice-bar-icon-min-width | 24px | - |
弹出式的气泡菜单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Popover } from 'vant';const app = createApp();app.use(Popover);当 Popover 弹出时，会基于 reference 插槽的内容进行定位。
<van-popover v-model:show="showPopover" :actions="actions" @select="onSelect"> <template #reference> <van-button type="primary">浅色风格</van-button> </template></van-popover>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const showPopover = ref(false); // 通过 actions 属性来定义菜单选项 const actions = [ { text: '选项一' }, { text: '选项二' }, { text: '选项三' }, ]; const onSelect = (action) => Toast(action.text); return { actions, onSelect, showPopover, }; },};Popover 支持浅色和深色两种风格，默认为浅色风格，将 theme 属性设置为 dark 可切换为深色风格。
<van-popover v-model:show="showPopover" theme="dark" :actions="actions"> <template #reference> <van-button type="primary">深色风格</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一' }, { text: '选项二' }, { text: '选项三' }, ]; return { actions, showPopover, }; },};通过 placement 属性来控制气泡的弹出位置。
<van-popover placement="top" />placement 支持以下值：
top # 顶部中间位置top-start # 顶部左侧位置top-end # 顶部右侧位置left # 左侧中间位置left-start # 左侧上方位置left-end # 左侧下方位置right # 右侧中间位置right-start # 右侧上方位置right-end # 右侧下方位置bottom # 底部中间位置bottom-start # 底部左侧位置bottom-end # 底部右侧位置在 actions 数组中，可以通过 icon 字段来定义选项的图标，支持传入图标名称或图片链接。
<van-popover v-model:show="showPopover" :actions="actions"> <template #reference> <van-button type="primary">展示图标</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一', icon: 'add-o' }, { text: '选项二', icon: 'music-o' }, { text: '选项三', icon: 'more-o' }, ]; return { actions, showPopover, }; },};在 actions 数组中，可以通过 disabled 字段来禁用某个选项。
<van-popover v-model:show="showPopover" :actions="actions"> <template #reference> <van-button type="primary">禁用选项</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); const actions = [ { text: '选项一', disabled: true }, { text: '选项二', disabled: true }, { text: '选项三' }, ]; return { actions, showPopover, }; },};通过默认插槽，可以在 Popover 内部放置任意内容。
<van-popover v-model:show="showPopover"> <van-grid square clickable :border="false" column-num="3" style="width: 240px;" > <van-grid-item v-for="i in 6" :key="i" text="选项" icon="photo-o" @click="showPopover = false" /> </van-grid> <template #reference> <van-button type="primary">自定义内容</van-button> </template></van-popover>import { ref } from 'vue';export default { setup() { const showPopover = ref(false); return { showPopover }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否展示气泡弹出层 | boolean | false |
| actions | 选项列表 | Action[] | [] |
| placement | 弹出位置 | string | bottom |
| theme | 主题风格，可选值为 dark | string | light |
| trigger | 触发方式，可选值为 manual | click | |
| duration | 动画时长，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| offset | 出现位置的偏移量 | [number, number] | [0, 8] |
| overlay | 是否显示遮罩层 | boolean | false |
overlay-class v3.0.10 | 自定义遮罩层类名 | string | Array | object | - |
overlay-style v3.0.10 | 自定义遮罩层样式 | object | - |
| close-on-click-action | 是否在点击选项后关闭 | boolean | true |
| close-on-click-outside | 是否在点击外部元素后关闭菜单 | boolean | true |
close-on-click-overlay v3.0.10 | 是否在点击遮罩层后关闭菜单 | boolean | true |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | body |
icon-prefix v3.0.17 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
actions 属性是一个由对象构成的数组，数组中的每个对象配置一列，对象可以包含以下值：
| 键名 | 说明 | 类型 |
|---|---|---|
| text | 选项文字 | string |
| icon | 文字左侧的图标，支持传入图标名称或图片链接 | string |
| color | 选项文字颜色 | string |
| disabled | 是否为禁用状态 | boolean |
| className | 为对应选项添加额外的类名 | string | Array | object |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击选项时触发 | action: Action, index: number |
| open | 打开菜单时触发 | - |
| close | 关闭菜单时触发 | - |
| opened | 打开菜单且动画结束后触发 | - |
| closed | 关闭菜单且动画结束后触发 | - |
| click-overlay | 点击遮罩层时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义菜单内容 |
| reference | 触发 Popover 显示的元素内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-popover-arrow-size | 6px | - |
| --van-popover-border-radius | var(--van-border-radius-lg) | - |
| --van-popover-action-width | 128px | - |
| --van-popover-action-height | 44px | - |
| --van-popover-action-font-size | var(--van-font-size-md) | - |
| --van-popover-action-line-height | var(--van-line-height-md) | - |
| --van-popover-action-icon-size | 20px | - |
| --van-popover-light-text-color | var(--van-text-color) | - |
| --van-popover-light-background-color | var(--van-white) | - |
| --van-popover-light-action-disabled-text-color | var(--van-gray-5) | - |
| --van-popover-dark-text-color | var(--van-white) | - |
| --van-popover-dark-background-color | #4a4a4a | - |
| --van-popover-dark-action-disabled-text-color | var(--van-gray-6) | - |
这种情况通常是由于项目中引入了 fastclick 库导致的。建议移除 fastclick，或者配置 fastclick 的 ignore 规则。
用于展示操作的当前进度。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Progress } from 'vant';const app = createApp();app.use(Progress);进度条默认为蓝色，使用 percentage 属性来设置当前进度。
<van-progress :percentage="50" />通过 stroke-width 可以设置进度条的粗细。
<van-progress :percentage="50" stroke-width="8" />设置 inactive 属性后进度条将置灰。
<van-progress inactive :percentage="50" />可以使用 pivot-text 属性自定义文字，color 属性自定义进度条颜色。
<van-progress pivot-text="橙色" color="#f2826a" :percentage="25" /><van-progress pivot-text="红色" color="#ee0a24" :percentage="50" /><van-progress :percentage="75" pivot-text="紫色" pivot-color="#7232dd" color="linear-gradient(to right, #be99ff, #7232dd)"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| percentage | 进度百分比 | number | string | 0 |
| stroke-width | 进度条粗细，默认单位为px | number | string | 4px |
| color | 进度条颜色 | string | #1989fa |
| track-color | 轨道颜色 | string | #e5e5e5 |
| pivot-text | 进度文字内容 | string | 百分比 |
| pivot-color | 进度文字背景色 | string | 同进度条颜色 |
| text-color | 进度文字颜色 | string | white |
| inactive | 是否置灰 | boolean | false |
| show-pivot | 是否显示进度文字 | boolean | true |
通过 ref 可以获取到 Progress 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| resize | 外层元素大小变化后，可以调用此方法来触发重绘 | - | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-progress-height | 4px | - |
| --van-progress-color | var(--van-primary-color) | - |
| --van-progress-background-color | var(--van-gray-3) | - |
| --van-progress-pivot-padding | 0 5px | - |
| --van-progress-pivot-text-color | var(--van-white) | - |
| --van-progress-pivot-font-size | var(--van-font-size-xs) | - |
| --van-progress-pivot-line-height | 1.6 | - |
| --van-progress-pivot-background-color | var(--van-primary-color) | - |
Progress 组件在挂载时，会获取自身的宽度，并计算出进度条的样式。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法展示正确的进度。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-progress v-show="show" /><!-- After --><van-progress v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-progress v-show="show" ref="progress" />this.$refs.progress.resize();用于在内容加载过程中展示一组占位图形。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Skeleton } from 'vant';const app = createApp();app.use(Skeleton);通过 title 属性显示标题占位图，通过 row 属性配置占位段落行数。
<van-skeleton title :row="3" />通过 avatar 属性显示头像占位图。
<van-skeleton title avatar :row="3" />将 loading 属性设置成 false 表示内容加载完成，此时会隐藏占位图，并显示 Skeleton 的子组件。
<van-skeleton title avatar :row="3" :loading="loading"> <div>实际内容</div></van-skeleton>import { ref, onMounted } from 'vue';export default { setup() { const loading = ref(true); onMounted(() => { loading.value = false; }); return { loading, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| row | 段落占位图行数 | number | string | 0 |
| row-width | 段落占位图宽度，可传数组来设置每一行的宽度 | number | string | (number | string)[] | 100% |
| title | 是否显示标题占位图 | boolean | false |
| avatar | 是否显示头像占位图 | boolean | false |
| loading | 是否显示骨架屏，传 false 时会展示子组件内容 | boolean | true |
| animate | 是否开启动画 | boolean | true |
| round | 是否将标题和段落显示为圆角风格 | boolean | false |
| title-width | 标题占位图宽度 | number | string | 40% |
| avatar-size | 头像占位图大小 | number | string | 32px |
| avatar-shape | 头像占位图形状，可选值为 square | string | round |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-skeleton-row-height | 16px | - |
| --van-skeleton-row-background-color | var(--van-active-color) | - |
| --van-skeleton-row-margin-top | var(--van-padding-sm) | - |
| --van-skeleton-title-width | 40% | - |
| --van-skeleton-avatar-size | 32px | - |
| --van-skeleton-avatar-background-color | var(--van-active-color) | - |
| --van-skeleton-animation-duration | 1.2s | - |
用于展示操作流程的各个环节，让用户了解当前的操作在整体流程中的位置。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Step, Steps } from 'vant';const app = createApp();app.use(Step);app.use(Steps);active 属性表示当前步骤的索引，从 0 起计。
<van-steps :active="active"> <van-step>买家下单</van-step> <van-step>商家接单</van-step> <van-step>买家提货</van-step> <van-step>交易完成</van-step></van-steps>import { ref } from 'vue';export default { setup() { const active = ref(1); return { active }; },};可以通过 active-icon 和 active-color 属性设置激活状态下的图标和颜色。
<van-steps :active="active" active-icon="success" active-color="#38f"> <van-step>买家下单</van-step> <van-step>商家接单</van-step> <van-step>买家提货</van-step> <van-step>交易完成</van-step></van-steps>可以通过设置 direction 属性来改变步骤条的显示方向。
<van-steps direction="vertical" :active="0"> <van-step> <h3>【城市】物流状态1</h3> <p>2016-07-12 12:40</p> </van-step> <van-step> <h3>【城市】物流状态2</h3> <p>2016-07-11 10:00</p> </van-step> <van-step> <h3>快件已发货</h3> <p>2016-07-10 09:30</p> </van-step></van-steps>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| active | 当前步骤对应的索引值 | number | string | 0 |
| direction | 步骤条方向，可选值为 vertical | string | horizontal |
| active-icon | 当前步骤对应的底部图标，可选值见 Icon 组件 | string | checked |
| inactive-icon | 非当前步骤对应的底部图标，可选值见 Icon 组件 | string | - |
finish-icon v3.0.7 | 已完成步骤对应的底部图标，优先级高于 inactive-icon，可选值见 Icon 组件 | string | - |
| active-color | 当前步骤和已完成步骤的颜色 | string | #07c160 |
| inactive-color | 未激活步骤的颜色 | string | #969799 |
icon-prefix v3.0.15 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| 名称 | 说明 |
|---|---|
| active-icon | 自定义激活状态图标 |
| inactive-icon | 自定义未激活状态图标 |
finish-icon v3.0.7 | 自定义已完成步骤对应的底部图标，优先级高于 inactive-icon |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-step | 点击步骤的标题或图标时触发 | index: number |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-step-text-color | var(--van-gray-6) | - |
| --van-step-active-color | var(--van-success-color) | - |
| --van-step-process-text-color | var(--van-text-color) | - |
| --van-step-font-size | var(--van-font-size-md) | - |
| --van-step-line-color | var(--van-border-color) | - |
| --van-step-finish-line-color | var(--van-success-color) | - |
| --van-step-finish-text-color | var(--van-text-color) | - |
| --van-step-icon-size | 12px | - |
| --van-step-circle-size | 5px | - |
| --van-step-circle-color | var(--van-gray-6) | - |
| --van-step-horizontal-title-font-size | var(--van-font-size-sm) | - |
| --van-steps-background-color | var(--van-white) | - |
Sticky 组件与 CSS 中 position: sticky 属性实现的效果一致，当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在屏幕顶部。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Sticky } from 'vant';const app = createApp();app.use(Sticky);将内容包裹在 Sticky 组件内即可。
<van-sticky> <van-button type="primary">基础用法</van-button></van-sticky>通过 offset-top 属性可以设置组件在吸顶时与顶部的距离。
<van-sticky :offset-top="50"> <van-button type="primary">吸顶距离</van-button></van-sticky>通过 container 属性可以指定组件的容器，页面滚动时，组件会始终保持在容器范围内，当组件即将超出容器底部时，会固定在容器的底部。
<div ref="container" style="height: 150px;"> <van-sticky :container="container"> <van-button type="warning">指定容器</van-button> </van-sticky></div>export default { setup() { const container = ref(null); return { container }; },};将 position 设置为 bottom 可以让组件吸附在底部。通过 offset-bottom 属性可以设置组件在吸底时与底部的距离。
<van-sticky :offset-bottom="50" position="bottom"> <van-button type="primary">吸底距离</van-button></van-sticky>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
position v3.0.6 | 吸附位置，可选值为 bottom | string | top |
| offset-top | 吸顶时与顶部的距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
offset-bottom v3.0.6 | 吸底时与底部的距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
| z-index | 吸顶时的 z-index | number | string | 99 |
| container | 容器对应的 HTML 节点 | Element | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
change v3.0.10 | 当吸顶状态改变时触发 | isFixed: boolean |
| scroll | 滚动时触发 | { scrollTop: number, isFixed: boolean } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-sticky-z-index | 99 | - |
用于循环播放一组图片或内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。import { createApp } from 'vue';
import { Swipe, SwipeItem } from 'vant';const app = createApp();app.use(Swipe);app.use(SwipeItem);每个 SwipeItem 代表一张轮播卡片，可以通过 autoplay 属性设置自动轮播的间隔。
<van-swipe class="my-swipe" :autoplay="3000" indicator-color="white"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe><style> .my-swipe .van-swipe-item { color: #fff; font-size: 20px; line-height: 150px; text-align: center; background-color: #39a9ed; }</style>当 Swipe 中含有图片时，可以通过 lazy-render 属性来开启懒加载模式。在懒加载模式下，只会渲染当前页和下一页。
<van-swipe :autoplay="3000" lazy-render> <van-swipe-item v-for="image in images" :key="image"> <img :src="image" /> </van-swipe-item></van-swipe>export default { setup() { const images = [ 'https://img.yzcdn.cn/vant/apple-1.jpg', 'https://img.yzcdn.cn/vant/apple-2.jpg', ]; return { images }; },};在每一页轮播结束后，会触发 change 事件。
<van-swipe @change="onChange"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>import { Toast } from 'vant';export default { setup() { const onChange = (index) => Toast('当前 Swipe 索引：' + index); return { onChange }; },};设置 vertical 属性后滑块会纵向排列，此时需要指定滑块容器的高度。
<van-swipe style="height: 200px;" vertical> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>滑块默认宽度为 100%，可以通过 width 属性设置单个滑块的宽度。纵向滚动模式下，可以通过 height 属性设置单个滑块的高度。
<van-swipe :loop="false" :width="300"> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item></van-swipe>目前不支持在循环滚动模式下自定义滑块大小，因此需要将 loop 设置为 false。
通过 indicator 插槽可以自定义指示器的样式。
<van-swipe> <van-swipe-item>1</van-swipe-item> <van-swipe-item>2</van-swipe-item> <van-swipe-item>3</van-swipe-item> <van-swipe-item>4</van-swipe-item> <template #indicator="{ active }"> <div class="custom-indicator">{{ active + 1 }}/4</div> </template></van-swipe><style> .custom-indicator { position: absolute; right: 5px; bottom: 5px; padding: 2px 5px; font-size: 12px; background: rgba(0, 0, 0, 0.1); }</style>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| autoplay | 自动轮播间隔，单位为 ms | number | string | - |
| duration | 动画时长，单位为 ms | number | string | 500 |
| initial-swipe | 初始位置索引值 | number | string | 0 |
| width | 滑块宽度，单位为 px | number | string | auto |
| height | 滑块高度，单位为 px | number | string | auto |
| loop | 是否开启循环播放 | boolean | true |
| show-indicators | 是否显示指示器 | boolean | true |
| vertical | 是否为纵向滚动 | boolean | false |
| touchable | 是否可以通过手势滑动 | boolean | true |
| stop-propagation | 是否阻止滑动事件冒泡 | boolean | true |
| lazy-render | 是否延迟渲染未展示的轮播 | boolean | false |
| indicator-color | 指示器颜色 | string | #1989fa |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 每一页轮播结束后触发 | index, 当前页的索引 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
通过 ref 可以获取到 Swipe 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| prev | 切换到上一轮播 | - | - |
| next | 切换到下一轮播 | - | - |
| swipeTo | 切换到指定位置 | index: number, options: SwipeToOptions | - |
| resize | 外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘 | - | - |
通过 SwipeInstance 获取 Swipe 实例的类型定义。
import { ref } from 'vue';import type { SwipeInstance } from 'vant';const swipeRef = ref<SwipeInstance>();swipeRef.value?.next();| 名称 | 说明 | 类型 |
|---|---|---|
| immediate | 是否跳过动画 | boolean |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 轮播内容 | - |
indicator v3.0.16 | 自定义指示器 | { active: number } |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-swipe-indicator-size | 6px | - |
| --van-swipe-indicator-margin | var(--van-padding-sm) | - |
| --van-swipe-indicator-active-opacity | 1 | - |
| --van-swipe-indicator-inactive-opacity | 0.3 | - |
| --van-swipe-indicator-active-background-color | var(--van-primary-color) | - |
| --van-swipe-indicator-inactive-background-color | var(--van-border-color) | - |
这种情况通常是由于项目中引入了 fastclick 库导致的。fastclick 的原理是通过 Touch 事件模拟出 click 事件，而 Swipe 内部默认会阻止 touchmove 事件冒泡，干扰了 fastclick 的判断，导致出现这个问题。
将 Swipe 组件的 stop-propagation 属性设置为 false 即可避免该问题。
参见桌面端适配。
Vant 中的 Swipe 组件是比较轻量的，因此功能也比较基础。如果需要更复杂的轮播效果，推荐使用社区里一些优质的轮播库，比如 vue-awesome-swiper。
Swipe 组件在挂载时，会获取自身的宽度，并计算出轮播图的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法正确计算位置。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-swipe v-show="show" /><!-- After --><van-swipe v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-swipe v-show="show" ref="swipe" />this.$refs.swipe.resize();用于标记关键词和概括主要内容。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tag } from 'vant';const app = createApp();app.use(Tag);通过 type 属性控制标签颜色。
<van-tag type="primary">标签</van-tag><van-tag type="success">标签</van-tag><van-tag type="danger">标签</van-tag><van-tag type="warning">标签</van-tag>设置 plain 属性设置为空心样式。
<van-tag plain type="primary">标签</van-tag>通过 round 设置为圆角样式。
<van-tag round type="primary">标签</van-tag>通过 mark 设置为标记样式(半圆角)。
<van-tag mark type="primary">标签</van-tag>添加 closeable 属性表示标签是可关闭的，关闭标签时会触发 close 事件，在 close 事件中可以执行隐藏标签的逻辑。
<van-tag :show="show" closeable size="medium" type="primary" @close="close"> 标签</van-tag>import { ref } from 'vue';export default { setup() { const show = ref(true); const close = () => { show.value = false; }; return { show, close, }; },};通过 size 属性调整标签大小。
<van-tag type="primary">标签</van-tag><van-tag type="primary" size="medium">标签</van-tag><van-tag type="primary" size="large">标签</van-tag>通过 color 和 text-color 属性设置标签颜色。
<van-tag color="#7232dd">标签</van-tag><van-tag color="#ffe1e1" text-color="#ad0000">标签</van-tag><van-tag color="#7232dd" plain>标签</van-tag>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 类型，可选值为 primary success danger warning | string | default |
| size | 大小, 可选值为 large medium | string | - |
| color | 标签颜色 | string | - |
| show | 是否展示标签 | boolean | true |
| plain | 是否为空心样式 | boolean | false |
| round | 是否为圆角样式 | boolean | false |
| mark | 是否为标记样式 | boolean | false |
| text-color | 文本颜色，优先级高于 color 属性 | string | white |
| closeable | 是否为可关闭标签 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 标签显示内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| close | 关闭标签时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tag-padding | 0 var(--van-padding-base) | - |
| --van-tag-text-color | var(--van-white) | - |
| --van-tag-font-size | var(--van-font-size-sm) | - |
| --van-tag-border-radius | 2px | - |
| --van-tag-line-height | 16px | - |
| --van-tag-medium-padding | 2px 6px | - |
| --van-tag-large-padding | var(--van-padding-base) var(--van-padding-xs) | - |
| --van-tag-large-border-radius | var(--van-border-radius-md) | - |
| --van-tag-large-font-size | var(--van-font-size-md) | - |
| --van-tag-round-border-radius | var(--van-border-radius-max) | - |
| --van-tag-danger-color | var(--van-danger-color) | - |
| --van-tag-primary-color | var(--van-primary-color) | - |
| --van-tag-success-color | var(--van-success-color) | - |
| --van-tag-warning-color | var(--van-warning-color) | - |
| --van-tag-default-color | var(--van-gray-6) | - |
| --van-tag-plain-background-color | var(--van-white) | - |
用于为页面相关操作提供便捷交互。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ActionBar, ActionBarIcon, ActionBarButton } from 'vant';const app = createApp();app.use(ActionBar);app.use(ActionBarIcon);app.use(ActionBarButton);<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" @click="onClickIcon" /> <van-action-bar-icon icon="cart-o" text="购物车" @click="onClickIcon" /> <van-action-bar-icon icon="shop-o" text="店铺" @click="onClickIcon" /> <van-action-bar-button type="danger" text="立即购买" @click="onClickButton" /></van-action-bar>import { Toast } from 'vant';export default { setup() { const onClickIcon = () => Toast('点击图标'); const onClickButton = () => Toast('点击按钮'); return { onClickIcon, onClickButton, }; },};在 ActionBarIcon 组件上设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" dot /> <van-action-bar-icon icon="cart-o" text="购物车" badge="5" /> <van-action-bar-icon icon="shop-o" text="店铺" badge="12" /> <van-action-bar-button type="warning" text="加入购物车" /> <van-action-bar-button type="danger" text="立即购买" /></van-action-bar>通过 ActionBarIcon 的 color 属性可以自定义图标的颜色。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" color="#ee0a24" /> <van-action-bar-icon icon="cart-o" text="购物车" /> <van-action-bar-icon icon="star" text="已收藏" color="#ff5000" /> <van-action-bar-button type="warning" text="加入购物车" /> <van-action-bar-button type="danger" text="立即购买" /></van-action-bar>通过 ActionBarButton 的 color 属性可以自定义按钮的颜色，支持传入 linear-gradient 渐变色。
<van-action-bar> <van-action-bar-icon icon="chat-o" text="客服" /> <van-action-bar-icon icon="shop-o" text="店铺" /> <van-action-bar-button color="#be99ff" type="warning" text="加入购物车" /> <van-action-bar-button color="#7232dd" type="danger" text="立即购买" /></van-action-bar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 按钮文字 | string | - |
| icon | 图标 | string | - |
| color | 图标颜色 | string | #323233 |
| icon-class | 图标额外类名 | string | Array | object | - |
icon-prefix v3.0.17 | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 按钮文字 | string | - |
| type | 按钮类型，可选值为 primary info warning danger | string | default |
| color | 按钮颜色，支持传入 linear-gradient 渐变色 | string | - |
| icon | 左侧图标名称或图片链接 | string | - |
| disabled | 是否禁用按钮 | boolean | false |
| loading | 是否显示为加载状态 | boolean | false |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 名称 | 说明 |
|---|---|
| default | 文本内容 |
| icon | 自定义图标 |
| 名称 | 说明 |
|---|---|
| default | 按钮显示内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-action-bar-background-color | var(--van-white) | - |
| --van-action-bar-height | 50px | - |
| --van-action-bar-icon-width | 48px | - |
| --van-action-bar-icon-height | 100% | - |
| --van-action-bar-icon-color | var(--van-text-color) | - |
| --van-action-bar-icon-size | 18px | - |
| --van-action-bar-icon-font-size | var(--van-font-size-xs) | - |
| --van-action-bar-icon-active-color | var(--van-active-color) | - |
| --van-action-bar-icon-text-color | var(--van-gray-7) | - |
| --van-action-bar-icon-background-color | var(--van-white) | - |
| --van-action-bar-button-height | 40px | - |
| --van-action-bar-button-warning-color | var(--van-gradient-orange) | - |
| --van-action-bar-button-danger-color | var(--van-gradient-red) | - |
宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Grid, GridItem } from 'vant';const app = createApp();app.use(Grid);app.use(GridItem);通过 icon 属性设置格子内的图标，text 属性设置文字内容。
<van-grid> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /></van-grid>默认一行展示四个格子，可以通过 column-num 自定义列数。
<van-grid :column-num="3"> <van-grid-item v-for="value in 6" :key="value" icon="photo-o" text="文字" /></van-grid>通过插槽可以自定义格子展示的内容。
<van-grid :border="false" :column-num="3"> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-1.jpg" rel="external nofollow" /> </van-grid-item> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-2.jpg" rel="external nofollow" /> </van-grid-item> <van-grid-item> <van-image src="https://img.yzcdn.cn/vant/apple-3.jpg" rel="external nofollow" /> </van-grid-item></van-grid>设置 square 属性后，格子的高度会和宽度保持一致。
<van-grid square> <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" /></van-grid>通过 gutter 属性设置格子之间的距离。
<van-grid :gutter="10"> <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" /></van-grid>将 direction 属性设置为 horizontal，可以让宫格的内容呈横向排列。
<van-grid direction="horizontal" :column-num="3"> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /> <van-grid-item icon="photo-o" text="文字" /></van-grid>通过 to 属性设置 vue-router 跳转链接，通过 url 属性设置 URL 跳转链接。
<van-grid clickable :column-num="2"> <van-grid-item icon="home-o" text="路由跳转" to="/" /> <van-grid-item icon="search" text="URL 跳转" url="/vant/mobile.html" /></van-grid>设置 dot 属性后，会在图标右上角展示一个小红点。设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-grid :column-num="2"> <van-grid-item icon="home-o" text="文字" dot /> <van-grid-item icon="search" text="文字" badge="99+" /></van-grid>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| column-num | 列数 | number | string | 4 |
| icon-size | 图标大小，默认单位为px | number | string | 28px |
| gutter | 格子之间的间距，默认单位为px | number | string | 0 |
| border | 是否显示边框 | boolean | true |
| center | 是否将格子内容居中显示 | boolean | true |
| square | 是否将格子固定为正方形 | boolean | false |
| clickable | 是否开启格子点击反馈 | boolean | false |
| direction | 格子内容排列的方向，可选值为 horizontal | string | vertical |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| text | 文字 | string | - |
| icon | 图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| icon-color | 图标颜色，等同于 Icon 组件的 color 属性 | string | - |
reverse v3.1.0 | 是否调换图标和文本的位置 | boolean | false |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击格子时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| default | 自定义宫格的所有内容 |
| icon | 自定义图标 |
| text | 自定义文字 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-grid-item-content-padding | var(--van-padding-md) var(--van-padding-xs) | - |
| --van-grid-item-content-background-color | var(--van-white) | - |
| --van-grid-item-content-active-color | var(--van-active-color) | - |
| --van-grid-item-icon-size | 28px | - |
| --van-grid-item-text-color | var(--van-gray-7) | - |
| --van-grid-item-text-font-size | var(--van-font-size-sm) | - |
用于列表的索引分类显示和快速定位。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { IndexBar, IndexAnchor } from 'vant';const app = createApp();app.use(IndexBar);app.use(IndexAnchor);点击索引栏时，会自动跳转到对应的 IndexAnchor 锚点位置。
<van-index-bar> <van-index-anchor index="A" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-index-anchor index="B" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> ...</van-index-bar>可以通过 index-list 属性自定义展示的索引字符列表。
<van-index-bar :index-list="indexList"> <van-index-anchor index="1">标题1</van-index-anchor> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> <van-index-anchor index="2">标题2</van-index-anchor> <van-cell title="文本" /> <van-cell title="文本" /> <van-cell title="文本" /> ...</van-index-bar>export default { setup() { return { indexList: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| index-list | 索引字符列表 | string[] | number[] | A-Z |
| z-index | z-index 层级 | number | string | 1 |
| sticky | 是否开启锚点自动吸顶 | boolean | true |
| sticky-offset-top | 锚点自动吸顶时与顶部的距离 | number | 0 |
| highlight-color | 索引字符高亮颜色 | string | #ee0a24 |
teleport v3.0.19 | 指定索引栏挂载的节点 | string | Element | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| index | 索引字符 | number | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| select | 点击索引栏的字符时触发 | index: number | string |
| change | 当前高亮的索引字符变化时触发 | index: number | string |
通过 ref 可以获取到 IndexBar 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| scrollTo | 滚动到指定锚点 | index: number | string | - |
| 名称 | 说明 |
|---|---|
| default | 锚点位置显示内容，默认为索引字符 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-index-bar-sidebar-z-index | 2 | - |
| --van-index-bar-index-font-size | var(--van-font-size-xs) | - |
| --van-index-bar-index-line-height | var(--van-line-height-xs) | - |
| --van-index-bar-index-active-color | var(--van-danger-color) | - |
| --van-index-anchor-z-index | 1 | - |
| --van-index-anchor-padding | 0 var(--van-padding-md) | - |
| --van-index-anchor-text-color | var(--van-text-color) | - |
| --van-index-anchor-font-weight | var(--van-font-weight-bold) | - |
| --van-index-anchor-font-size | var(--van-font-size-md) | - |
| --van-index-anchor-line-height | 32px | - |
| --van-index-anchor-background-color | transparent | - |
| --van-index-anchor-sticky-text-color | var(--van-danger-color) | - |
| --van-index-anchor-sticky-background-color | var(--van-white) | - |
为页面提供导航功能，常用于页面顶部。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { NavBar } from 'vant';const app = createApp();app.use(NavBar);<van-nav-bar title="标题" left-text="返回" right-text="按钮" left-arrow @click-left="onClickLeft" @click-right="onClickRight"/>import { Toast } from 'vant';export default { setup() { const onClickLeft = () => Toast('返回'); const onClickRight = () => Toast('按钮'); return { onClickLeft, onClickRight, }; },};通过插槽自定义导航栏两侧的内容。
<van-nav-bar title="标题" left-text="返回" left-arrow> <template #right> <van-icon name="search" size="18" /> </template></van-nav-bar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | '' |
| left-text | 左侧文案 | string | '' |
| right-text | 右侧文案 | string | '' |
| left-arrow | 是否显示左侧箭头 | boolean | false |
| border | 是否显示下边框 | boolean | true |
| fixed | 是否固定在顶部 | boolean | false |
| placeholder | 固定在顶部时，是否在标签位置生成一个等高的占位元素 | boolean | false |
| z-index | 导航栏 z-index | number | string | 1 |
| safe-area-inset-top | 是否开启顶部安全区适配 | boolean | false |
| 名称 | 说明 |
|---|---|
| title | 自定义标题 |
| left | 自定义左侧区域内容 |
| right | 自定义右侧区域内容 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-left | 点击左侧按钮时触发 | event: MouseEvent |
| click-right | 点击右侧按钮时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-nav-bar-height | 46px | - |
| --van-nav-bar-background-color | var(--van-white) | - |
| --van-nav-bar-arrow-size | 16px | - |
| --van-nav-bar-icon-color | var(--van-primary-color) | - |
| --van-nav-bar-text-color | var(--van-primary-color) | - |
| --van-nav-bar-title-font-size | var(--van-font-size-lg) | - |
| --van-nav-bar-title-text-color | var(--van-text-color) | - |
| --van-nav-bar-z-index | 1 | - |
数据量过多时，采用分页的形式将数据分隔，每次只加载一个页面。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Pagination } from 'vant';const app = createApp();app.use(Pagination);通过 v-model 来绑定当前页码。
<van-pagination v-model="currentPage" :total-items="24" :items-per-page="5" />import { ref } from 'vue';export default { setup() { const currentPage = ref(1); return { currentPage }; },};将 mode 设置为 simple 来切换到简单模式，此时分页器不会展示具体的页码按钮。
<van-pagination v-model="currentPage" :page-count="12" mode="simple" />设置 force-ellipses 后会展示省略号按钮，点击后可以快速跳转。
<van-pagination v-model="currentPage" :total-items="125" :show-page-size="3" force-ellipses/>通过 prev-text、next-text 等插槽来自定义分页按钮的内容。
<van-pagination v-model="currentPage" :total-items="50" :show-page-size="5"> <template #prev-text> <van-icon name="arrow-left" /> </template> <template #next-text> <van-icon name="arrow" /> </template> <template #page="{ text }">{{ text }}</template></van-pagination>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前页码 | number | - |
| mode | 显示模式，可选值为 simple | string | multi |
| prev-text | 上一页按钮文字 | string | 上一页 |
| next-text | 下一页按钮文字 | string | 下一页 |
| page-count | 总页数 | number | string | 根据页数计算 |
| total-items | 总记录数 | number | string | 0 |
| items-per-page | 每页记录数 | number | string | 10 |
| show-page-size | 显示的页码个数 | number | string | 5 |
| force-ellipses | 是否显示省略号 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 页码改变时触发 | - |
| 名称 | 描述 | 参数 |
|---|---|---|
| page | 自定义页码 | { number: number, text: string, active: boolean } |
| prev-text | 自定义上一页按钮文字 | - |
| next-text | 自定义下一页按钮文字 | - |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-pagination-height | 40px | - |
| --van-pagination-font-size | var(--van-font-size-md) | - |
| --van-pagination-item-width | 36px | - |
| --van-pagination-item-default-color | var(--van-primary-color) | - |
| --van-pagination-item-disabled-color | var(--van-gray-7) | - |
| --van-pagination-item-disabled-background-color | var(--van-background-color) | - |
| --van-pagination-background-color | var(--van-white) | - |
| --van-pagination-desc-color | var(--van-gray-7) | - |
| --van-pagination-disabled-opacity | var(--van-disabled-opacity) | - |
垂直展示的导航栏，用于在不同的内容区域之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Sidebar, SidebarItem } from 'vant';const app = createApp();app.use(Sidebar);app.use(SidebarItem);通过 v-model 绑定当前选中项的索引。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" /></van-sidebar>import { ref } from 'vue';export default { setup() { const active = ref(0); return { active }; },};设置 dot 属性后，会在右上角展示一个小红点；设置 badge 属性后，会在右上角展示相应的徽标。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" dot /> <van-sidebar-item title="标签名称" badge="5" /> <van-sidebar-item title="标签名称" badge="20" /></van-sidebar>通过 disabled 属性禁用选项。
<van-sidebar v-model="active"> <van-sidebar-item title="标签名称" /> <van-sidebar-item title="标签名称" disabled /> <van-sidebar-item title="标签名称" /></van-sidebar>设置 change 方法来监听切换导航项时的事件。
<van-sidebar v-model="active" @change="onChange"> <van-sidebar-item title="标签名 1" /> <van-sidebar-item title="标签名 2" /> <van-sidebar-item title="标签名 3" /></van-sidebar>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onChange = (index) => Toast(`标签名 ${index + 1}`); return { active, onChange, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前导航项的索引 | number | string | 0 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换导航项时触发 | index: number |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 内容 | string | '' |
| dot | 是否显示右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| disabled | 是否禁用该项 | boolean | false |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | index: number |
| Name | Description |
|---|---|
| title | 自定义标题 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-sidebar-width | 80px | - |
| --van-sidebar-font-size | var(--van-font-size-md) | - |
| --van-sidebar-line-height | var(--van-line-height-md) | - |
| --van-sidebar-text-color | var(--van-text-color) | - |
| --van-sidebar-disabled-text-color | var(--van-gray-5) | - |
| --van-sidebar-padding | 20px var(--van-padding-sm) | - |
| --van-sidebar-active-color | var(--van-active-color) | - |
| --van-sidebar-background-color | var(--van-background-color) | - |
| --van-sidebar-selected-font-weight | var(--van-font-weight-bold) | - |
| --van-sidebar-selected-text-color | var(--van-text-color) | - |
| --van-sidebar-selected-border-width | 4px | - |
| --van-sidebar-selected-border-height | 16px | - |
| --van-sidebar-selected-border-color | var(--van-danger-color) | - |
| --van-sidebar-selected-background-color | var(--van-white) | - |
选项卡组件，用于在不同的内容区域之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tab, Tabs } from 'vant';const app = createApp();app.use(Tab);app.use(Tabs);通过 v-model:active 绑定当前激活标签对应的索引值，默认情况下启用第一个标签。
<van-tabs v-model:active="active"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab> <van-tab title="标签 4">内容 4</van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const active = ref(2); return { active }; },};在标签指定 name 属性的情况下，v-model:active 的值为当前标签的 name（此时无法通过索引值来匹配标签）。
<van-tabs v-model:active="activeName"> <van-tab title="标签 1" name="a">内容 1</van-tab> <van-tab title="标签 2" name="b">内容 2</van-tab> <van-tab title="标签 3" name="c">内容 3</van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const activeName = ref('a'); return { activeName }; },};标签数量超过 5 个时，标签栏可以在水平方向上滚动，切换时会自动将当前标签居中。
<van-tabs v-model:active="active"> <van-tab v-for="index in 8" :title="'标签 ' + index"> 内容 {{ index }} </van-tab></van-tabs>设置 disabled 属性即可禁用标签。
<van-tabs v-model:active="active"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2" disabled>内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab></van-tabs>Tab 支持两种样式风格：line 和card，默认为 line 样式，可以通过 type 属性切换样式风格。
<van-tabs v-model:active="active" type="card"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab> <van-tab title="标签 3">内容 3</van-tab></van-tabs>点击标签页时，会触发 click-tab 事件。
<van-tabs v-model:active="active" @click-tab="onClickTab"> <van-tab title="标签 1">内容 1</van-tab> <van-tab title="标签 2">内容 2</van-tab></van-tabs>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onClickTab = ({ title }) => Toast(title); return { active, onClickTab, }; },};通过 sticky 属性可以开启粘性布局，粘性布局下，标签页滚动到顶部时会自动吸顶。
<van-tabs v-model:active="active" sticky> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 title 插槽可以自定义标签内容。
<van-tabs v-model:active="active"> <van-tab v-for="index in 2"> <template #title> <van-icon name="more-o" />选项 </template> 内容 {{ index }} </van-tab></van-tabs>通过 animated 属性可以开启切换标签内容时的转场动画。
<van-tabs v-model:active="active" animated> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 swipeable 属性可以开启滑动切换标签页。
<van-tabs v-model:active="active" swipeable> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 scrollspy 属性可以开启滚动导航模式，该模式下，内容将会平铺展示。
<van-tabs v-model:active="active" scrollspy sticky> <van-tab v-for="index in 8" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>通过 before-change 属性可以在切换标签前执行特定的逻辑。
<van-tabs v-model:active="active" :before-change="beforeChange"> <van-tab v-for="index in 4" :title="'选项 ' + index"> 内容 {{ index }} </van-tab></van-tabs>import { ref } from 'vue';export default { setup() { const active = ref(0); const beforeChange = (index) => { // 返回 false 表示阻止此次切换 if (index === 1) { return false; } // 返回 Promise 来执行异步逻辑 return new Promise((resolve) => { // 在 resolve 函数中返回 true 或 false resolve(index !== 3); }); }; return { beforeChange, }; },};Tips: 通过手势滑动不会触发 before-change 属性。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:active | 绑定当前选中标签的标识符 | number | string | 0 |
| type | 样式风格类型，可选值为 card | string | line |
| color | 标签主题色 | string | #ee0a24 |
| background | 标签栏背景色 | string | white |
| duration | 动画时间，单位秒，设置为 0 可以禁用动画 | number | string | 0.3 |
| line-width | 底部条宽度，默认单位 px | number | string | 40px |
| line-height | 底部条高度，默认单位 px | number | string | 3px |
| animated | 是否开启切换标签内容时的转场动画 | boolean | false |
| border | 是否显示标签栏外边框，仅在 type="line" 时有效 | boolean | false |
| ellipsis | 是否省略过长的标题文字 | boolean | true |
| sticky | 是否使用粘性定位布局 | boolean | false |
| swipeable | 是否开启手势左右滑动切换 | boolean | false |
| lazy-render | 是否开启延迟渲染（首次切换到标签时才触发内容渲染） | boolean | true |
| scrollspy | 是否开启滚动导航 | boolean | false |
| offset-top | 粘性定位布局下与顶部的最小距离，支持 px vw vh rem 单位，默认 px | number | string | 0 |
| swipe-threshold | 滚动阈值，标签数量超过阈值且总宽度超过标签栏宽度时开始横向滚动 | number | string | 5 |
| title-active-color | 标题选中态颜色 | string | - |
| title-inactive-color | 标题默认态颜色 | string | - |
| before-change | 切换标签前的回调函数，返回 false 可阻止切换，支持返回 Promise | (name: number | string) => boolean | Promise<boolean> | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | string | - |
| disabled | 是否禁用标签 | boolean | false |
| dot | 是否在标题右上角显示小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| name | 标签名称，作为匹配的标识符 | number | string | 标签的索引值 |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| title-style | 自定义标题样式 | string | Array | object | - |
| title-class | 自定义标题类名 | string | Array | object | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
click-tab v3.1.4 | 点击标签时触发 | { name: string | number, title: string, event: MouseEvent, disabled: boolean } |
| change | 当前激活的标签改变时触发 | name: string | number, title: string |
| rendered | 标签内容首次渲染时触发（仅在开启延迟渲染后触发） | name: string | number, title: string |
| scroll | 滚动时触发，仅在 sticky 模式下生效 | { scrollTop: number, isFixed: boolean } |
提示：click 和 disabled 事件已废弃，请使用 click-tab 事件代替。
通过 ref 可以获取到 Tabs 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| resize | 外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘 | - | - |
| scrollTo | 滚动到指定的标签页，在滚动导航模式下可用 | name: string | number | - |
通过 TabsInstance 获取 Tabs 实例的类型定义。
import { ref } from 'vue';import type { TabsInstance } from 'vant';const tabsRef = ref<TabsInstance>();tabsRef.value?.scrollTo(0);| 名称 | 说明 |
|---|---|
| nav-left | 标签栏左侧内容 |
| nav-right | 标签栏右侧内容 |
nav-bottom v3.1.1 | 标签栏下方内容 |
| 名称 | 说明 |
|---|---|
| default | 标签页内容 |
| title | 自定义标题 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tab-text-color | var(--van-gray-7) | - |
| --van-tab-active-text-color | var(--van-text-color) | - |
| --van-tab-disabled-text-color | var(--van-gray-5) | - |
| --van-tab-font-size | var(--van-font-size-md) | - |
| --van-tab-line-height | var(--van-line-height-md) | - |
| --van-tabs-default-color | var(--van-danger-color) | - |
| --van-tabs-line-height | 44px | - |
| --van-tabs-card-height | 30px | - |
| --van-tabs-nav-background-color | var(--van-white) | - |
| --van-tabs-bottom-bar-width | 40px | - |
| --van-tabs-bottom-bar-height | 3px | - |
| --van-tabs-bottom-bar-color | var(--van-danger-color) | - |
Tabs 组件在挂载时，会获取自身的宽度，并计算出底部条的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法展示底部条位置。
方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：
<!-- Before --><van-tabs v-show="show" /><!-- After --><van-tabs v-if="show" />方法二，调用组件的 resize 方法来主动触发重绘：
<van-tabs v-show="show" ref="tabs" />this.$refs.tabs.resize();底部导航栏，用于在不同页面之间进行切换。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Tabbar, TabbarItem } from 'vant';const app = createApp();app.use(Tabbar);app.use(TabbarItem);v-model 默认绑定选中标签的索引值，通过修改 v-model 即可切换选中的标签。
<van-tabbar v-model="active"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="friends-o">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref(0); return { active }; },};在标签指定 name 属性的情况下，v-model 的值为当前标签的 name。
<van-tabbar v-model="active"> <van-tabbar-item name="home" icon="home-o">标签</van-tabbar-item> <van-tabbar-item name="search" icon="search">标签</van-tabbar-item> <van-tabbar-item name="friends" icon="friends-o">标签</van-tabbar-item> <van-tabbar-item name="setting" icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref('home'); return { active }; },};设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-tabbar v-model="active"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search" dot>标签</van-tabbar-item> <van-tabbar-item icon="friends-o" badge="5">标签</van-tabbar-item> <van-tabbar-item icon="setting-o" badge="20">标签</van-tabbar-item></van-tabbar>通过 icon 插槽自定义图标，可以通过 slot-scope 判断标签是否选中。
<van-tabbar v-model="active"> <van-tabbar-item badge="3"> <span>自定义</span> <template #icon="props"> <img :src="props.active ? icon.active : icon.inactive" /> </template> </van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>import { ref } from 'vue';export default { setup() { const active = ref(0); const icon = { active: 'https://img.yzcdn.cn/vant/user-active.png', inactive: 'https://img.yzcdn.cn/vant/user-inactive.png', }; return { icon, active, }; },};通过 active-color 属性设置选中标签的颜色，通过 inactive-color 属性设置未选中标签的颜色。
<van-tabbar v-model="active" active-color="#ee0a24" inactive-color="#000"> <van-tabbar-item icon="home-o">标签</van-tabbar-item> <van-tabbar-item icon="search">标签</van-tabbar-item> <van-tabbar-item icon="friends-o">标签</van-tabbar-item> <van-tabbar-item icon="setting-o">标签</van-tabbar-item></van-tabbar>通过 change 事件来监听选中标签的变化。
<van-tabbar v-model="active" @change="onChange"> <van-tabbar-item icon="home-o">标签 1</van-tabbar-item> <van-tabbar-item icon="search">标签 2</van-tabbar-item> <van-tabbar-item icon="friends-o">标签 3</van-tabbar-item> <van-tabbar-item icon="setting-o">标签 4</van-tabbar-item></van-tabbar>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const active = ref(0); const onChange = (index) => Toast(`标签 ${index}`); return { icon, onChange, }; },};标签栏支持路由模式，用于搭配 vue-router 使用。路由模式下会匹配页面路径和标签的 to 属性，并自动选中对应的标签。
<router-view /><van-tabbar route> <van-tabbar-item replace to="/home" icon="home-o">标签</van-tabbar-item> <van-tabbar-item replace to="/search" icon="search">标签</van-tabbar-item></van-tabbar>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中标签的名称或索引值 | number | string | 0 |
| fixed | 是否固定在底部 | boolean | true |
| border | 是否显示外边框 | boolean | true |
| z-index | 元素 z-index | number | string | 1 |
| active-color | 选中标签的颜色 | string | #1989fa |
| inactive-color | 未选中标签的颜色 | string | #7d7e80 |
| route | 是否开启路由模式 | boolean | false |
| placeholder | 固定在底部时，是否在标签位置生成一个等高的占位元素 | boolean | false |
| safe-area-inset-bottom | 是否开启底部安全区适配，设置 fixed 时默认开启 | boolean | false |
| before-change | 切换标签前的回调函数，返回 false 可阻止切换，支持返回 Promise | (name: number | string) => boolean | Promise<boolean> | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 切换标签时触发 | active: number | string |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标签名称，作为匹配的标识符 | number | string | 当前标签的索引值 |
| icon | 图标名称或图片链接 | string | - |
| icon-prefix | 图标类名前缀，等同于 Icon 组件的 class-prefix 属性 | string | van-icon |
| dot | 是否显示图标右上角小红点 | boolean | false |
| badge | 图标右上角徽标的内容 | number | string | - |
| url | 点击后跳转的链接地址 | string | - |
| to | 点击后跳转的目标路由对象，等同于 vue-router 的 to 属性 | string | object | - |
| replace | 是否在跳转时替换当前页面历史 | boolean | false |
| 名称 | 说明 | 参数 |
|---|---|---|
| icon | 自定义图标 | active: boolean |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tabbar-height | 50px | - |
| --van-tabbar-z-index | 1 | - |
| --van-tabbar-background-color | var(--van-white) | - |
| --van-tabbar-item-font-size | var(--van-font-size-sm) | - |
| --van-tabbar-item-text-color | var(--van-gray-7) | - |
| --van-tabbar-item-active-color | var(--van-primary-color) | - |
| --van-tabbar-item-active-background-color | var(--van-white) | - |
| --van-tabbar-item-line-height | 1 | - |
| --van-tabbar-item-icon-size | 22px | - |
| --van-tabbar-item-icon-margin-bottom | var(--van-padding-base) | - |
用于从一组相关联的数据集合中进行选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { TreeSelect } from 'vant';const app = createApp();app.use(TreeSelect);item 为分类显示所需的数据，数据格式见下方示例。main-active-index 表示左侧高亮选项的索引，active-id 表示右侧高亮选项的 id。
<van-tree-select v-model:active-id="state.activeId" v-model:main-active-index="state.activeIndex" :items="items"/>import { reactive } from 'vue';export default { setup() { const state = reactive({ activeId: 1, activeIndex: 0, }); const items = [ { text: '浙江', children: [ { text: '杭州', id: 1 }, { text: '温州', id: 2 }, ], }, { text: '江苏', children: [ { text: '南京', id: 5 }, { text: '无锡', id: 6 }, ], }, ]; return { state, items, }; },};active-id 为数组格式时，可以选中多个右侧选项。
<van-tree-select v-model:active-id="state.activeIds" v-model:main-active-index="state.activeIndex" :items="items"/>import { reactive } from 'vue';export default { setup() { const state = reactive({ activeId: [1, 2], activeIndex: 0, }); const items = [ { text: '浙江', children: [ { text: '杭州', id: 1 }, { text: '温州', id: 2 }, ], }, { text: '江苏', children: [ { text: '南京', id: 5 }, { text: '无锡', id: 6 }, ], }, ]; return { state, items, }; },};通过 content 插槽可以自定义右侧区域的内容。
<van-tree-select v-model:main-active-index="activeIndex" height="55vw" :items="items"> <template #content> <van-image v-if="activeIndex === 0" src="https://img.yzcdn.cn/vant/apple-1.jpg" rel="external nofollow" /> <van-image v-if="activeIndex === 1" src="https://img.yzcdn.cn/vant/apple-2.jpg" rel="external nofollow" /> </template></van-tree-select>import { ref } from 'vue';export default { setup() { const activeIndex = ref(0); return { activeIndex, items: [{ text: '分组 1' }, { text: '分组 2' }], }; },};设置 dot 属性后，会在图标右上角展示一个小红点；设置 badge 属性后，会在图标右上角展示相应的徽标。
<van-tree-select v-model:main-active-index="activeIndex" height="55vw" :items="items"/>import { ref } from 'vue';export default { setup() { const activeIndex = ref(0); return { activeIndex, items: [ { text: '浙江', children: [], dot: true }, { text: '江苏', children: [], badge: 5 }, ], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| items | 分类显示所需的数据 | Item[] | [] |
| height | 高度，默认单位为px | number | string | 300 |
| main-active-index | 左侧选中项的索引 | number | string | 0 |
| active-id | 右侧选中项的 id，支持传入数组 | number | string | (number | string)[] | 0 |
| max | 右侧项最大选中个数 | number | string | Infinity |
| selected-icon | 自定义右侧栏选中状态的图标 | string | success |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click-nav | 点击左侧导航时触发 | index：被点击的导航的索引 |
| click-item | 点击右侧选择项时触发 | data: 该点击项的数据 |
| 名称 | 说明 |
|---|---|
| content | 自定义右侧区域内容 |
items 整体为一个数组，数组内包含一系列描述分类的对象，每个分类里，text表示当前分类的名称，children表示分类里的可选项。
[ { // 导航名称 text: '所有城市', // 导航名称右上角徽标 badge: 3, // 是否在导航名称右上角显示小红点 dot: true, // 导航节点额外类名 className: 'my-class', // 该导航下所有的可选项 children: [ { // 名称 text: '温州', // id，作为匹配选中状态的标识符 id: 1, // 禁用选项 disabled: true, }, { text: '杭州', id: 2, }, ], },];组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-tree-select-font-size | var(--van-font-size-md) | - |
| --van-tree-select-nav-background-color | var(--van-background-color) | - |
| --van-tree-select-content-background-color | var(--van-white) | - |
| --van-tree-select-nav-item-padding | 14px var(--van-padding-sm) | - |
| --van-tree-select-item-height | 48px | - |
| --van-tree-select-item-active-color | var(--van-danger-color) | - |
| --van-tree-select-item-disabled-color | var(--van-gray-5) | - |
| --van-tree-select-item-selected-size | 16px | - |
收货地址编辑组件，用于新建、更新、删除收货地址。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { AddressEdit } from 'vant';const app = createApp();app.use(AddressEdit);<van-address-edit :area-list="areaList" show-postal show-delete show-set-default show-search-result :search-result="searchResult" :area-columns-placeholder="['请选择', '请选择', '请选择']" @save="onSave" @delete="onDelete" @change-detail="onChangeDetail"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const searchResult = ref([]); const onSave = () => Toast('save'); const onDelete = () => Toast('delete'); const onChangeDetail = (val) => { if (val) { searchResult.value = [ { name: '黄龙万科中心', address: '杭州市西湖区', }, ]; } else { searchResult.value = []; } }; return { onSave, onDelete, areaList, searchResult, onChangeDetail, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| area-list | 地区列表 | object | - |
| area-columns-placeholder | 地区选择列占位提示文字 | string[] | [] |
| area-placeholder | 地区输入框占位提示文字 | string | 选择省 / 市 / 区 |
| address-info | 收货人信息初始值 | AddressInfo | {} |
| search-result | 详细地址搜索结果 | SearchResult[] | [] |
| show-postal | 是否显示邮政编码 | boolean | false |
| show-delete | 是否显示删除按钮 | boolean | false |
| show-set-default | 是否显示默认地址栏 | boolean | false |
| show-search-result | 是否显示搜索结果 | boolean | false |
| show-area | 是否显示地区 | boolean | true |
| show-detail | 是否显示详细地址 | boolean | true |
| disable-area | 是否禁用地区选择 | boolean | false |
| save-button-text | 保存按钮文字 | string | 保存 |
| delete-button-text | 删除按钮文字 | string | 删除 |
| detail-rows | 详细地址输入框行数 | number | string | 1 |
| detail-maxlength | 详细地址最大长度 | number | string | 200 |
| is-saving | 是否显示保存按钮加载动画 | boolean | false |
| is-deleting | 是否显示删除按钮加载动画 | boolean | false |
| tel-validator | 手机号格式校验函数 | string => boolean | - |
| tel-maxlength | 手机号最大长度 | number | string | - |
| postal-validator | 邮政编码格式校验函数 | string => boolean | - |
| validator | 自定义校验函数 | (key, val) => string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| save | 点击保存按钮时触发 | content：表单内容 |
| focus | 输入框聚焦时触发 | key: 聚焦的输入框对应的 key |
| delete | 确认删除地址时触发 | content：表单内容 |
| cancel-delete | 取消删除地址时触发 | content：表单内容 |
| select-search | 选中搜索结果时触发 | value: 搜索结果 |
| click-area | 点击收件地区时触发 | - |
| change-area | 修改收件地区时触发 | values: 地区信息 |
| change-detail | 修改详细地址时触发 | value: 详细地址内容 |
| change-default | 切换是否使用默认地址时触发 | value: 是否选中 |
| 名称 | 说明 |
|---|---|
| default | 在邮政编码下方插入内容 |
通过 ref 可以获取到 AddressEdit 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| setAddressDetail | 设置详细地址 | addressDetail: string | - |
通过 AddressEditInstance 获取 AddressEdit 实例的类型定义。
import { ref } from 'vue';import type { AddressEditInstance } from 'vant';const addressEditRef = ref<AddressEditInstance>();addressEditRef.value?.setAddressDetail('');注意：AddressInfo 仅作为初始值传入，表单最终内容可以在 save 事件中获取。
| key | 说明 | 类型 |
|---|---|---|
| name | 收货人姓名 | string |
| tel | 收货人手机号 | string |
| province | 省份 | string |
| city | 城市 | string |
| county | 区县 | string |
| addressDetail | 详细地址 | string |
| areaCode | 地区编码，通过 省市区选择 获取（必填） | string |
| postalCode | 邮政编码 | string |
| isDefault | 是否为默认地址 | boolean |
| key | 说明 | 类型 |
|---|---|---|
| name | 地名 | string |
| address | 详细地址 | string |
请参考 Area 组件。
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-address-edit-padding | var(--van-padding-sm) | - |
| --van-address-edit-buttons-padding | var(--van-padding-xl) var(--van-padding-base) | - |
| --van-address-edit-button-margin-bottom | var(--van-padding-sm) | - |
| --van-address-edit-button-font-size | var(--van-font-size-lg) | - |
| --van-address-edit-detail-finish-color | var(--van-primary-color) | - |
| --van-address-edit-detail-finish-font-size | var(--van-font-size-sm) | - |
展示收货地址列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { AddressList } from 'vant';const app = createApp();app.use(AddressList);<van-address-list v-model="chosenAddressId" :list="list" :disabled-list="disabledList" disabled-text="以下地址超出配送范围" default-tag-text="默认" @add="onAdd" @edit="onEdit"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const chosenAddressId = ref('1'); const list = [ { id: '1', name: '张三', tel: '13000000000', address: '浙江省杭州市西湖区文三路 138 号东方通信大厦 7 楼 501 室', isDefault: true, }, { id: '2', name: '李四', tel: '1310000000', address: '浙江省杭州市拱墅区莫干山路 50 号', }, ]; const disabledList = [ { id: '3', name: '王五', tel: '1320000000', address: '浙江省杭州市滨江区江南大道 15 号', }, ]; const onAdd = () => Toast('新增地址'); const onEdit = (item, index) => Toast('编辑地址:' + index); return { list, onAdd, onEdit, disabledList, chosenAddressId, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中地址的 id | string | - |
| list | 地址列表 | Address[] | [] |
| disabled-list | 不可配送地址列表 | Address[] | [] |
| disabled-text | 不可配送提示文案 | string | - |
| switchable | 是否允许切换地址 | boolean | true |
| add-button-text | 底部按钮文字 | string | 新增地址 |
| default-tag-text | 默认地址标签文字 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| add | 点击新增按钮时触发 | - |
| edit | 点击编辑按钮时触发 | item: Address, index: number |
| select | 切换选中的地址时触发 | item: Address, index: number |
| edit-disabled | 编辑不可配送的地址时触发 | item: Address, index: number |
| select-disabled | 选中不可配送的地址时触发 | item: Address, index: number |
| click-item | 点击任意地址时触发 | item: Address, index: number |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 每条地址的唯一标识 | number | string |
| name | 收货人姓名 | string |
| tel | 收货人手机号 | number | string |
| address | 收货地址 | string |
| isDefault | 是否为默认地址 | boolean |
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 在列表下方插入内容 | - |
| top | 在顶部插入内容 | - |
| item-bottom | 在列表项底部插入内容 | item: Address |
tag v3.0.9 | 自定义列表项标签内容 | item: Address |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-address-list-padding | var(--van-padding-sm) var(--van-padding-sm) 80px | - |
| --van-address-list-disabled-text-color | var(--van-gray-6) | - |
| --van-address-list-disabled-text-padding | var(--van-padding-base) * 5 0 var(--van-padding-md) | - |
| --van-address-list-disabled-text-font-size | var(--van-font-size-md) | - |
| --van-address-list-disabled-text-line-height | var(--van-line-height-md) | - |
| --van-address-list-add-button-z-index | 999 | - |
| --van-address-list-item-padding | var(--van-padding-sm) | - |
| --van-address-list-item-text-color | var(--van-text-color) | - |
| --van-address-list-item-disabled-text-color | var(--van-gray-5) | - |
| --van-address-list-item-font-size | 13px | - |
| --van-address-list-item-line-height | var(--van-line-height-sm) | - |
| --van-address-list-item-radio-icon-color | var(--van-danger-color) | - |
| --van-address-list-edit-icon-size | 20px | - |
省市区三级联动选择，通常与弹出层组件配合使用。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Area } from 'vant';const app = createApp();app.use(Area);初始化省市区组件时，需要通过 area-list 属性传入省市区数据。
<van-area title="标题" :area-list="areaList" />areaList 为对象结构，包含 province_list、city_list、county_list 三个 key。
每项以地区码作为 key，省市区名字作为 value。地区码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。比如北京的地区码为 11，以 0 补足 6 位，为 110000。
示例数据如下：
const areaList = { province_list: { 110000: '北京市', 120000: '天津市', }, city_list: { 110100: '北京市', 120100: '天津市', }, county_list: { 110101: '东城区', 110102: '西城区', // .... },};Vant 官方提供了一份默认的省市区数据，可以通过 @vant/area-data 引入：
yarn add @vant/area-dataimport { areaList } from '@vant/area-data';export default { setup() { return { areaList }; },};如果想选中某个省市区，需要传入一个 value 属性，绑定对应的地区码。
<van-area title="标题" :area-list="areaList" value="110101" />可以通过 columns-num 属性配置省市区显示的列数，默认情况下会显示省市区，当你设置为 2，则只会显示省市选择。
<van-area title="标题" :area-list="areaList" :columns-num="2" />可以通过 columns-placeholder 属性配置每一列的占位提示文字。
<van-area title="标题" :area-list="areaList" :columns-placeholder="['请选择', '请选择', '请选择']"/>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 当前选中项对应的地区码 | string | - |
| title | 顶部栏标题 | string | - |
| confirm-button-text | 确认按钮文字 | string | 确认 |
| cancel-button-text | 取消按钮文字 | string | 取消 |
| area-list | 省市区数据，格式见下方 | object | - |
| columns-placeholder | 列占位提示文字 | string[] | [] |
| loading | 是否显示加载状态 | boolean | false |
| readonly | 是否为只读状态，只读状态下无法切换选项 | boolean | false |
| item-height | 选项高度，支持 px vw vh rem 单位，默认 px | number | string | 44 |
| columns-num | 显示列数，3-省市区，2-省市，1-省 | number | string | 3 |
| visible-item-count | 可见的选项个数 | number | string | 6 |
| swipe-duration | 快速滑动时惯性滚动的时长，单位 ms | number | string | 1000 |
| is-oversea-code | 根据地区码校验海外地址，海外地址会划分至单独的分类 | () => boolean | - |
| 事件 | 说明 | 回调参数 |
|---|---|---|
| confirm | 点击右上方完成按钮 | result: ConfirmResult |
| cancel | 点击取消按钮时 | - |
| change | 选项改变时触发 | 所有列选中值，当前列对应的索引 |
confirm 事件返回的数据整体为一个数组，数组每一项对应一列选项中被选中的数据。
[ { code: '110000', name: '北京市', }, { code: '110100', name: '北京市', }, { code: '110101', name: '东城区', },];| 名称 | 说明 | 参数 |
|---|---|---|
toolbar v3.1.2 | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
confirm v3.1.2 | 自定义确认按钮内容 | - |
cancel v3.1.2 | 自定义取消按钮内容 | - |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
通过 ref 可以获取到 Area 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| reset | 根据地区码重置所有选项，若不传地区码，则重置到第一项 | code?: string | - |
通过 AreaInstance 获取 Area 实例的类型定义。
import { ref } from 'vue';import type { AreaInstance } from 'vant';const areaRef = ref<AreaInstance>();areaRef.value?.reset();参见桌面端适配。
商品卡片，用于展示商品的图片、价格等信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { Card } from 'vant';const app = createApp();app.use(Card);<van-card num="2" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg"/>通过 origin-price 设置商品原价，通过 tag 设置商品左上角标签。
<van-card num="2" tag="标签" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg" origin-price="10.00"/>Card 组件提供了多个插槽，可以灵活地自定义内容。
<van-card num="2" price="2.00" desc="描述信息" title="商品标题" thumb="https://img.yzcdn.cn/vant/ipad.jpeg"> <template #tags> <van-tag plain type="danger">标签</van-tag> <van-tag plain type="danger">标签</van-tag> </template> <template #footer> <van-button size="mini">按钮</van-button> <van-button size="mini">按钮</van-button> </template></van-card>| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| thumb | 左侧图片 URL | string | - |
| title | 标题 | string | - |
| desc | 描述 | string | - |
| tag | 图片角标 | string | - |
| num | 商品数量 | number | string | - |
| price | 商品价格 | number | string | - |
| origin-price | 商品划线原价 | number | string | - |
| centered | 内容是否垂直居中 | boolean | false |
| currency | 货币符号 | string | ¥ |
| thumb-link | 点击左侧图片后跳转的链接地址 | string | - |
| lazy-load | 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
| click-thumb | 点击自定义图片时触发 | event: MouseEvent |
| 名称 | 说明 |
|---|---|
| title | 自定义标题 |
| desc | 自定义描述 |
| num | 自定义数量 |
| price | 自定义价格 |
| origin-price | 自定义商品原价 |
| price-top | 自定义价格上方区域 |
| bottom | 自定义价格下方区域 |
| thumb | 自定义图片 |
| tag | 自定义图片角标 |
| tags | 自定义描述下方标签区域 |
| footer | 自定义右下角内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-card-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-card-font-size | var(--van-font-size-sm) | - |
| --van-card-text-color | var(--van-text-color) | - |
| --van-card-background-color | var(--van-background-color-light) | - |
| --van-card-thumb-size | 88px | - |
| --van-card-thumb-border-radius | var(--van-border-radius-lg) | - |
| --van-card-title-line-height | 16px | - |
| --van-card-desc-color | var(--van-gray-7) | - |
| --van-card-desc-line-height | var(--van-line-height-md) | - |
| --van-card-price-color | var(--van-gray-8) | - |
| --van-card-origin-price-color | var(--van-gray-6) | - |
| --van-card-num-color | var(--van-gray-6) | - |
| --van-card-origin-price-font-size | var(--van-font-size-xs) | - |
| --van-card-price-font-size | var(--van-font-size-sm) | - |
| --van-card-price-integer-font-size | var(--van-font-size-lg) | - |
| --van-card-price-font-family | var(--van-price-integer-font-family) | - |
以卡片的形式展示联系人信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactCard } from 'vant';const app = createApp();app.use(ContactCard);<van-contact-card type="add" @click="onAdd" />import { Toast } from 'vant';export default { setup() { const onAdd = () => Toast('新增'); return { onAdd, }; },};<van-contact-card type="edit" :name="currentContact.name" :tel="currentContact.tel" @click="onEdit"/>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const currentContact = reactive({ name: '张三', tel: '13000000000', }); const onEdit = () => Toast('edit'); return { onEdit, currentContact, }; },};<van-contact-card type="edit" name="张三" tel="13000000000" :editable="false" />| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 卡片类型，可选值为 edit | string | add |
| name | 联系人姓名 | string | - |
| tel | 联系人手机号 | string | - |
| add-text | 添加时的文案提示 | string | 添加联系人 |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击时触发 | event: MouseEvent |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-card-padding | var(--van-padding-md) | - |
| --van-contact-card-add-icon-size | 40px | - |
| --van-contact-card-add-icon-color | var(--van-primary-color) | - |
| --van-contact-card-value-line-height | var(--van-line-height-md) | - |
编辑并保存联系人信息。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactEdit } from 'vant';const app = createApp();app.use(ContactEdit);<van-contact-edit is-edit show-set-default :contact-info="editingContact" set-default-label="设为默认联系人" @save="onSave" @delete="onDelete"/>import { ref } from 'vue';import { Toast } from 'vant';export default { setup() { const editingContact = ref({}); const onSave = (contactInfo) => Toast('保存'); const onDelete = (contactInfo) => Toast('删除'); return { onSave, onDelete, editingContact, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| contact-info | 联系人信息 | Contact | {} |
| is-edit | 是否为编辑联系人 | boolean | false |
| is-saving | 是否显示保存按钮加载动画 | boolean | false |
| is-deleting | 是否显示删除按钮加载动画 | boolean | false |
| tel-validator | 手机号格式校验函数 | (tel: string) => boolean | - |
| show-set-default | 是否显示默认联系人栏 | boolean | false |
| set-default-label | 默认联系人栏文案 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| save | 点击保存按钮时触发 | content：表单内容 |
| delete | 点击删除按钮时触发 | content：表单内容 |
| 键名 | 说明 | 类型 |
|---|---|---|
| name | 联系人姓名 | string |
| tel | 联系人手机号 | number | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-edit-padding | var(--van-padding-md) | - |
| --van-contact-edit-fields-radius | var(--van-border-radius-md) | - |
| --van-contact-edit-buttons-padding | var(--van-padding-xl) 0 | - |
| --van-contact-edit-button-margin-bottom | var(--van-padding-sm) | - |
| --van-contact-edit-button-font-size | var(--van-font-size-lg) | - |
| --van-contact-edit-field-label-width | 4.1em | - |
展示联系人列表。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { ContactList } from 'vant';const app = createApp();app.use(ContactList);<van-contact-list v-model="state.chosenContactId" :list="state.list" default-tag-text="默认" @add="onAdd" @edit="onEdit" @select="onSelect"/>import { reactive } from 'vue';import { Toast } from 'vant';export default { setup() { const state = reactive({ chosenContactId: '1', list: [ { id: '1', name: '张三', tel: '13000000000', isDefault: true, }, { id: '2', name: '李四', tel: '1310000000', }, ], }); const onAdd = () => Toast('新增'); const onEdit = (contact) => Toast('编辑' + contact.id); const onSelect = (contact) => Toast('选择' + contact.id); return { state, onAdd, onEdit, onSelect, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 当前选中联系人的 id | number | string | - |
| list | 联系人列表 | Contact[] | [] |
| add-text | 新建按钮文案 | string | 新建联系人 |
| default-tag-text | 默认联系人标签文案 | string | - |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| add | 点击新增按钮时触发 | - |
| edit | 点击编辑按钮时触发 | contact: Contact，index: number |
| select | 切换选中的联系人时触发 | contact: Contact，index: number |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 每位联系人的唯一标识 | number | string |
| name | 联系人姓名 | string |
| tel | 联系人手机号 | number | string |
| isDefault | 是否为默认联系人 | boolean |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-contact-list-edit-icon-size | 16px | - |
| --van-contact-list-add-button-z-index | 999 | - |
| --van-contact-list-item-padding | var(--van-padding-md) | - |
| --van-contact-list-item-radio-icon-color | var(--van-danger-color) | - |
用于优惠券的兑换和选择。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { CouponCell, CouponList } from 'vant';const app = createApp();app.use(CouponCell);app.use(CouponList);<!-- 优惠券单元格 --><van-coupon-cell :coupons="state.coupons" :chosen-coupon="state.chosenCoupon" @click="state.showList = true"/><!-- 优惠券列表 --><van-popup v-model="state.showList" round position="bottom" style="height: 90%; padding-top: 4px;"> <van-coupon-list :coupons="state.coupons" :chosen-coupon="state.chosenCoupon" :disabled-coupons="disabledCoupons" @change="onChange" @exchange="onExchange" /></van-popup>import { reactive } from 'vue';const coupon = { available: 1, condition: '无使用门槛
最多优惠12元', reason: '', value: 150, name: '优惠券名称', startAt: 1489104000, endAt: 1514592000, valueDesc: '1.5', unitDesc: '元',};export default { setup() { const state = reactive({ coupons: [coupon], showList: false, chosenCoupon: -1, }); const onChange = (index) => { state.showList = false; state.chosenCoupon = index; }; const onExchange = (code) => { state.coupons.push(coupon); }; return { state, onChange, onExchange, disabledCoupons: [coupon], }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 单元格标题 | string | 优惠券 |
| chosen-coupon | 当前选中优惠券的索引 | number | string | -1 |
| coupons | 可用优惠券列表 | Coupon[] | [] |
| editable | 能否切换优惠券 | boolean | true |
| border | 是否显示内边框 | boolean | true |
| currency | 货币符号 | string | ¥ |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:code | 当前输入的兑换码 | string | - |
| chosen-coupon | 当前选中优惠券的索引 | number | -1 |
| coupons | 可用优惠券列表 | Coupon[] | [] |
| disabled-coupons | 不可用优惠券列表 | Coupon[] | [] |
| enabled-title | 可用优惠券列表标题 | string | 可使用优惠券 |
| disabled-title | 不可用优惠券列表标题 | string | 不可使用优惠券 |
| exchange-button-text | 兑换按钮文字 | string | 兑换 |
| exchange-button-loading | 是否显示兑换按钮加载动画 | boolean | false |
| exchange-button-disabled | 是否禁用兑换按钮 | boolean | false |
| exchange-min-length | 兑换码最小长度 | number | 1 |
| displayed-coupon-index | 滚动至特定优惠券位置 | number | - |
| show-close-button | 是否显示列表底部按钮 | boolean | true |
| close-button-text | 列表底部按钮文字 | string | 不使用优惠 |
| input-placeholder | 输入框文字提示 | string | 请输入优惠码 |
| show-exchange-bar | 是否展示兑换栏 | boolean | true |
| currency | 货币符号 | string | ¥ |
| empty-image | 列表为空时的占位图 | string | https://img.yzcdn.cn/vant/coupon-empty.png |
| show-count | 是否展示可用 / 不可用数量 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 优惠券切换回调 | index, 选中优惠券的索引 |
| exchange | 兑换优惠券回调 | code, 兑换码 |
| 名称 | 说明 |
|---|---|
list-footer v3.0.18 | 优惠券列表底部 |
disabled-list-footer v3.0.18 | 不可用优惠券列表底部 |
| 键名 | 说明 | 类型 |
|---|---|---|
| id | 优惠券 id | string |
| name | 优惠券名称 | string |
| condition | 满减条件 | string |
| startAt | 卡有效开始时间 (时间戳, 单位秒) | number |
| endAt | 卡失效日期 (时间戳, 单位秒) | number |
| description | 描述信息，优惠券可用时展示 | string |
| reason | 不可用原因，优惠券不可用时展示 | string |
| value | 折扣券优惠金额，单位分 | number |
| valueDesc | 折扣券优惠金额文案 | string |
| unitDesc | 单位文案 | string |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-coupon-margin | 0 var(--van-padding-sm) var(--van-padding-sm) | - |
| --van-coupon-content-height | 84px | - |
| --van-coupon-content-padding | 14px 0 | - |
| --van-coupon-background-color | var(--van-white) | - |
| --van-coupon-active-background-color | var(--van-active-color) | - |
| --van-coupon-border-radius | var(--van-border-radius-lg) | - |
| --van-coupon-box-shadow | 0 0 4px rgba(0, 0, 0, 0.1) | - |
| --van-coupon-head-width | 96px | - |
| --van-coupon-amount-color | var(--van-danger-color) | - |
| --van-coupon-amount-font-size | 30px | - |
| --van-coupon-currency-font-size | 40% | - |
| --van-coupon-name-font-size | var(--van-font-size-md) | - |
| --van-coupon-disabled-text-color | var(--van-gray-6) | - |
| --van-coupon-description-padding | var(--van-padding-xs) var(--van-padding-md) | - |
| --van-coupon-description-border-color | var(--van-border-color) | - |
| --van-coupon-corner-checkbox-icon-color | var(--van-danger-color) | - |
| --van-coupon-list-background-color | var(--van-background-color) | - |
| --van-coupon-list-field-padding | 5px 0 5px var(--van-padding-md) | - |
| --van-coupon-list-exchange-button-height | 32px | - |
| --van-coupon-list-close-button-height | 40px | - |
| --van-coupon-list-empty-image-size | 200px | - |
| --van-coupon-list-empty-tip-color | var(--van-gray-6) | - |
| --van-coupon-list-empty-tip-font-size | var(--van-font-size-md) | - |
| --van-coupon-list-empty-tip-line-height | var(--van-line-height-md) | - |
| --van-coupon-cell-selected-text-color | var(--van-text-color) | - |
用于展示订单金额与提交订单。
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
import { createApp } from 'vue';import { SubmitBar } from 'vant';const app = createApp();app.use(SubmitBar);<van-submit-bar :price="3050" button-text="提交订单" @submit="onSubmit" />import { Toast } from 'vant';export default { setup() { const onSubmit = () => Toast('点击按钮'); return { onSubmit, }; },};禁用状态下不会触发 submit 事件。
<van-submit-bar disabled :price="3050" button-text="提交订单" tip="你的收货地址不支持同城送, 我们已为你推荐快递" tip-icon="info-o" @submit="onSubmit"/>加载状态下不会触发 submit 事件。
<van-submit-bar loading :price="3050" button-text="提交订单" @submit="onSubmit"/>通过插槽插入自定义内容。
<van-submit-bar :price="3050" button-text="提交订单" @submit="onSubmit"> <van-checkbox v-model="checked">全选</van-checkbox> <template #tip> 你的收货地址不支持同城送, <span @click="onClickLink">修改地址</span> </template></van-submit-bar>import { Toast } from 'vant';export default { setup() { const onSubmit = () => Toast('点击按钮'); const onClickLink = () => Toast('修改地址'); return { onSubmit, onClickLink, }; },};| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| price | 金额（单位分） | number | - |
| decimal-length | 金额小数点位数 | number | string | 2 |
| label | 金额左侧文案 | string | 合计： |
| suffix-label | 金额右侧文案 | string | - |
| text-align | 金额文案对齐方向，可选值为 left | string | right |
| button-text | 按钮文字 | string | - |
| button-type | 按钮类型 | string | danger |
| button-color | 自定义按钮颜色 | string | - |
| tip | 在订单栏上方的提示文案 | string | - |
| tip-icon | 提示文案左侧的图标名称或图片链接 | string | - |
| currency | 货币符号 | string | ¥ |
| disabled | 是否禁用按钮 | boolean | false |
| loading | 是否显示将按钮显示为加载中状态 | boolean | false |
| safe-area-inset-bottom | 是否开启底部安全区适配 | boolean | true |
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| submit | 按钮点击事件回调 | - |
| 名称 | 说明 |
|---|---|
| default | 自定义订单栏左侧内容 |
| button | 自定义按钮 |
| top | 自定义订单栏上方内容 |
| tip | 提示文案中的额外内容 |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-submit-bar-height | 50px | - |
| --van-submit-bar-z-index | 100 | - |
| --van-submit-bar-background-color | var(--van-white) | - |
| --van-submit-bar-button-width | 110px | - |
| --van-submit-bar-price-color | var(--van-danger-color) | - |
| --van-submit-bar-text-color | var(--van-text-color) | - |
| --van-submit-bar-text-font-size | var(--van-font-size-md) | - |
| --van-submit-bar-tip-padding | var(--van-padding-xs) var(--van-padding-sm) | - |
| --van-submit-bar-tip-font-size | var(--van-font-size-sm) | - |
| --van-submit-bar-tip-line-height | 1.5 | - |
| --van-submit-bar-tip-color | #f56723 | - |
| --van-submit-bar-tip-background-color | #fff7cc | - |
| --van-submit-bar-tip-icon-size | 12px | - |
| --van-submit-bar-button-height | 40px | - |
| --van-submit-bar-padding | 0 var(--van-padding-md) | - |
| --van-submit-bar-price-font-size | var(--van-font-size-sm) | - |
| --van-submit-bar-price-integer-font-size | 20px | - |
| --van-submit-bar-price-font-family | var(--van-price-integer-font-family) | - |
Vant 内置了一系列的组合式 API，对于安装了 vant 的项目，可以直接使用这些 API 进行开发。
下面是一个 Vant 组合式 API 的用法示例，我们从 @vant/use 这个包中引入 useWindowSize 方法，然后进行调用，即可获取到当前 Window 的宽度和高度。
import { useWindowSize } from '@vant/use';const { width, height } = useWindowSize();console.log(width.value); // -> 窗口宽度console.log(height.value); // -> 窗口高度下面是 Vant 对外提供的所有组合式 API，点击名称可以查看详细介绍：
| 名称 | 描述 |
|---|---|
| useClickAway | 监听点击元素外部的事件 |
| useCountDown | 提供倒计时管理能力 |
| useEventListener | 方便地进行事件绑定 |
| usePageVisibility | 获取页面的可见状态 |
| useRect | 获取元素的大小及其相对于视口的位置 |
| useRelation | 建立父子组件之间的关联关系 |
| useScrollParent | 获取元素最近的可滚动父元素 |
| useToggle | 用于在布尔值之间进行切换 |
| useWindowSize | 获取浏览器窗口的视口宽度和高度 |
用于在 true 和 false 之间进行切换。
import { useToggle } from '@vant/use';export default { setup() { const [state, toggle] = useToggle(); toggle(true); console.log(state.value); // -> true toggle(false); console.log(state.value); // -> false toggle(); console.log(state.value); // -> true },};import { useToggle } from '@vant/use';export default { setup() { const [state, toggle] = useToggle(true); console.log(state.value); // -> true },};function useToggle( defaultValue: boolean): [Ref<boolean>, (newValue: boolean) => void];| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| defaultValue | 默认值 | boolean | false |
| 参数 | 说明 | 类型 |
|---|---|---|
| state | 状态值 | Ref<boolean> |
| toggle | 切换状态值的函数 | (newValue?: boolean) => void |
提供倒计时管理能力。
<span>总时间：{{ current.total }}</span><span>剩余天数：{{ current.days }}</span><span>剩余小时：{{ current.hours }}</span><span>剩余分钟：{{ current.minutes }}</span><span>剩余秒数：{{ current.seconds }}</span><span>剩余毫秒：{{ current.milliseconds }}</span>import { useCountDown } from '@vant/use';export default { setup() { const countDown = useCountDown({ // 倒计时 24 小时 time: 24 * 60 * 60 * 1000, }); // 开始倒计时 countDown.start(); return { current: countDown.current, }; },};倒计时默认每秒渲染一次，设置 millisecond 选项可以开启毫秒级渲染。
import { useCountDown } from '@vant/use';export default { setup() { const countDown = useCountDown({ time: 24 * 60 * 60 * 1000, millisecond: true, }); countDown.start(); return { current: countDown.current, }; },};type CurrentTime = { days: number; hours: number; total: number; minutes: number; seconds: number; milliseconds: number;};type CountDown = { start: () => void; pause: () => void; reset: (totalTime: number) => void; current: ComputedRef<CurrentTime>;};type UseCountDownOptions = { time: number; millisecond?: boolean; onChange?: (current: CurrentTime) => void; onFinish?: () => void;};function useCountDown(options: UseCountDownOptions): CountDown;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| time | 倒计时时长，单位毫秒 | number | - |
| millisecond | 是否开启毫秒级渲染 | boolean | false |
| onChange | 倒计时改变时触发的回调函数 | (current: CurrentTime) => void | - |
| onFinish | 倒计时结束时触发的回调函数 | - |
| 参数 | 说明 | 类型 |
|---|---|---|
| current | 当前剩余的时间 | CurrentTime |
| start | 开始倒计时 | () => void |
| pause | 暂停倒计时 | () => void |
| reset | 重置倒计时，支持传入新的倒计时时长 | (time?: number): void |
| 名称 | 说明 | 类型 |
|---|---|---|
| total | 剩余总时间（单位毫秒） | number |
| days | 剩余天数 | number |
| hours | 剩余小时 | number |
| minutes | 剩余分钟 | number |
| seconds | 剩余秒数 | number |
| milliseconds | 剩余毫秒 | number |
用于自定义 Form 组件中的表单项。
如果需要自定义表单项，可以在 Field 组件的 input 插槽中插入你的自定义组件，并在自定义组件内部调用 useCustomFieldValue 方法。
首先，在你的自定义组件中，调用 useCustomFieldValue 方法，并传入一个回调函数，这个函数返回值为表单项的值。
// MyComponent.vueimport { useCustomFieldValue } from '@vant/use';export default { setup() { // 此处传入的值会替代 Field 组件内部的 value useCustomFieldValue(() => 'Some value'); },};接着，在 Form 组件中嵌入你的自定义组件，当提交表单时，即可获取到自定义表单项的值。
<van-form> <!-- 这是一个自定义表单项 --> <!-- 当表单提交时，会包括 useCustomFieldValue 中传入的值 --> <van-field name="my-field" label="自定义表单项"> <template #input> <my-component /> </template> </van-field></van-form>function useCustomFieldValue(customValue: () => unknown): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| customValue | 获取表单项值的函数 | () => unknown | - |
获取元素的大小及其相对于视口的位置，等价于 Element.getBoundingClientRect。
<div ref="root" />import { ref } from 'vue';import { useRect } from '@vant/use';export default { setup() { const root = ref(); const rect = useRect(); console.log(rect); // -> 元素的大小及其相对于视口的位置 return { root }; },};function useRect( element: Element | Window | Ref<Element | Window | undefined>): DOMRect;| 参数 | 说明 | 类型 |
|---|---|---|
| width | 宽度 | number |
| height | 高度 | number |
| top | 顶部与视图窗口左上角的距离 | number |
| left | 左侧与视图窗口左上角的距离 | number |
| right | 右侧与视图窗口左上角的距离 | number |
| bottom | 底部与视图窗口左上角的距离 | number |
方便地进行事件绑定，在组件 mounted 和 activated 时绑定事件，unmounted 和 deactivated 时解绑事件。
import { ref } from 'vue';import { useEventListener } from '@vant/use';export default { setup() { // 在 window 上绑定 resize 事件 // 未指定监听对象时，默认会监听 window 的事件 useEventListener('resize', () => { console.log('window resize'); }); // 在 body 元素上绑定 click 事件 useEventListener( 'click', () => { console.log('click body'); }, { target: document.body } ); },};type Options = { target?: EventTarget | Ref<EventTarget>; capture?: boolean; passive?: boolean;};function useEventListener( type: string, listener: EventListener, options?: Options): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 监听的事件类型 | string | - |
| listener | 点击外部时触发的回调函数 | EventListener | - |
| options | 可选的配置项 | Options | - |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| target | 绑定事件的元素 | EventTarget | Ref<EventTarget> | window |
| capture | 是否在事件捕获阶段触发 | boolean | false |
| passive | 设置为 true 时，表示 listener 永远不会调用 preventDefault | boolean | false |
获取页面的可见状态。
import { watch } from 'vue';import { usePageVisibility } from '@vant/use';export default { setup() { const pageVisibility = usePageVisibility(); watch(pageVisibility, (value) => { console.log('visibility: ', value); }); },};type VisibilityState = 'visible' | 'hidden';function usePageVisibility(): Ref<VisibilityState>;| 参数 | 说明 | 类型 |
|---|---|---|
| visibilityState | 页面当前的可见状态，visible 为可见，hidden 为隐藏 | Ref<VisibilityState> |
获取元素最近的可滚动父元素。
<div ref="root" />import { ref, watch } from 'vue';import { useScrollParent, useEventListener } from '@vant/use';export default { setup() { const root = ref(); const scrollParent = useScrollParent(root); useEventListener( 'scroll', () => { console.log('scroll'); }, { target: scrollParent } ); return { root }; },};function useScrollParent( element: Ref<Element | undefined>): Ref<Element | Window | undefined>;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| element | 当前元素 | Ref<Element> | - |
| 参数 | 说明 | 类型 |
|---|---|---|
| scrollParent | 最近的可滚动父元素 | Ref<Element> |
获取浏览器窗口的视口宽度和高度，并在窗口大小变化时自动更新。
import { watch } from 'vue';import { useWindowSize } from '@vant/use';export default { setup() { const { width, height } = useWindowSize(); console.log(width.value); // -> 窗口宽度 console.log(height.value); // -> 窗口高度 watch([width, height], () => { console.log('window resized'); }); },};function useWindowSize(): { width: Ref<number>; height: Ref<number>;};| 参数 | 说明 | 类型 |
|---|---|---|
| width | 浏览器窗口宽度 | Ref<number> |
| height | 浏览器窗口高度 | Ref<number> |
建立父子组件之间的关联关系，进行数据通信和方法调用，基于 provide 和 inject 实现。
在父组件中使用 useChildren 关联子组件:
import { ref } from 'vue';import { useChildren } from '@vant/use';const RELATION_KEY = Symbol('my-relation');export default { setup() { const { linkChildren } = useChildren(RELATION_KEY); const count = ref(0); const add = () => { count.value++; }; // 向子组件提供数据和方法 linkChildren({ add, count }); },};在子组件中使用 useParent 获取父组件提供的数据和方法:
import { useParent } from '@vant/use';export default { setup() { const { parent } = useParent(RELATION_KEY); // 调用父组件提供的数据和方法 if (parent) { parent.add(); console.log(parent.count.value); // -> 1 } },};function useParent<T>( key: string | symbol): { parent?: T; index?: Ref<number>;};function useChildren( key: string | symbol): { children: ComponentPublicInstance[]; linkChildren: (value: any) => void;};| 参数 | 说明 | 类型 |
|---|---|---|
| parent | 父组件提供的值 | any |
| index | 当前组件在父组件的所有子组件中对应的索引位置 | Ref<number> |
| 参数 | 说明 | 类型 |
|---|---|---|
| children | 子组件列表 | ComponentPublicInstance[] |
| linkChildren | 向子组件提供值的方法 | (value: any) => void |
监听点击元素外部的事件。
<div ref="root" />import { ref } from 'vue';import { useClickAway } from '@vant/use';export default { setup() { const root = ref(); useClickAway(root, () => { console.log('click outside!'); }); return { root }; },};通过 eventName 选项可以自定义需要监听的事件类型。
<div ref="root" />import { ref } from 'vue';import { useClickAway } from '@vant/use';export default { setup() { const root = ref(); useClickAway( root, () => { console.log('touch outside!'); }, { eventName: 'touchstart' } ); return { root }; },};type Options = { eventName?: string;};function useClickAway( target: Element | Ref<Element | undefined>, listener: EventListener, options?: Options): void;| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| target | 绑定事件的元素 | Element | Ref<Element> | - |
| listener | 点击外部时触发的回调函数 | EventListener | - |
| options | 可选的配置项 | Options | 见下表 |
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| eventName | 监听的事件类型 | string | click |
本文档已废弃，Vant 提供了更方便的 ConfigProvider 全局配置 组件进行主题配置。基于 Less 变量进行定制的方式将在下个大版本废弃。
Vant 提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以按照本文档进行主题定制。
我们提供了一个基于 Vue Cli 3 的示例工程，仓库地址为 Vant Demo，其中包含了定制主题的基本配置，可以作为参考。
Vant 使用了 Less 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。
下面是所有的基础样式变量，组件的样式变量请参考各个组件的文档，或查看组件源码目录下的 var.less 文件。
// Color Palette@black: #000;@white: #fff;@gray-1: #f7f8fa;@gray-2: #f2f3f5;@gray-3: #ebedf0;@gray-4: #dcdee0;@gray-5: #c8c9cc;@gray-6: #969799;@gray-7: #646566;@gray-8: #323233;@red: #ee0a24;@blue: #1989fa;@orange: #ff976a;@orange-dark: #ed6a0c;@orange-light: #fffbe8;@green: #07c160;// Gradient Colors@gradient-red: linear-gradient(to right, #ff6034, #ee0a24);@gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);// Component Colors@text-color: @gray-8;@active-color: @gray-2;@active-opacity: 0.7;@disabled-opacity: 0.5;@background-color: @gray-1;@background-color-light: #fafafa;@text-link-color: #576b95;// Padding@padding-base: 4px;@padding-xs: @padding-base * 2;@padding-sm: @padding-base * 3;@padding-md: @padding-base * 4;@padding-lg: @padding-base * 6;@padding-xl: @padding-base * 8;// Font@font-size-xs: 10px;@font-size-sm: 12px;@font-size-md: 14px;@font-size-lg: 16px;@font-weight-bold: 500;@line-height-xs: 14px;@line-height-sm: 18px;@line-height-md: 20px;@line-height-lg: 22px;@base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;@price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif;// Animation@animation-duration-base: 0.3s;@animation-duration-fast: 0.2s;@animation-timing-function-enter: ease-out;@animation-timing-function-leave: ease-in;// Border@border-color: @gray-3;@border-width-base: 1px;@border-radius-sm: 2px;@border-radius-md: 4px;@border-radius-lg: 8px;@border-radius-max: 999px;定制主题时，需要引入组件对应的 Less 样式文件，支持按需引入和手动引入两种方式。
在 babel.config.js 中配置按需引入样式源文件，注意 babel 6 不支持按需引入样式，请手动引入样式。
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: { // 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。 lessOptions: { modifyVars: { // 直接覆盖变量 'text-color': '#111', 'border-color': '#eee', // 或者可以通过 less 文件覆盖（文件路径为绝对路径） hack: `true; @import "your-less-file-path.less";`, }, }, }, }, ], }, ],};如果 vue-cli 搭建的项目，可以在 vue.config.js 中进行配置。
// vue.config.jsmodule.exports = { css: { loaderOptions: { less: { // 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。 lessOptions: { modifyVars: { // 直接覆盖变量 'text-color': '#111', 'border-color': '#eee', // 或者可以通过 less 文件覆盖（文件路径为绝对路径） hack: `true; @import "your-less-file-path.less";`, }, }, }, }, },};如果是 vite 项目，可以跳过以上步骤，直接在 vite.config.js 中添加如下配置即可。
// vite.config.jsimport vue from '@vitejs/plugin-vue';import styleImport from 'vite-plugin-style-import';export default { css: { preprocessorOptions: { less: { javascriptEnabled: true, // 覆盖样式变量 modifyVars: { 'text-color': '#111', 'border-color': '#eee', }, }, }, }, resolve: { alias: [{ find: /^~/, replacement: '' }], }, plugins: [ vue(), // 按需引入样式源文件 styleImport({ libs: [ { libraryName: 'vant', esModule: true, resolveStyle: (name) => `vant/es/${name}/style/less`, }, ], }), ],};