codecamp

Vant3 Swipe 轮播

介绍

用于循环播放一组图片或内容。

实例演示

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册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 事件

在每一页轮播结束后,会触发 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>

API

Swipe Props

参数 说明 类型 默认值
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

Swipe Events

事件名 说明 回调参数
change 每一页轮播结束后触发 index, 当前页的索引

SwipeItem Events

事件名 说明 回调参数
click 点击时触发 event: MouseEvent

Swipe 方法

通过 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();

SwipeToOptions 格式

名称 说明 类型
immediate 是否跳过动画 boolean

Swipe Slots

名称 说明 参数
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) -

常见问题

滑动轮播时为什么触发了 click 事件?

这种情况通常是由于项目中引入了 fastclick 库导致的。fastclick 的原理是通过 Touch 事件模拟出 click 事件,而 Swipe 内部默认会阻止 touchmove 事件冒泡,干扰了 fastclick 的判断,导致出现这个问题。

将 Swipe 组件的 stop-propagation 属性设置为 false 即可避免该问题。

在桌面端无法操作组件?

参见桌面端适配

Swipe 组件功能太少,无法实现复杂效果?

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();


Vant3 Sticky 粘性布局
Vant3 Tag 标签
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

Vant3 废弃内容

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }