0.5.1

Swipe 轮播 ​

介绍 ​

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

DHdesign 中，Swipe 默认指示器尺寸、间距和数字样式对齐移动端设计规范；指示器激活态跟随 DHdesign 当前主题色，未激活态使用主题边框色并以 50% 透明度区分。

引入 ​

通过以下方式来引入组件。

js
import { createApp } from 'vue';
import { Swipe, SwipeItem } from '@szhn/dh-design-mobile';

const app = createApp();
app.use(Swipe);
app.use(SwipeItem);

代码演示 ​

通栏轮播 ​

通栏轮播支持柱形、圆形、数字三种指示器样式，并区分内部与外部指示器位置。图片场景可使用 indicator-color="#fff" 提升对比度；页面内纯色场景默认跟随 DHdesign 主题色。

html
<van-swipe class="dh-swipe--indicator-line" :autoplay="3000" indicator-color="#fff">
  <van-swipe-item>
    <img src="banner.png" alt="轮播图" />
  </van-swipe-item>
</van-swipe>

<van-swipe class="dh-swipe--indicator-dot dh-swipe--indicator-outside" :autoplay="3000">
  <van-swipe-item>
    <img src="banner.png" alt="轮播图" />
  </van-swipe-item>
</van-swipe>

<van-swipe :show-indicators="false">
  <van-swipe-item>
    <img src="banner.png" alt="轮播图" />
  </van-swipe-item>
  <template #indicator="{ active, total }">
    <div class="dh-swipe__number dh-swipe__number--bottom">{{ active + 1 }}/{{ total }}</div>
  </template>
</van-swipe>

左右箭头 ​

通过 indicator 插槽配合 prev / next 实例方法，可实现设计稿中的圆形箭头切换。

html
<van-swipe ref="swipeRef" class="dh-swipe--with-arrows" :show-indicators="false">
  <van-swipe-item>
    <img src="banner.png" alt="轮播图" />
  </van-swipe-item>
  <template #indicator>
    <button type="button" class="dh-swipe__arrow dh-swipe__arrow--prev" @click="swipeRef?.prev()">
      <van-icon name="arrow-left" />
    </button>
    <button type="button" class="dh-swipe__arrow dh-swipe__arrow--next" @click="swipeRef?.next()">
      <van-icon name="arrow" />
    </button>
  </template>
</van-swipe>

卡片轮播 ​

通过 width 属性设置单个滑块宽度，可实现并列或重叠卡片轮播。设计稿卡片尺寸为 283×159，圆角 12px，卡片间距 12px。

html
<van-swipe
  class="dh-swipe--indicator-line dh-swipe--indicator-outside"
  :loop="false"
  :width="295"
>
  <van-swipe-item>
    <img class="card-image" src="card.png" alt="卡片" />
  </van-swipe-item>
  <van-swipe-item>
    <img class="card-image" src="card.png" alt="卡片" />
  </van-swipe-item>
</van-swipe>

懒加载 ​

当 Swipe 中含有图片时，可以通过 lazy-render 属性来开启懒加载模式。在懒加载模式下，只会渲染当前页和下一页。

html
<van-swipe :autoplay="3000" lazy-render>
  <van-swipe-item v-for="image in images" :key="image">
    <img :src="image" />
  </van-swipe-item>
</van-swipe>
js
export default {
  setup() {
    const images = [
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    ];
    return { images };
  },
};

监听 change 事件 ​

在每一页轮播结束后，会触发 change 事件。

html
<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>
js
import { showToast } from '@szhn/dh-design-mobile';

export default {
  setup() {
    const onChange = (index) => showToast('当前 Swipe 索引：' + index);
    return { onChange };
  },
};

纵向滚动 ​

设置 vertical 属性后滑块会纵向排列，此时需要指定滑块容器的高度。

html
<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 属性设置单个滑块的高度。

html
<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 插槽可以自定义指示器的样式。

html
<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>

API ​

Swipe Props ​

参数说明类型默认值
autoplay自动轮播间隔，单位为 msnumber | string-
duration动画时长，单位为 msnumber | string500
initial-swipe初始位置索引值number | string0
width滑块宽度，单位为 pxnumber | stringauto
height滑块高度，单位为 pxnumber | stringauto
loop是否开启循环播放booleantrue
show-indicators是否显示指示器booleantrue
vertical是否为纵向滚动booleanfalse
touchable是否可以通过手势滑动booleantrue
stop-propagation是否阻止滑动事件冒泡booleantrue
lazy-render是否延迟渲染未展示的轮播booleanfalse
indicator-color指示器颜色string#1989fa

Swipe Events ​

事件名说明回调参数
change每一页轮播结束后触发index: number
drag-start当用户开始拖动轮播组件时触发
drag-end当用户结束拖动轮播组件时触发

SwipeItem Events ​

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

Swipe 方法 ​

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

方法名说明参数返回值
prev切换到上一轮播--
next切换到下一轮播--
swipeTo切换到指定位置index: number, options: SwipeToOptions-
resize外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘--

类型定义 ​

组件导出以下类型定义：

ts
import type { SwipeProps, SwipeInstance, SwipeToOptions } from '@szhn/dh-design-mobile';

SwipeInstance 是组件实例的类型，用法如下：

ts
import { ref } from 'vue';
import type { SwipeInstance } from '@szhn/dh-design-mobile';

const swipeRef = ref<SwipeInstance>();

swipeRef.value?.next();

SwipeToOptions 格式 ​

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

Swipe Slots ​

名称说明参数
default轮播内容-
indicator自定义指示器

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-swipe-indicator-size6px轮播指示器的尺寸
--van-swipe-indicator-marginvar(--van-padding-sm)轮播指示器的外边距
--van-swipe-indicator-active-opacity1激活指示器的透明度
--van-swipe-indicator-inactive-opacity0.3未激活指示器的透明度
--van-swipe-indicator-active-backgroundvar(--van-primary-color)激活指示器的背景色
--van-swipe-indicator-inactive-backgroundvar(--van-border-color)未激活指示器的背景色

常见问题 ​

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

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

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

在桌面端无法操作组件？ ​

参见桌面端适配。

Swipe 组件功能太少，无法实现复杂效果？ ​

dh-design-mobile 中的 Swipe 组件是比较轻量的，因此功能也比较基础。如果需要更复杂的轮播效果，推荐使用社区里一些优质的轮播库，比如 vue-awesome-swiper。

组件从隐藏状态切换到显示状态时，无法正确渲染？ ​

Swipe 组件在挂载时，会获取自身的宽度，并计算出轮播图的位置。如果组件一开始处于隐藏状态，则获取到的宽度永远为 0，因此无法正确计算位置。

解决方法 ​

方法一，如果是使用 v-show 来控制组件展示的，则替换为 v-if 即可解决此问题：

html
<!-- Before -->
<van-swipe v-show="show" />
<!-- After -->
<van-swipe v-if="show" />

方法二，调用组件的 resize 方法来主动触发重绘：

html
<van-swipe v-show="show" ref="swipe" />
js
this.$refs.swipe.resize();
Swipe