vue3 使用swiper轮播组件

1. 本地环境信息参考

node版本：

nodejs : v18.20.4
npm : 10.7.0

vue版本

  "dependencies": {
    "vue": "^3.2.13",
    ...
  }

2. 安装swiper依赖

执行命令：

npm i swiper

安装后，查看工程中的package.json文件，新增了swiper依赖（默认最新版）：

  "dependencies": {
    "swiper": "^11.1.14",
    "vue": "^3.2.13",
    ...
  }

3. 轮播图默认效果

模拟轮播图需求说明：

1、多张图片，可自动播放
2、有指示器
3、有左右导航按钮（向前、向后）

图片导入工程

代码实现 & 释义：

导入swiper组件：Swiper容器；SwiperSlide子项容器

import {Swiper, SwiperSlide} from 'swiper/vue';

导入module：因为swiper将不同功能进行组件化拆分，使其更灵活化，我们使用具体的功能，只需导入相应的module即可。
导航（左右按钮功能）、Pagination（分页指示器功能）、A11y （辅助功能模块，旨在提高网站或应用的可访问性）、Autoplay（自动播放功能）

import {Navigation, Pagination, A11y, Autoplay} from 'swiper/modules';
const modules = [Navigation, Pagination, A11y, Autoplay]

导入相关样式，按功能导入相应的css：

import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/autoplay';

template中使用Swiper、SwiperSlide组件，并配置module、属性、事件等

<swiper
      class="swiper-container"
      :slides-per-view="1"
      :space-between="0"
      @swiper="onSwiper"
      @slideChange="onSlideChange"
      :modules="modules"
      :pagination="{ clickable: true }"
      :autoplay="{
      delay: 2000,
      disableOnInteraction: false,
      }"
      navigation
      :loop="true"
  >
    <swiper-slide>
      <img class="item" src="@/assets/banner/0.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/1.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/2.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/3.jpg"/>
    </swiper-slide>
  </swiper>

:slides-per-view: 这个属性设置了每个滑块（slide）的可见数量。在这里，设置为 1 表示每次只显示一个滑块。
:space-between：这个属性设置了滑块之间的间距。在这里，设置为 0 表示滑块之间没有间距。
@swiper="onSwiper"：这个属性是一个事件监听器，当 Swiper 初始化完成时会触发名为 "onSwiper" 的方法。
@slideChange="onSlideChange"：这个属性是另一个事件监听器，当滑块切换时会触发名为 "onSlideChange" 的方法。
:modules：这个属性指定了 Swiper 实例所使用的模块。通过这个属性，可以配置 Swiper 实例使用的各种功能模块【此处配置了导航、指示器、自动播放等】。
:pagination：这个属性配置了 Swiper 的分页指示器，设置为可点击，用户可以通过点击分页器来切换到不同的滑块。
:autoplay：这个属性配置了自动播放功能，设置了播放延迟为 2000 毫秒（2秒），并且当用户交互时不停止自动播放。
navigation：这个属性开启了 Swiper 的导航按钮，通常会显示左右箭头或其他导航元素，用于用户手动导航滑块。
:loop：这个属性设置了 Swiper 是否循环播放滑块内容，即当滑动到最后一个滑块时是否自动切换到第一个滑块。设置为 true 表示开启循环播放。

定义swiper实例，用于后续swiper操作，例如：跳转下一页、暂停自动播放等等

const swiperInstance = ref<typeof Swiper | null>(null);

事件方法定义

//初始化swiper后，为swiperInstance赋值
const onSwiper = (swiper: typeof Swiper) => {
  swiperInstance.value = swiper;
};
//监听slide滑块更改事件回调
const onSlideChange = () => {
  console.log('slide change');
};

实现效果

完整代码参考

<template>
  <swiper
      class="swiper-container"
      :slides-per-view="1"
      :space-between="0"
      @swiper="onSwiper"
      @slideChange="onSlideChange"
      :modules="modules"
      :pagination="{ clickable: true }"
      :autoplay="{
      delay: 2000,
      disableOnInteraction: false,
      }"
      navigation
      :loop="true"
  >
    <swiper-slide>
      <img class="item" src="@/assets/banner/0.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/1.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/2.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/3.jpg"/>
    </swiper-slide>
  </swiper>
</template>
<script lang="ts" setup>
import {ref} from 'vue';
import {Swiper, SwiperSlide} from 'swiper/vue';
import {Navigation, Pagination, A11y, Autoplay} from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/autoplay';

const modules = [Navigation, Pagination, A11y, Autoplay]
const swiperInstance = ref<typeof Swiper | null>(null);

const onSwiper = (swiper: typeof Swiper) => {
  swiperInstance.value = swiper;
};
const onSlideChange = () => {
  console.log('slide change');
};
</script>

<style scoped>
.swiper-container {
  background-color: white;
}

.item {
  width: 100%;
  height: auto;
}
</style>

4. 优化自动播放效果

如果用户鼠标移入swiper，应该让swiper暂停滑动，方便用户查看当前滑块的具体信息；如果鼠标滑出swiper，应该继续自动滑动。

实现：

swiper ui组件监听鼠标移入、移出事件：

@mouseenter="pauseSwiper"
@mouseleave="resumeSwiper"

script代码中，实现对应的方法：

const pauseSwiper = () => {
  if (swiperInstance.value) {
    swiperInstance.value.autoplay.stop();
  }
};
const resumeSwiper = () => {
  if (swiperInstance.value) {
    swiperInstance.value.autoplay.start();
  }
};

5. 自定义左右导航按钮

多数情况下，需要参考项目的UI设计稿，调整左右导航按钮效果/样式。

此处，我们模拟修改下，使用两张图片作为左右导航按钮。

script中，先实现左右切换滑块的功能：

const goPrev = ()=> {
  if (swiperInstance.value) {
    swiperInstance.value.slidePrev();
  }
};
const goNext = () => {
  if (swiperInstance.value) {
    swiperInstance.value.slideNext();
  }
};

swiper ui组件上不再配置默认的navigation属性。
导入按钮图片：

布局中新增左右按钮，并设置其样式：

  <div class="custom-navigation">
      <img src="@/assets/img_pre.png" class="custom-swiper-button-prev" @click="goPrev">
      <img src="@/assets/img_next.png" class="custom-swiper-button-next" @click="goNext">
  </div>

.custom-swiper-button-prev, .custom-swiper-button-next {
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  z-index: 10;
  color: #FFFFFF;
  font-size: 20px;
  width: 50px;
  height: 50px;
}

.custom-swiper-button-next {
  right: 20px;
}

.custom-swiper-button-prev {
  left: 20px;
}

自定义导航按钮效果：

完整代码

<template>
  <swiper
      class="swiper-container"
      :slides-per-view="1"
      :space-between="0"
      @swiper="onSwiper"
      @slideChange="onSlideChange"
      :modules="modules"
      :pagination="{ clickable: true }"
      :autoplay="{
      delay: 2000,
      disableOnInteraction: false,
      }"
      :loop="true"
      @mouseenter="pauseSwiper"
      @mouseleave="resumeSwiper"
  >
    <swiper-slide>
      <img class="item" src="@/assets/banner/0.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/1.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/2.jpg"/>
    </swiper-slide>
    <swiper-slide>
      <img class="item" src="@/assets/banner/3.jpg"/>
    </swiper-slide>
  </swiper>
  <div class="custom-navigation">
      <img src="@/assets/img_pre.png" class="custom-swiper-button-prev" @click="goPrev">
      <img src="@/assets/img_next.png" class="custom-swiper-button-next" @click="goNext">
  </div>
</template>
<script lang="ts" setup>
import {ref} from 'vue';
import {Swiper, SwiperSlide} from 'swiper/vue';
import {Navigation, Pagination, A11y, Autoplay} from 'swiper/modules';
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/autoplay';

const modules = [Navigation, Pagination, A11y, Autoplay]
const swiperInstance = ref<typeof Swiper | null>(null);

const onSwiper = (swiper: typeof Swiper) => {
  swiperInstance.value = swiper;
};
const onSlideChange = () => {
  console.log('slide change');
};

const pauseSwiper = () => {
  if (swiperInstance.value) {
    swiperInstance.value.autoplay.stop();
  }
};
const resumeSwiper = () => {
  if (swiperInstance.value) {
    swiperInstance.value.autoplay.start();
  }
};
const goPrev = ()=> {
  if (swiperInstance.value) {
    swiperInstance.value.slidePrev();
  }
};
const goNext = () => {
  if (swiperInstance.value) {
    swiperInstance.value.slideNext();
  }
};
</script>

<style scoped>
.swiper-container {
  background-color: white;
}

.item {
  width: 100%;
  height: auto;
}

.custom-swiper-button-prev, .custom-swiper-button-next {
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  z-index: 10;
  color: #FFFFFF;
  font-size: 20px;
  width: 50px;
  height: 50px;
}

.custom-swiper-button-next {
  right: 20px;
}

.custom-swiper-button-prev {
  left: 20px;
}
</style>