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 - 導覽模組
Pagination - 分頁模組
Scrollbar - 滾動條模組
Parallax - 視差模組
FreeMode - 自由模式模組
Grid - 格線模組
Manipulation - 幻燈片操作模組 (僅適用於核心版本)
Zoom - 縮放模組
Controller - 控制器模組
A11y - 無障礙模組
History - 歷史導覽模組
HashNavigation - Hash 導覽模組
Autoplay - 自動播放模組
EffectFade - 淡入淡出效果模組
EffectCube - 立方體效果模組
EffectFlip - 翻轉效果模組
EffectCoverflow - Coverflow 效果模組
EffectCards - 卡片效果模組
EffectCreative - Creative 效果模組
Thumbs - 縮圖模組

<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 - Coverflow 效果模組所需的樣式
swiper/css/effect-creative - Creative 效果模組所需的樣式
swiper/css/effect-cube - 立方體效果模組所需的樣式
swiper/css/effect-fade - 淡入淡出效果模組所需的樣式
swiper/css/effect-flip - 翻轉效果模組所需的樣式
swiper/css/free-mode - 自由模式模組所需的樣式
swiper/css/grid - 格線模組所需的樣式
swiper/css/hash-navigation - Hash 導覽模組所需的樣式
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 樣式，請在匯入路徑中將 css 替換為 less，例如

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

對於 SCSS 樣式，請在匯入路徑中將 css 替換為 scss，例如

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

Swiper props

Swiper Vue.js 組件會接收所有 Swiper 參數作為組件 props，外加一些額外的 props

Prop	類型	預設值	描述
`tag`	`字串`	`'div'`	主要的 Swiper 容器 HTML 元素標籤
`wrapperTag`	`字串`	`'div'`	字串

Swiper 事件

Swiper 組件支援所有 Swiper 事件，包括額外的 swiper 事件，該事件會盡快傳回 swiper 執行個體。例如

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

SwiperSlide props

Prop	類型	預設值	描述
`tag`	`字串`	`'div'`	字串
`zoom`	`布林值`	`false`	啟用縮放模式所需的額外包裝器
`virtualIndex`	`數字`		實際的 swiper 幻燈片索引。必須為虛擬幻燈片設定

SwiperSlide 插槽 props

SwiperSlide 組件具有以下插槽 props

isActive - 當目前幻燈片為活動狀態時為 true
isPrev - 當目前幻燈片為活動狀態的前一張幻燈片時為 true
isNext - 當目前幻燈片為活動狀態的下一張幻燈片時為 true
isVisible - 當目前幻燈片可見時為 true (必須啟用 watchSlidesProgress Swiper 參數)
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 hook，以便在 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 是另一個 hook，用於 Swiper 幻燈片內的組件以取得幻燈片資料 (與 SwiperSlide 插槽 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>

插槽

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
翻轉
卡片
Creative

若要使用效果，您必須先匯入並安裝它們 (與所有其他模組一樣)。

您可以在這裡找到正在執行的效果示範。

完整的淡入淡出效果範例

<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 上建立 issue。
如果您正在尋求支援，我們為 Swiper Patrons 提供私人 Discord 支援聊天室。

在 GitHub 上編輯此頁面