Vue 中 vue-awesome-swiper的使用笔记（适配 Vue2/Vue3）

vue-awesome-swiper 是基于 Swiper.js 封装的 Vue 轮播组件，支持 Vue2 和 Vue3 版本（注意版本适配），总结了完整的安装、配置、基础使用及其他功能教程。

一、版本适配（关键！避免踩坑）

Vue 版本	vue-awesome-swiper 版本	Swiper 版本	安装命令
Vue3	^5.0.0	^8.x	npm i vue-awesome-swiper@5 swiper@8
Vue2	^4.1.1	^6.x	npm i vue-awesome-swiper@4 swiper@6

注意：Vue3 版本的 vue-awesome-swiper 不再全局注册，需手动导入组件；Swiper 8+ 需手动引入 CSS 文件。

二、基础安装（以 Vue3 + Vite 为例）

1. 安装依赖

# Vue3 + Swiper8
npm install vue-awesome-swiper@5 swiper@8 --save

# Vue2 + Swiper6
npm install vue-awesome-swiper@4 swiper@6 --save

2. 全局引入（可选，Vue3 推荐局部引入）

Vue3 全局引入

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
import 'swiper/css' // 核心样式
import 'swiper/css/pagination' // 分页器样式
import 'swiper/css/navigation' // 导航按钮样式

const app = createApp(App)
app.component('Swiper', Swiper)
app.component('SwiperSlide', SwiperSlide)
app.mount('#app')

Vue2 全局引入

// main.js
import Vue from 'vue'
import VueAwesomeSwiper from 'vue-awesome-swiper'
import 'swiper/css/swiper.css' // Vue2 对应 Swiper6 的 CSS 路径

Vue.use(VueAwesomeSwiper)

三、基础使用（Vue3 局部引入，推荐）

1. 基础轮播示例（含分页、自动播放）

<template>
  <!-- Swiper 容器 -->
  <swiper 
    class="my-swiper" 
    :options="swiperOptions"
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <!-- 轮播项 -->
    <swiper-slide>
      <div class="slide-item" style="background: #f00;">Slide 1</div>
    </swiper-slide>
    <swiper-slide>
      <div class="slide-item" style="background: #0f0;">Slide 2</div>
    </swiper-slide>
    <swiper-slide>
      <div class="slide-item" style="background: #00f;">Slide 3</div>
    </swiper-slide>

    <!-- 分页器（可选，需引入对应 CSS） -->
    <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>
    <!-- 滚动条（可选） -->
    <div class="swiper-scrollbar" slot="scrollbar"></div>
  </swiper>
</template>

<script setup>
import { ref } from 'vue'
// 局部引入组件和样式（Vue3 推荐）
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
import 'swiper/css' // 核心样式
import 'swiper/css/pagination' // 分页器样式
import 'swiper/css/navigation' // 导航按钮样式

// Swiper 配置项（对应 Swiper8 配置）
const swiperOptions = ref({
  // 基础配置
  direction: 'horizontal', // 方向：horizontal/vertical
  loop: true, // 循环播放
  autoplay: {
    delay: 3000, // 自动播放间隔（毫秒）
    disableOnInteraction: false, // 点击后是否继续自动播放
  },
  speed: 500, // 切换速度（毫秒）
  // 分页器配置
  pagination: {
    el: '.swiper-pagination', // 分页器元素选择器
    clickable: true, // 分页器是否可点击
  },
  // 导航按钮配置
  navigation: {
    nextEl: '.swiper-button-next', // 下一页按钮
    prevEl: '.swiper-button-prev', // 上一页按钮
  },
  // 滚动条配置
  scrollbar: {
    el: '.swiper-scrollbar',
    draggable: true, // 是否可拖动
  },
})

// 获取 Swiper 实例
const onSwiper = (swiper) => {
  console.log('Swiper 实例：', swiper)
}

// 监听轮播切换事件
const onSlideChange = () => {
  console.log('轮播切换了')
}
</script>

<style scoped>
/* 轮播容器样式 */
.my-swiper {
  width: 100%;
  height: 300px; /* 必须设置高度，否则轮播不显示 */
}

/* 轮播项样式 */
.slide-item {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  color: #fff;
  font-size: 24px;
}

/* 解决 scoped 样式穿透（分页器/导航按钮样式） */
:deep(.swiper-pagination-bullet-active) {
  background: #fff;
}
:deep(.swiper-button-prev),
:deep(.swiper-button-next) {
  color: #fff;
}
</style>

2. Vue2 基础使用示例

<template>
  <swiper :options="swiperOptions" class="my-swiper">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    <div class="swiper-pagination" slot="pagination"></div>
  </swiper>
</template>

<script>
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
import 'swiper/css/swiper.css'

export default {
  components: { Swiper, SwiperSlide },
  data() {
    return {
      swiperOptions: {
        loop: true,
        autoplay: {
          delay: 3000
        },
        pagination: {
          el: '.swiper-pagination',
          clickable: true
        }
      }
    }
  },
  methods: {
    // 可选：通过 ref 获取 Swiper 实例
    getSwiperInstance() {
      console.log(this.$refs.mySwiper.swiper)
    }
  }
}
</script>

<style>
.my-swiper {
  width: 100%;
  height: 300px;
}
</style>

四、核心配置项（常用）

配置项	类型	说明	默认值
loop	Boolean	是否循环播放	false
autoplay	Object	自动播放配置（delay/stopOnLastSlide 等）	false
direction	String	滑动方向：horizontal/vertical	horizontal
speed	Number	切换动画速度（毫秒）	300
pagination	Object	分页器配置（el/clickable/type 等）	-
navigation	Object	导航按钮配置（nextEl/prevEl）	-
scrollbar	Object	滚动条配置（el/draggable）	-
slidesPerView	Number	同时显示的轮播项数量	1
spaceBetween	Number	轮播项之间的间距（像素）	0
centeredSlides	Boolean	居中显示当前轮播项	false
mousewheel	Boolean	是否支持鼠标滚轮控制	false

分页器类型扩展

// 分页器改为进度条样式
pagination: {
  el: '.swiper-pagination',
  type: 'progressbar' // 可选：bullets（默认圆点）、fraction（分数）、progressbar（进度条）
}

五、高级功能

1. 动态加载轮播数据

<template>
  <swiper :options="swiperOptions" class="my-swiper">
    <swiper-slide v-for="(item, index) in slideList" :key="index">
      <img :src="item.imgUrl" alt="轮播图" style="width: 100%; height: 100%; object-fit: cover;">
    </swiper-slide>
    <div class="swiper-pagination" slot="pagination"></div>
  </swiper>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
import 'swiper/css'
import 'swiper/css/pagination'

const slideList = ref([])
const swiperOptions = ref({
  loop: true,
  autoplay: { delay: 3000 },
  pagination: { el: '.swiper-pagination', clickable: true }
})

// 模拟接口请求加载数据
const fetchSlideData = () => {
  setTimeout(() => {
    slideList.value = [
      { imgUrl: 'https://picsum.photos/800/400?1' },
      { imgUrl: 'https://picsum.photos/800/400?2' },
      { imgUrl: 'https://picsum.photos/800/400?3' }
    ]
  }, 500)
}

onMounted(() => {
  fetchSlideData()
})
</script>

2. 手动控制轮播（通过 Swiper 实例）

<template>
  <div>
    <swiper 
      ref="swiperRef" 
      :options="swiperOptions" 
      class="my-swiper"
    >
      <swiper-slide>Slide 1</swiper-slide>
      <swiper-slide>Slide 2</swiper-slide>
      <swiper-slide>Slide 3</swiper-slide>
    </swiper>
    <!-- 手动控制按钮 -->
    <button @click="prevSlide">上一页</button>
    <button @click="nextSlide">下一页</button>
    <button @click="toggleAutoplay">切换自动播放</button>
  </div>
</template>

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

const swiperRef = ref(null)
const swiperOptions = ref({
  loop: true,
  autoplay: { delay: 3000 }
})

// 上一页
const prevSlide = () => {
  swiperRef.value.swiper.slidePrev()
}

// 下一页
const nextSlide = () => {
  swiperRef.value.swiper.slideNext()
}

// 切换自动播放
const toggleAutoplay = () => {
  const swiper = swiperRef.value.swiper
  if (swiper.autoplay.running) {
    swiper.autoplay.stop() // 停止自动播放
  } else {
    swiper.autoplay.start() // 开始自动播放
  }
}
</script>

3. 多列轮播（slidesPerView）

<template>
  <swiper :options="swiperOptions" class="my-swiper">
    <swiper-slide v-for="i in 8" :key="i">
      <div class="slide-item">{{ i }}</div>
    </swiper-slide>
  </swiper>
</template>

<script setup>
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
import 'swiper/css'

const swiperOptions = ref({
  slidesPerView: 3, // 同时显示3个轮播项
  spaceBetween: 10, // 间距10px
  loop: true,
  pagination: { el: '.swiper-pagination', clickable: true }
})
</script>

<style scoped>
.my-swiper {
  width: 100%;
  height: 200px;
}
.slide-item {
  width: 100%;
  height: 100%;
  background: #eee;
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>

4. 垂直轮播

js

const swiperOptions = ref({
  direction: 'vertical', // 垂直方向
  loop: true,
  autoplay: { delay: 2000 },
  pagination: { el: '.swiper-pagination', clickable: true }
})

六、常见问题解决

1. 轮播容器高度问题

• 必须给 .swiper 容器设置明确高度（如 height: 300px），否则轮播项无法显示；

• 响应式高度可通过 vw/百分比 或监听窗口大小调整：

  js

  import { onMounted, watch } from 'vue'
  onMounted(() => {
    window.addEventListener('resize', () => {
      swiperRef.value.swiper.update() // 窗口变化时更新 Swiper 布局
    })
  })

2. 样式穿透问题（scoped）

Vue3 中使用 :deep()，Vue2 中使用 /deep/ 或 ::v-deep，否则无法修改分页器 / 导航按钮样式：

/* Vue3 */
:deep(.swiper-pagination-bullet) {
  background: #ccc;
}

/* Vue2 */
/deep/ .swiper-pagination-bullet-active {
  background: #ff0;
}

3. 自动播放失效

• 检查 autoplay 配置是否为对象（而非布尔值）；
• 设置 disableOnInteraction: false，避免点击后停止自动播放；
• 循环播放 loop: true 需开启，否则最后一页会停止。

4. Vue3 中 Swiper 实例获取不到

• 确保 ref 绑定到 <swiper> 组件上；
• 实例需在 onMounted 后获取（组件已挂载）。

七、总结

1. 版本适配 ：Vue3 用 vue-awesome-swiper@5 + Swiper8，Vue2 用 @4 + Swiper6；
2. 核心步骤 ：安装依赖 → 引入组件 / CSS → 配置 options → 编写轮播结构；
3. 关键配置 ：loop（循环）、autoplay（自动播放）、pagination（分页）、navigation（导航）；
4. 高级用法：动态数据、手动控制、多列 / 垂直轮播，需结合 Swiper 实例操作；
5. 避坑点：设置容器高度、样式穿透、自动播放配置。