vant3的option写法示例
现在vant官方文档对应vue3的全部是CompositionApi写法,对于一些刚上手,还在用optionsApi的人不友好。现在将一部分组件的文档写法改为optionsApi写法
安装
参考官方文档安装即可:快速上手
注意:
如果你用的是这个按需引入的方法
那么可能会遇到报错
解决方法:Cannot use ‘import.meta‘ outside a module Vant按需引入报错
安装低版本的
npm i unplugin-vue-components@0.22.0
组件使用
我只是将官方示例写法进行修改,效果还是看官方文档
swipe 轮播
基础用法
每个 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 {
data() {
return {
images:[
'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
]
}
}
};
监听 change 事件
在每一页轮播结束后,会触发 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 {
methods: {
onChange(index) {
Toast('当前 Swipe 索引:' + index)
}
}
};
纵向滚动
设置 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, total }">
<div class="custom-indicator">{{ active + 1 }}/{{ total }}</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>
Popup 弹出层
基础用法
通过 v-model:show 控制弹出层是否展示。不要忘记引入van-cell
<van-cell is-link @click="showPopup">展示弹出层</van-cell>
<van-popup v-model:show="show">内容</van-popup>
export default {
data() {
return {
show: false
};
},
methods: {
showPopup(index) {
this.show = true;
}
}
};
弹出位置
通过 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" />
Picker 选择器
基础用法
选项配置
Picker 组件通过 columns 属性配置选项数据,columns 是一个包含字符串或对象的数组。
顶部栏
顶部栏包含标题、确认按钮和取消按钮,点击确认按钮触发 confirm 事件,点击取消按钮触发 cancel 事件。
<van-picker
title="标题"
:columns="columns"
@confirm="onConfirm"
@cancel="onCancel"
@change="onChange"
/>
import { Toast } from 'vant';
export default {
data() {
return {
columns: ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华']
};
},
methods: {
onConfirm(value, index) {
Toast(`当前值: ${value}, 当前索引: ${index}`);
},
onChange(value, index) {
Toast(`当前值: ${value}, 当前索引: ${index}`);
},
onCancel() {
Toast('取消');
}
}
};
默认选中项
单列选择时,可以通过 default-index 属性设置初始选中项的索引。
<van-picker title="标题" :columns="columns" :default-index="2" />
多列选择
columns 属性可以通过对象数组的形式配置多列选择,对象中可以配置选项数据、初始选中项等,详细格式见下方表格。
<van-picker title="标题" :columns="columns" />
export default {
data() {
return {
columns: [
// 第一列
{
values: ['周一', '周二', '周三', '周四', '周五'],
defaultIndex: 2,
},
// 第二列
{
values: ['上午', '下午', '晚上'],
defaultIndex: 1,
},
]
};
}
};
级联选择
使用 columns 的 children 字段可以实现选项级联的效果。如果级联层级较多,推荐使用 Cascader 级联选项组件。
<van-picker title="标题" :columns="columns" />
export default {
data() {
return {
columns: [
{
text: '浙江',
children: [
{
text: '杭州',
children: [{ text: '西湖区' }, { text: '余杭区' }],
},
{
text: '温州',
children: [{ text: '鹿城区' }, { text: '瓯海区' }],
},
],
},
{
text: '福建',
children: [
{
text: '福州',
children: [{ text: '鼓楼区' }, { text: '台江区' }],
},
{
text: '厦门',
children: [{ text: '思明区' }, { text: '海沧区' }],
},
],
},
]
};
},
};
级联选择的数据嵌套深度需要保持一致,如果部分选项没有子选项,可以使用空字符串进行占位。
禁用选项
选项可以为对象结构,通过设置 disabled 来禁用该选项。
<van-picker :columns="columns" />
export default {
data() {
return {
columns: [
{ text: '杭州', disabled: true },
{ text: '宁波' },
{ text: '温州' },
]
};
},
};
动态设置选项
通过 Picker 上的实例方法可以更灵活地控制选择器,比如使用 setColumnValues 方法实现多列联动。
<van-picker ref="picker" :columns="columns" @change="onChange" />
export default {
data() {
return {
cities: {
浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
福建: ['福州', '厦门', '莆田', '三明', '泉州'],
}
}
},
computed: {
columns() {
return [
{
values: Object.keys(this.cities)
},
{ values: this.cities['浙江'] },
]
}
},
methods: {
onChange(values) {
this.$refs.picker.setColumnValues(1, this.cities[values[0]]);
}
}
};
加载状态
若选择器数据是异步获取的,可以通过 loading 属性显示加载提示。
<van-picker :columns="columns" :loading="loading" />
export default {
data() {
return {
columns: [],
loading: true
}
},
created() {
setTimeout(() => {
this.columns = ['选项'];
this.loading = false;
}, 1000);
},
};
搭配弹出层使用
在实际场景中,Picker 通常作为用于辅助表单填写,可以搭配 Popup 和 Field 实现该效果。
<van-field
v-model="value"
is-link
readonly
label="城市"
placeholder="选择城市"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
export default {
data() {
return {
columns: ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华'],
result: '',
showPicker: false
}
},
methods: {
onConfirm(value) {
this.result = value;
this.showPicker = false;
}
}
};
自定义 Columns 的结构
<van-picker
:title="标题"
:columns="columns"
:columns-field-names="customFieldName"
/>
export default {
data() {
return {
columns: [
{
cityName: '浙江',
cities: [
{
cityName: '杭州',
cities: [{ cityName: '西湖区' }, { cityName: '余杭区' }],
},
{
cityName: '温州',
cities: [{ cityName: '鹿城区' }, { cityName: '瓯海区' }],
},
],
},
{
cityName: '福建',
cities: [
{
cityName: '福州',
cities: [{ cityName: '鼓楼区' }, { cityName: '台江区' }],
},
{
cityName: '厦门',
cities: [{ cityName: '思明区' }, { cityName: '海沧区' }],
},
],
},
],
customFieldName: {
text: 'cityName',
children: 'cities',
}
}
},
};
Stepper 步进器
基础用法
通过 v-model 绑定输入值,可以通过 change 事件监听到输入值的变化。
<van-stepper v-model="value" />
export default {
data() {
return {
value:1
}
}
};
步长设置
通过 step 属性设置每次点击增加或减少按钮时变化的值,默认为 1。
<van-stepper v-model="value" step="2" />
限制输入范围
通过 min 和 max 属性限制输入值的范围。
<van-stepper v-model="value" min="5" max="8" />
限制输入整数
设置 integer 属性后,输入框将限制只能输入整数。
<van-stepper v-model="value" integer />
禁用状态
通过设置 disabled 属性来禁用步进器,禁用状态下无法点击按钮或修改输入框。
<van-stepper v-model="value" disabled />
禁用输入框
通过设置 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 { Toast } from 'vant';
export default {
data() {
return {
value: 1
}
},
methods: {
beforeChange(value) {
Toast.loading({ forbidClick: true });
return new Promise((resolve) => {
setTimeout(() => {
Toast.clear();
// 在 resolve 函数中返回 true 或 false
resolve(true);
}, 500);
});
}
}
};
圆角风格
将 theme 设置为 round 来展示圆角风格的步进器。
<van-stepper v-model="value" theme="round" button-size="22" disable-input />
Field 输入框
基础用法
可以通过 v-model 双向绑定输入框的值,通过 placeholder 设置占位提示文字。
<!-- 可以使用 CellGroup 作为容器 -->
<van-cell-group inset>
<van-field v-model="value" label="文本" placeholder="请输入用户名" />
</van-cell-group>
export default {
data() {
return {
value: ''
}
}
};
自定义类型
根据 type 属性定义不同类型的输入框,默认值为 text。
<van-cell-group inset>
<!-- 输入任意文本 -->
<van-field v-model="text" label="文本" />
<!-- 输入手机号,调起手机号键盘 -->
<van-field v-model="tel" type="tel" label="手机号" />
<!-- 允许输入正整数,调起纯数字键盘 -->
<van-field v-model="digit" type="digit" label="整数" />
<!-- 允许输入数字,调起带符号的纯数字键盘 -->
<van-field v-model="number" type="number" label="数字" />
<!-- 输入密码 -->
<van-field v-model="pass(删除)word" type="pass(删除)word" label="密码" />
</van-cell-group>
export default {
data() {
return {
value1: '',
value2: '',
tel : '',
text : '',
digit : '',
number : '',
pass(删除)word : ''
}
}
};
禁用输入框
通过 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="value1"
label="文本"
left-icon="smile-o"
right-icon="warning-o"
placeholder="显示图标"
/>
<van-field
v-model="value2"
clearable
label="文本"
left-icon="music-o"
placeholder="显示清除图标"
/>
</van-cell-group>
export default {
data() {
return {
value1: '',
value2: '123'
}
}
};
错误提示
设置 required 属性表示这是一个必填项,可以配合 error 或 error-message 属性显示对应的错误提示。
<van-cell-group 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="value1"
label="文本"
:formatter="formatter"
placeholder="在输入时执行格式化"
/>
<van-field
v-model="value2"
label="文本"
:formatter="formatter"
format-trigger="onBlur"
placeholder="在失焦时执行格式化"
/>
</van-cell-group>
export default {
data() {
return {
value1: '',
value2: ''
}
},
methods: {
formatter(value) {
return value.replace(/\d/g, '')
}
}
};
高度自适应
对于 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>
Tab 标签页
基础用法
通过 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>
export default {
data() {
return {
active: 0
}
},
};
通过名称匹配
在标签指定 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>
export default {
data() {
return {
activeName: 'a'
}
},
};
标签栏滚动
标签数量超过 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 { Toast } from 'vant';
export default {
data() {
return {
active: 0
}
},
methods: {
onClickTab({ title }) {
Toast(title)
}
}
};
粘性布局
通过 sticky 属性可以开启粘性布局,粘性布局下,标签页滚动到顶部时会自动吸顶。
<van-tabs v-model:active="active" sticky>
<van-tab v-for="index in 4" :title="'选项 ' + index">
内容 {{ index }}
</van-tab>
</van-tabs>
Tips: 如果页面顶部有其他内容,可以通过 offset-top 属性设置吸顶时与顶部的距离。
收缩布局
通过 shrink 属性可以开启收缩布局,开启后,所有的标签会向左侧收缩对齐。
<van-tabs v-model:active="active" shrink>
<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>
export default {
data() {
return {
active: 0
}
},
methods: {
beforeChange(index) {
// 返回 false 表示阻止此次切换
if (index === 1) {
return false;
}
// 返回 Promise 来执行异步逻辑
return new Promise((resolve) => {
// 在 resolve 函数中返回 true 或 false
resolve(index !== 3);
});
}
}
};
Tips: 通过手势滑动不会触发 before-change 属性。
Tabbar 标签栏
基础用法
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>
export default {
data() {
return {
active: 0
}
}
};
通过名称匹配
在标签指定 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>
export default {
data() {
return {
active: 'home'
}
}
};
徽标提示
设置 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>
export default {
data() {
return {
active: 0,
icon: {
active: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png',
inactive:
'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png',
}
}
},
};
自定义颜色
通过 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 { Toast } from 'vant';
export default {
data() {
return {
active: 0
}
},
methods: {
onChange(index) {
Toast(`标签 ${index}`)
}
}
};
路由模式
标签栏支持路由模式,用于搭配 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>