Swiper Vue.js 组件

Swiper Vue 组件很可能在未来的版本中被移除。建议改用 Swiper Element。

如果您要从 Swiper 9 升级到 Swiper 10，请查看 Swiper 10 迁移指南

如果您正在寻找 v9 文档，它们在这里 v9.swiperjs.com

安装

Swiper Vue.js 插件仅通过 NPM 作为主 Swiper 库的一部分提供

  npm i swiper

用法

swiper/vue 导出 2 个组件：Swiper 和 SwiperSlide

<template>
  <swiper
    :slides-per-view="3"
    :space-between="50"
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  // Import Swiper Vue.js components
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // Import Swiper styles
  import 'swiper/css';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      const onSwiper = (swiper) => {
        console.log(swiper);
      };
      const onSlideChange = () => {
        console.log('slide change');
      };
      return {
        onSwiper,
        onSlideChange,
      };
    },
  };
</script>

默认情况下，Swiper Vue 使用 Swiper 的核心版本（没有任何其他模块）。如果您想使用导航、分页和其他模块，您必须先安装它们

以下是来自 swiper/modules 的其他模块导入列表

Virtual - 虚拟幻灯片模块
Keyboard - 键盘控制模块
Mousewheel - 鼠标滚轮控制模块
Navigation - 导航模块
分页 - 分页模块
滚动条 - 滚动条模块
视差 - 视差模块
自由模式 - 自由模式模块
网格 - 网格模块
操作 - 幻灯片操作模块（仅适用于核心版本）
缩放 - 缩放模块
控制器 - 控制器模块
无障碍 - 无障碍模块
历史 - 历史导航模块
哈希导航 - 哈希导航模块
自动播放 - 自动播放模块
淡入淡出效果 - 淡入淡出效果模块
立方体效果 - 立方体效果模块
翻转效果 - 翻转效果模块
封面流效果 - 封面流效果模块
卡片效果 - 卡片效果模块
创意效果 - 创意效果模块
缩略图 - 缩略图模块

<template>
  <swiper
    :modules="modules"
    :slides-per-view="3"
    :space-between="50"
    navigation
    :pagination="{ clickable: true }"
    :scrollbar="{ draggable: true }"
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  // import Swiper core and required modules
  import { Navigation, Pagination, Scrollbar, A11y } from 'swiper/modules';

  // Import Swiper Vue.js components
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // Import Swiper styles
  import 'swiper/css';
  import 'swiper/css/navigation';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';

  // Import Swiper styles
  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      const onSwiper = (swiper) => {
        console.log(swiper);
      };
      const onSlideChange = () => {
        console.log('slide change');
      };
      return {
        onSwiper,
        onSlideChange,
        modules: [Navigation, Pagination, Scrollbar, A11y],
      };
    },
  };
</script>

请注意，如果您在未指定其元素（例如，未指定 navigation.nextEl、pagination.el 等）的情况下传递这些参数，Swiper Vue 组件将为导航、分页和滚动条创建所需的元素。

样式

Swiper 包含不同的 CSS、Less 和 SCSS 样式集

swiper/css - 仅核心 Swiper 样式
swiper/css/bundle - 所有 Swiper 样式，包括所有模块样式（如导航、分页等）

模块样式（如果您已导入捆绑样式，则不需要）

swiper/css/a11y - A11y 模块所需的样式
swiper/css/autoplay - 自动播放模块所需的样式
swiper/css/controller - 控制器模块所需的样式
swiper/css/effect-cards - 卡片效果模块所需的样式
swiper/css/effect-coverflow - 封面流效果模块所需的样式
swiper/css/effect-creative - 创意效果模块所需的样式
swiper/css/effect-cube - 立方体效果模块所需的样式
swiper/css/effect-fade - 淡入淡出效果模块所需的样式
swiper/css/effect-flip - 翻转效果模块所需的样式
swiper/css/free-mode - 自由模式模块所需的样式
swiper/css/grid - 网格模块所需的样式
swiper/css/hash-navigation - 哈希导航模块所需的样式
swiper/css/history - 历史模块所需的样式
swiper/css/keyboard - 键盘模块所需的样式
swiper/css/manipulation - 操作模块所需的样式
swiper/css/mousewheel - 鼠标滚轮模块所需的样式
swiper/css/navigation - 导航模块所需的样式
swiper/css/pagination - 分页模块所需的样式
swiper/css/parallax - 视差模块所需的样式
swiper/css/scrollbar - 滚动条模块所需的样式
swiper/css/thumbs - 缩略图模块所需的样式
swiper/css/virtual - 虚拟模块所需的样式
swiper/css/zoom - 缩放模块所需的样式

对于 Less 样式，在导入路径中用 less 替换 css，例如

import 'swiper/less';
import 'swiper/less/navigation';
import 'swiper/less/pagination';

对于 SCSS 样式，在导入路径中用 scss 替换 css，例如

import 'swiper/scss';
import 'swiper/scss/navigation';
import 'swiper/scss/pagination';

Swiper 属性

Swiper Vue.js 组件接收所有 Swiper 参数作为组件属性，以及一些额外的属性

属性	类型	默认值	说明
`tag`	`字符串`	`'div'`	Swiper 容器 HTML 元素标记
`wrapperTag`	`字符串`	`'div'`	Swiper 包装 HTML 元素标记

Swiper 事件

Swiper 组件支持所有 Swiper 事件，包括返回 swiper 实例的附加 swiper 事件。例如

<swiper @swiper="..." @slideChange="..." @reachEnd="..." ...></swiper>

SwiperSlide 属性

属性	类型	默认值	说明
`tag`	`字符串`	`'div'`	Swiper 幻灯片 HTML 元素标记
`zoom`	`布尔值`	`false`	启用缩放模式所需的附加包装
`virtualIndex`	`数字`		实际的 swiper 幻灯片索引。需要为虚拟幻灯片设置

SwiperSlide 插槽属性

SwiperSlide 组件具有以下插槽属性

isActive - 当前幻灯片处于活动状态时为 true
isPrev - 当前幻灯片为活动幻灯片的上一个时为 true
isNext - 当前幻灯片为活动幻灯片的下一个时为 true
isVisible - 当前幻灯片可见时为 true（必须启用 Swiper 参数 watchSlidesProgress）
isDuplicate - 当当前幻灯片是重复幻灯片时为 true（当启用loop模式时）。例如

<swiper>
  <swiper-slide v-slot="{ isActive }">
    <div>Current slide is {{ isActive ? 'active' : 'not active' }}</div>
  </swiper-slide>
</swiper>

useSwiper

Swiper Vue 提供 useSwiper 钩子，以便在 Swiper 内的组件中轻松获取 Swiper 实例

<!-- some-inner-component.vue -->
<template>
  <button @click="swiper.slideNext()">Slide to the next slide</button>
</template>
<script>
  import { useSwiper } from 'swiper/vue';

  export default {
    setup() {
      const swiper = useSwiper();

      return {
        swiper,
      };
    },
  };
</script>

useSwiperSlide

useSwiperSlide 是 Swiper 幻灯片内组件的另一个钩子，用于获取幻灯片数据（与 SwiperSlide 插槽属性中的数据相同）

<!-- some-inner-component.vue -->
<template>
  <p>Current slide is {{swiperSlide.isActive ? 'active' : 'not active'}}</p>
</template>
<script>
  import { useSwiperSlide } from 'swiper/vue';

  export default {
    setup() {
      const swiperSlide = useSwiperSlide();

      return {
        swiperSlide,
      };
    },
  };
</script>

插槽

Swiper Vue.js 组件使用“插槽”来分发内容。有 4 个可用的插槽

container-start - 元素将被添加到 swiper-container 的开头
container-end（默认） - 元素将被添加到 swiper-container 的末尾
wrapper-start - 元素将被添加到 swiper-wrapper 的开头
wrapper-end - 元素将被添加到 swiper-wrapper 的末尾

例如

<swiper>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <template v-slot:container-start><span>Container start</span></template>
  <template v-slot:container-end><span>Container end</span></template>
  <template v-slot:wrapper-start><span>Wrapper start</span></template>
  <template v-slot:wrapper-end><span>Wrapper end</span></template>
</swiper>

将被渲染为

<div class="swiper">
  <span>Container start</span>
  <div class="swiper-wrapper">
    <span>Wrapper start</span>
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <span>Wrapper end</span>
  </div>
  <span>Container end</span>
</div>

虚拟幻灯片

此处的虚拟幻灯片渲染完全由 Vue.js 处理，除了设置 :virtual="true" 属性和在幻灯片上设置 virtualIndex 之外，不需要任何其他操作

<template>
  <swiper :modules="[Virtual]" :slides-per-view="3" :space-between="50" virtual>
    <swiper-slide
      v-for="(slideContent, index) in slides"
      :key="index"
      :virtualIndex="index"
      >{{slideContent}}</swiper-slide
    >
  </swiper>
</template>
<script>
  import { Virtual } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },

    setup() {
      // Create array with 1000 slides
      const slides = Array.from({ length: 1000 }).map(
        (el, index) => `Slide ${index + 1}`
      );
      return {
        slides,
        Virtual,
      };
    },
  };
</script>

控制器

控制器需要将一个 Swiper 实例传递给另一个

<template>
  <!-- Main Swiper -> pass controlled swiper instance -->
  <swiper
    :modules="[Controller]"
    :controller="{ control: controlledSwiper }"
    ...
  >
    ...
  </swiper>

  <!-- Controlled Swiper -> store swiper instance -->
  <swiper :modules="[Controller]" @swiper="setControlledSwiper" ...>
    ...
  </swiper>
</template>
<script>
  import { ref } from 'vue';
  import { Controller } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      const controlledSwiper = ref(null);
      const setControlledSwiper = (swiper) => {
        controlledSwiper.value = swiper;
      };
      return {
        Controller,
        controlledSwiper,
        setControlledSwiper,
      };
    },
  };
</script>

对于双向控制（当两个 Swiper 相互控制时），它应该是这样

<template>
  <swiper
    :modules="[Controller]"
    @swiper="setFirstSwiper"
    :controller="{ control: secondSwiper }"
    ...
  >
    ...
  </swiper>
  <swiper
    :modules="[Controller]"
    @swiper="setSecondSwiper"
    :controller="{ control: firstSwiper }"
    ...
  >
    ...
  </swiper>
</template>
<script>
  import { ref } from 'vue';
  import { Controller } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      const firstSwiper = ref(null);
      const secondSwiper = ref(null);
      const setFirstSwiper = (swiper) => {
        firstSwiper.value = swiper;
      };
      const setSecondSwiper = (swiper) => {
        secondSwiper.value = swiper;
      };

      return {
        Controller,
        firstSwiper,
        secondSwiper,
        setFirstSwiper,
        setSecondSwiper,
      };
    },
  };
</script>

缩略图

与控制器相同，我们需要存储缩略图实例并将其传递给主画廊

<template>
  <!-- Main Swiper -> pass thumbs swiper instance -->
  <swiper :modules="[Thumbs]" :thumbs="{ swiper: thumbsSwiper }" ...>
    ...
  </swiper>

  <!-- Thumbs Swiper -> store swiper instance -->
  <!-- It is also required to set watchSlidesProgress prop -->
  <swiper
    :modules="[Thumbs]"
    watch-slides-progress
    @swiper="setThumbsSwiper"
    ...
  >
    ...
  </swiper>
</template>
<script>
  import { ref } from 'vue';
  import { Thumbs } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      const thumbsSwiper = ref(null);
      const setThumbsSwiper = (swiper) => {
        thumbsSwiper.value = swiper;
      };
      return {
        Thumbs,
        thumbsSwiper,
        setThumbsSwiper,
      };
    },
  };
</script>

效果

以下效果可用

淡入淡出
立方体
Coverflow
翻转
卡片
创意

要使用效果，你必须先导入并安装它们（与所有其他模块一样）。

你可以找到运行的效果演示。

全屏淡入淡出效果示例

<template>
  <swiper :modules="[EffectFade]" effect="fade">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  import 'swiper/css';
  import 'swiper/css/effect-fade';

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    setup() {
      return {
        EffectFade,
      };
    },
  };
</script>

接下来是什么？

正如你所看到的，将 Swiper 集成到你的网站或应用程序中非常容易。因此，以下是你的下一步

转到 API 文档以了解有关所有 Swiper API 以及如何控制它的更多信息。
查看可用的演示。
如果你对 Swiper 有疑问，可以在 StackOverflow 或 Swiper 讨论中提出。
如果你发现了一个错误，请在 GitHub 上创建问题。
如果你正在寻求支持，我们为 Swiper 赞助人提供了一个私人的 Discord 支持聊天室。

在 GitHub 上编辑此页面