Vue中使用Swiper的完整指南

1. 前言

Swiper 是一款功能强大的轮播库，广泛应用于移动端和桌面端的滑动交互场景。在 Vue 项目中集成 Swiper 可以快速实现精美的轮播图、滑动菜单、图片画廊等功能。本文将从安装配置开始，逐步讲解如何在 Vue 2 和 Vue 3 中使用 Swiper，以及常见功能的实现与优化技巧。

2. 版本选择与安装

Swiper 有多个版本，不同版本的用法和兼容性存在差异，需根据 Vue 版本选择合适的 Swiper 版本：

2.1. Vue 3 中安装 Swiper

Swiper 7+ 对 Vue 3 提供了原生支持，安装步骤如下：

# 安装核心包
npm install swiper
# 或
yarn add swiper

Swiper 7+ 将核心功能与样式分离，无需额外安装插件，直接引入即可使用。

2.2. Vue 2 中安装 Swiper

Vue 2 需使用 vue-awesome-swiper 插件（基于 Swiper 5/6）：

# 安装 Swiper 5 和配套插件
npm install swiper@5 vue-awesome-swiper@4 --save
# 或
yarn add swiper@5 vue-awesome-swiper@4

安装完成后，需在 main.js 中全局注册：

import Vue from 'vue';
import VueAwesomeSwiper from 'vue-awesome-swiper';
import'swiper/css/swiper.css'; // 引入 Swiper 样式

Vue.use(VueAwesomeSwiper);

3. Vue 3 中使用Swiper

Swiper 7+ 对 Vue 3 采用组件化设计，使用方式简洁直观，以下是基础轮播图的实现：

3.1. 基础用法

<template>
  <div class="swiper-container">
    <!-- Swiper 容器 -->
    <Swiper
      :modules="modules"
      :slides-per-view="1"  <!-- 每页显示1个滑块 -->
      :space-between="30"   <!-- 滑块间距30px -->
      :loop="true"          <!-- 循环播放 -->
      :pagination="{ clickable: true }"  <!-- 分页器可点击 -->
      :navigation="true"    <!-- 显示前后按钮 -->
      :autoplay="{ delay: 3000 }"  <!-- 自动播放，延迟3秒 -->
    >
      <!-- 轮播项 -->
      <SwiperSlide v-for="(item, index) in images" :key="index">
        <img :src="item" class="slide-image" alt="轮播图" />
      </SwiperSlide>

      <!-- 分页器（可选，需配合 pagination 配置） -->
      <template #pagination>
        <div class="swiper-pagination"></div>
      </template>

      <!-- 导航按钮（可选，需配合 navigation 配置） -->
      <template #navigation>
        <div class="swiper-button-prev"></div>
        <div class="swiper-button-next"></div>
      </template>
    </Swiper>
  </div>
</template>

<script setup>
import { onMounted, ref } from 'vue';
// 引入 Swiper 核心组件和样式
import { Swiper, SwiperSlide } from'swiper/vue';
import'swiper/css';
// 引入所需模块（按需导入）
import { Autoplay, Pagination, Navigation } from'swiper/modules';

// 注册使用的模块
const modules = [Autoplay, Pagination, Navigation];

// 轮播图数据
const images = [
  '/images/slide1.jpg',
  '/images/slide2.jpg',
  '/images/slide3.jpg'
];
</script>

<style scoped>
.swiper-container {
  width: 800px;
  max-width: 100%;
  height: 400px;
  margin: 0 auto;
}

.slide-image {
  width: 100%;
  height: 100%;
  object-fit: cover;  /* 图片自适应容器，保持比例 */
}
</style>

3.2. 配置解析

• modules：Swiper 7+ 采用模块化设计，需手动导入并注册所需功能（如自动播放、分页器），减少打包体积。
• slides-per-view：控制每页显示的滑块数量，支持数字（如 3）或 'auto'（自动适应）。
• loop：设置为 true 开启循环播放，轮播到最后一页后自动回到第一页。
• pagination：配置分页器，clickable: true 允许点击分页按钮切换滑块。
• navigation：设置为 true 显示前后导航按钮，也可自定义按钮样式。
• autoplay：配置自动播放，delay 为播放间隔（毫秒），默认 3000。

4. Vue 2 中使用 Swiper

在 Vue 2 中，通过 vue-awesome-swiper 插件使用 Swiper，语法略有不同：

<template>
  <div class="swiper-container">
    <swiper
      :options="swiperOptions"
      ref="mySwiper"
    >
      <!-- 轮播项 -->
      <swiper-slide v-for="(item, index) in images" :key="index">
        <img :src="item" class="slide-image" alt="轮播图" />
      </swiper-slide>

      <!-- 分页器 -->
      <div class="swiper-pagination" slot="pagination"></div>

      <!-- 导航按钮 -->
      <div class="swiper-button-prev" slot="button-prev"></div>
      <div class="swiper-button-next" slot="button-next"></div>
    </swiper>
  </div>
</template>

<script>
export default {
  data() {
    return {
      images: [
        '/images/slide1.jpg',
        '/images/slide2.jpg',
        '/images/slide3.jpg'
      ],
      // Swiper 配置项
      swiperOptions: {
        slidesPerView: 1,
        spaceBetween: 30,
        loop: true,
        pagination: {
          el: '.swiper-pagination',
          clickable: true
        },
        navigation: {
          nextEl: '.swiper-button-next',
          prevEl: '.swiper-button-prev'
        },
        autoplay: {
          delay: 3000
        }
      }
    };
  },
  computed: {
    // 获取 Swiper 实例
    swiper() {
      return this.$refs.mySwiper.swiper;
    }
  },
  mounted() {
    // 可在 mounted 中调用 Swiper 实例方法
    console.log('Swiper 实例:', this.swiper);
  }
};
</script>

<style scoped>
/* 样式与 Vue 3 示例一致 */
.swiper-container {
  width: 800px;
  max-width: 100%;
  height: 400px;
  margin: 0 auto;
}

.slide-image {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
</style>

5. 高级功能实现

下面是一些自定义和配置的实现：

5.1. 自定义导航按钮和分页器样式

Swiper 默认样式可能不符合项目需求，可通过 CSS 自定义：

/* 自定义分页器样式 */
.swiper-pagination-bullet {
  width: 12px;
  height: 12px;
  background: #fff;
  opacity: 0.5;
  margin: 0 6px;
}

.swiper-pagination-bullet-active {
  opacity: 1;
  background: #409eff; /* 激活状态颜色 */
}

/* 自定义导航按钮 */
.swiper-button-prev,
.swiper-button-next {
  width: 40px;
  height: 40px;
  background: rgba(0, 0, 0, 0.3);
  border-radius: 50%;
  color: #fff;
  /* 隐藏默认箭头，使用自定义图标 */
  &::after {
    font-size: 18px;
    font-weight: bold;
  }
}

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

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

5.2. 实现垂直轮播

通过 direction: 'vertical' 配置垂直轮播，适用于移动端上下滑动场景：

<!-- Vue 3 示例 -->
<Swiper
  :modules="modules"
  :direction="'vertical'"  <!-- 垂直方向 -->
  :slides-per-view="1"
  :space-between="20"
  :loop="true"
>
  <!-- 轮播项 -->
</Swiper>

5.3. 响应式配置

根据屏幕宽度动态调整轮播参数（如不同尺寸显示不同数量的滑块）：

<!-- Vue 3 示例 -->
<Swiper
  :modules="modules"
  :slides-per-view="1"
  :space-between="10"
  :responsive="{
    640: {  // 屏幕宽度 ≥ 640px 时
      slidesPerView: 2,
      spaceBetween: 20
    },
    1024: {  // 屏幕宽度 ≥ 1024px 时
      slidesPerView: 3,
      spaceBetween: 30
    }
  }"
>
  <!-- 轮播项 -->
</Swiper>

5.4. 监听轮播事件

Swiper 提供了丰富的事件（如滑动开始、滑动结束、切换等），可通过 @事件名 监听：

<!-- Vue 3 示例 -->
<Swiper
  :modules="modules"
  @slideChange="onSlideChange"  <!-- 滑块切换时触发 -->
  @swiper="onSwiper"  <!-- Swiper 初始化完成时触发 -->
>
  <!-- 轮播项 -->
</Swiper>

<script setup>
const onSwiper = (swiper) => {
  console.log('Swiper 初始化完成', swiper);
};

const onSlideChange = (swiper) => {
  console.log('当前滑块索引', swiper.activeIndex);
};
</script>

6. 常见问题与解决方案

6.1. 轮播图高度自适应

当轮播图高度不固定时，可通过 autoHeight: true 让容器高度自适应当前滑块高度：

<Swiper
  :autoHeight="true"  <!-- 高度自适应 -->
  <!-- 其他配置 -->
>

6.2. 解决图片加载完成后轮播错位

图片异步加载可能导致 Swiper 初始化时尺寸计算错误，需在图片加载完成后重新初始化：

<script setup>
import { ref } from 'vue';
import { Swiper, SwiperSlide } from'swiper/vue';

const swiperRef = ref(null);
const images = [/* 图片地址 */];
const imageLoaded = ref(0);

// 图片加载完成后计数
const handleImageLoad = () => {
  imageLoaded.value++;
  // 所有图片加载完成后，重新初始化 Swiper
  if (imageLoaded.value === images.length && swiperRef.value) {
    swiperRef.value.swiper.update();
  }
};
</script>

<template>
  <Swiper ref="swiperRef">
    <SwiperSlide v-for="(item, index) in images" :key="index">
      <img :src="item" @load="handleImageLoad" alt="轮播图" />
    </SwiperSlide>
  </Swiper>
</template>

6.3. 禁止移动端触摸滑动

在某些场景下（如仅需要自动播放，不允许用户滑动），可禁用触摸交互：

<Swiper
  :allowTouchMove="false"  <!-- 禁止触摸滑动 -->
  :autoplay="{ delay: 3000 }"
  <!-- 其他配置 -->
>

6.4. Card视图居中放大

在某些场景下，需要居中的比其余的放大一些，可以设置swiper-slide-active类名：

.swiper-slide-active {
  transform: scale(1.2) !important;
}

7. 总结

在实际开发中，建议根据项目需求选择合适的 Swiper 版本，按需导入模块以减少打包体积，并通过自定义样式和事件监听实现个性化交互。

本次分享就到这儿啦，我是鹏多多，如果您看了觉得有帮助，欢迎评论，关注，点赞，转发，我们下次见~

往期文章

• vue中ref的详解以及react的ref对比
• css使用aspect-ratio制作4:3和9:16和1:1等等比例布局
• Web前端页面开发阿拉伯语种适配指南
• flutter-使用extended_image操作图片的加载和状态处理以及缓存和下载
• flutter-制作可缩放底部弹出抽屉评论区效果
• flutter-实现Tabs吸顶的PageView效果
• Vue2全家桶+Element搭建的PC端在线音乐网站
• 助你上手Vue3全家桶之Vue3教程
• 超详细！vue组件通信的10种方式
• 超详细！Vuex手把手教程
• 使用nvm管理node.js版本以及更换npm淘宝镜像源
• vue中利用.env文件存储全局环境变量，以及配置vue启动和打包命令

个人主页

• CSDN
• GitHub
• 掘金
• 简书
• 博客园