Swiper Vue.js 组件

Swiper Vue components will likely to be removed in future versions. It is recommended to migrate to Swiper Element instead.

If you are upgrading from Swiper 9 to Swiper 10, check out Migration Guide to Swiper 10

If you are looking for v9 docs, they are here v9.swiperjs.com

安装

¥Installation

Swiper Vue.js 插件仅通过 NPM 提供，是 Swiper 主库的一部分：

¥Swiper Vue.js plugin is available only via NPM as a part of the main Swiper library:

  npm i swiper

用法

¥Usage

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

¥swiper/vue exports 2 components: Swiper and 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>

By default Swiper Vue uses core version of Swiper (without any additional modules). If you want to use Navigation, Pagination and other modules, you have to install them first:

以下是从 swiper/modules 导入的附加模块列表：

¥Here is the list of additional modules imports from swiper/modules:

Virtual - 虚拟幻灯片模块

¥Virtual - Virtual Slides module
Keyboard - 键盘控制模块

¥Keyboard - Keyboard Control module
Mousewheel - 鼠标滚轮控制模块

¥Mousewheel - Mousewheel Control module
Navigation - 导航模块

¥Navigation - Navigation module
Pagination - 分页模块

¥Pagination - Pagination module
Scrollbar - 滚动条模块

¥Scrollbar - Scrollbar module
Parallax - 视差模块

¥Parallax - Parallax module
FreeMode - 自由模式模块

¥FreeMode - Free Mode module
Grid - 网格模块

¥Grid - Grid module
Manipulation - 幻灯片操作模块（仅适用于核心版本）

¥Manipulation - Slides manipulation module (only for Core version)
Zoom - 缩放模块

¥Zoom - Zoom module
Controller - 控制器模块

¥Controller - Controller module
A11y - 辅助功能模块

¥A11y - Accessibility module
History - 历史导航模块

¥History - History Navigation module
HashNavigation - 哈希导航模块

¥HashNavigation - Hash Navigation module
Autoplay - 自动播放模块

¥Autoplay - Autoplay module
EffectFade - 淡入淡出效果模块

¥EffectFade - Fade Effect module
EffectCube - 立方体效果模块

¥EffectCube - Cube Effect module
EffectFlip - 翻转效果模块

¥EffectFlip - Flip Effect module
EffectCoverflow - Coverflow 效果模块

¥EffectCoverflow - Coverflow Effect module
EffectCards - 卡片效果模块

¥EffectCards - Cards Effect module
EffectCreative - 创意效果模块

¥EffectCreative - Creative Effect module
Thumbs - 缩略图模块

¥Thumbs - Thumbs module

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

Note, Swiper Vue component will create required elements for Navigation, Pagination and Scrollbar if you pass these params without specifying its elements (e.g. without navigation.nextEl, pagination.el, etc.)

样式

¥Styles

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

¥Swiper package contains different sets of CSS, Less and SCSS styles:

swiper/css - 仅核心 Swiper 样式

¥swiper/css - only core Swiper styles
swiper/css/bundle - 所有 Swiper 样式，包括所有模块样式（例如导航、分页等）

¥swiper/css/bundle - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)

模块样式（如果已导入 bundle 样式，则无需添加）：

¥Modules styles (not required if you already imported bundle styles):

swiper/css/a11y - A11y 模块所需样式

¥swiper/css/a11y - styles required for A11y module
swiper/css/autoplay - 自动播放模块所需样式

¥swiper/css/autoplay - styles required for Autoplay module
swiper/css/controller - 控制器模块所需样式

¥swiper/css/controller - styles required for Controller module
swiper/css/effect-cards - 卡片效果模块所需样式

¥swiper/css/effect-cards - styles required for Cards Effect module
swiper/css/effect-coverflow - Coverflow 效果模块所需样式

¥swiper/css/effect-coverflow - styles required for Coverflow Effect module
swiper/css/effect-creative - 创意效果模块所需样式

¥swiper/css/effect-creative - styles required for Creative Effect module
swiper/css/effect-cube - 立方体效果模块所需样式

¥swiper/css/effect-cube - styles required for Cube Effect module
swiper/css/effect-fade - 所需样式淡入淡出效果模块

¥swiper/css/effect-fade - styles required for Fade Effect module
swiper/css/effect-flip - 翻转效果模块所需样式

¥swiper/css/effect-flip - styles required for Flip Effect module
swiper/css/free-mode - 自由模式模块所需样式

¥swiper/css/free-mode - styles required for Free Mode module
swiper/css/grid - 网格模块所需样式

¥swiper/css/grid - styles required for Grid module
swiper/css/hash-navigation - 哈希导航模块所需样式

¥swiper/css/hash-navigation - styles required for Hash Navigation module
swiper/css/history - 历史记录模块所需样式

¥swiper/css/history - styles required for History module
swiper/css/keyboard - 键盘模块所需样式

¥swiper/css/keyboard - styles required for Keyboard module
swiper/css/manipulation - 操作模块所需样式

¥swiper/css/manipulation - styles required for Manipulation module
swiper/css/mousewheel - 鼠标滚轮模块所需样式

¥swiper/css/mousewheel - styles required for Mousewheel module
swiper/css/navigation - 导航模块所需样式

¥swiper/css/navigation - styles required for Navigation module
swiper/css/pagination - 分页模块所需样式

¥swiper/css/pagination - styles required for Pagination module
swiper/css/parallax - 视差模块所需样式

¥swiper/css/parallax - styles required for Parallax module
swiper/css/scrollbar - 滚动条模块所需样式

¥swiper/css/scrollbar - styles required for Scrollbar module
swiper/css/thumbs - 缩略图模块所需样式

¥swiper/css/thumbs - styles required for Thumbs module
swiper/css/virtual - 虚拟模块所需样式

¥swiper/css/virtual - styles required for Virtual module
swiper/css/zoom - 缩放模块所需样式

¥swiper/css/zoom - styles required for Zoom module

对于 Less 样式，请在导入路径中将 css 替换为 less，例如：

¥For Less styles replace css with less in imports paths, e.g.:

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

对于 SCSS 样式，请在导入路径中将 css 替换为 scss，例如：

¥For SCSS styles replace css with scss in imports paths, e.g.:

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

Swiper 属性

¥Swiper props

Swiper Vue.js 组件接收所有 Swiper parameters 作为组件 props，以及一些额外的 props：

¥Swiper Vue.js component receive all Swiper parameters as component props, plus some extra props:

属性	类型	默认	描述
`tag`	`string`	`'div'`	主 Swiper 容器 HTML 元素标签
`wrapperTag`	`string`	`'div'`	Swiper 封装器 HTML 元素标签

Swiper 事件

¥Swiper events

Swiper 组件支持所有 Swiper events 类型，包括附加的 swiper 事件，该事件会尽快返回 Swiper 实例。例如：

¥Swiper component supports all Swiper events, including additional swiper event that returns swiper instance as soon as possible. For example:

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

SwiperSlide 属性

¥SwiperSlide props

属性	类型	默认	描述
`tag`	`string`	`'div'`	Swiper Slide HTML 元素标签
`zoom`	`boolean`	`false`	启用缩放模式所需的额外封装器
`virtualIndex`	`number`		实际的滑动条索引。虚拟幻灯片需要设置

SwiperSlide 插槽属性

¥SwiperSlide slot props

SwiperSlide 组件具有以下 slot props：

¥SwiperSlide component has the following slot props:

isActive - 当前幻灯片为活动幻灯片时为 true

¥isActive - true when current slide is active
isPrev - 当当前幻灯片是活动幻灯片中的上一张时，为 true

¥isPrev - true when current slide is the previous from active
isNext - 当当前幻灯片是活动幻灯片中的下一张

¥isNext - true when current slide is the next from active
isVisible - 当当前幻灯片可见时，为 true（必须启用 watchSlidesProgress Swiper 参数）

¥isVisible - true when current slide is visible (watchSlidesProgress Swiper parameter must be enabled)
isDuplicate - 当前幻灯片为重复幻灯片时（启用 loop 模式时）例如：

¥isDuplicate - true when current slide is a duplicate slide (when loop mode enabled) For example:

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

useSwiper

Swiper Vue 提供 useSwiper 钩子，可轻松获取 Swiper 内部组件中的 Swiper 实例：

¥Swiper Vue provides useSwiper hook to easliy get the Swiper instance in components inside of 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 插槽属性中的数据相同）的另一个钩子。

¥useSwiperSlide is one more hook for components inside of Swiper slides to get the slide data (same data as in SwiperSlide slot props)

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

插槽

¥Slots

Swiper Vue.js 组件使用 "slots" 进行内容分发。有 4 个可用插槽

¥Swiper Vue.js component uses "slots" for content distribution. There are 4 slots available

container-start - 元素将添加到 swiper-container 的开头

¥container-start - element will be added to the beginning of swiper-container
container-end（默认） - 元素将添加到 swiper-container 的末尾

¥container-end (default) - element will be added to the end of swiper-container
wrapper-start - 元素将添加到 swiper-wrapper 的开头

¥wrapper-start - element will be added to the beginning of swiper-wrapper
wrapper-end - 元素将添加到 swiper-wrapper 的末尾

¥wrapper-end - element will be added to the end of swiper-wrapper

例如：

¥For example:

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

将渲染为：

¥Will be rendered as:

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

虚拟幻灯片

¥Virtual Slides

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

¥Virtual Slides rendering here is fully handled by Vue.js and not required anything except setting :virtual="true" property and setting virtualIndex on slides:

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

控制器

¥Controller

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

¥Controller requires to pass one Swiper instance to another:

<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 互相控制时），应该如下所示：

¥For two-way control (when both Swipers control each other) it should be like this:

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

缩略图

¥Thumbs

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

¥Same as with controller we need to store thumbs instance and pass it to main gallery:

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

效果

¥Effects

可用效果如下：

¥The following effects are available:

淡入淡出

¥Fade
立方体

¥Cube
Coverflow
翻转

¥Flip
卡片

¥Cards
创意

¥Creative

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

¥To use effects you have to import and install them first (as all other modules).

你可以找到正在运行的 effect demos here。

¥You can find running effect demos here.

完全淡入淡出效果示例

¥Full Fade Effect Example

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

下一步？

¥What next?

正如你所见，将 Swiper 集成到你的网站或应用中非常容易。接下来的步骤如下：

¥As you see it is really easy to integrate Swiper into your website or app. So here are your next steps:

前往 API Documentation 了解更多关于 Swiper API 及其控制方法的信息。

¥Go to API Documentation to learn more about all Swiper API and how to control it.
查看可用的 Demos。

¥Look at available Demos.
如果你对 Swiper 有任何疑问，请在 StackOverflow 或 Swiper Discussions 中提问。

¥If you have questions about Swiper ask them in StackOverflow or Swiper Discussions.
如果你发现 GitHub 存在 bug，请创建 issue。

¥Create issue on GitHub if you found a bug.
如果你需要支持，我们有一个 Swiper Patrons 的私有 Discord 支持聊天室。

¥If you are looking for support, we have a private Discord support chat room for Swiper Patrons.