從 ion-slides 遷移至 Swiper.js

正在尋找 ion-slides 嗎？

ion-slides 已在 v6.0.0 中被棄用，並在 v7.0.0 中移除。我們建議直接使用 Swiper.js 函式庫。遷移過程詳述如下。

如果您需要現代化的觸控滑動元件，我們建議使用 Swiper.js。本指南將介紹如何在您的 Ionic Framework 應用程式中設定 Swiper for Vue。它還將介紹您可能需要從 ion-slides 移動到官方 Swiper Vue 整合的任何遷移資訊。

注意

Swiper 的 Vue 元件將在 Swiper 的未來版本中移除，並以 Swiper Element 作為替代。但是，本指南說明如何遷移到 Vue 元件，因為它在撰寫本文時提供了最穩定的體驗。

使用 Swiper 的 Vue 元件並**非**在 Ionic Framework 中使用 Swiper.js 的必要條件。

開始使用

首先，更新至最新版本的 Ionic

npm install @ionic/vue@latest @ionic/vue-router@latest

我們建議升級至 Vue CLI 5 以獲得更好的 Swiper 相容性

vue upgrade --next

完成後，在您的專案中安裝 Swiper 相依性

npm install swiper@latest

滑動樣式

接下來，我們需要匯入基本的 Swiper 樣式。我們還將匯入 Ionic 提供的樣式，這將允許我們使用與 ion-slides 相同的 CSS 變數自訂 Swiper 樣式。

我們建議在正在使用 Swiper 的元件中匯入樣式。這可確保樣式僅在需要時載入

<script>
  import { defineComponent } from 'vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    ...
  });
</script>

注意

使用 Ionic 時，匯入 @ionic/vue/css/ionic-swiper.css 並**非**使用 Swiper.js 的必要條件。此檔案用於與 ion-slides 元件的向後相容性，如果您不喜歡使用樣式表中提供的 CSS 變數，可以安全地省略它。

更新選取器

先前，我們可以指定 ion-slides 和 ion-slide 來套用任何自訂樣式。這些樣式區塊的內容保持不變，但我們需要更新選取器。以下是從 ion-slides 轉換為 Swiper Vue 時的選取器變更清單

ion-slides 選取器	Swiper 選取器
ion-slides	.swiper
ion-slide	.swiper-slide

預處理器（選用）

對於使用 SCSS 或 Less 樣式的開發人員，Swiper 也為這些檔案提供匯入。

對於 Less 樣式，請在 Swiper 匯入路徑中將 css 替換為 less

import 'swiper/less';
import '@ionic/vue/css/ionic-swiper.css';

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

import 'swiper/scss';
import '@ionic/vue/css/ionic-swiper.css';

使用元件

Swiper 匯出兩個元件：Swiper 和 SwiperSlide。Swiper 元件相當於 IonSlides，而 SwiperSlide 相當於 IonSlide。

這些元件是從 swiper/vue 匯入並提供給您的 Vue 元件的

<template>
  <ion-page>
    <ion-content>
      <swiper>
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>

<script>
  import { defineComponent } from 'vue';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: {
      Swiper,
      SwiperSlide,
      IonContent,
      IonPage,
    },
  });
</script>

使用模組

預設情況下，Swiper for Vue 不會匯入任何其他模組。若要使用導覽或分頁等模組，您需要先匯入它們。

ion-slides 自動包含分頁、捲軸、自動播放、鍵盤和縮放模組。本指南的這部分將說明如何安裝這些模組。

首先，我們需要從 swiper 套件匯入模組及其對應的 CSS 檔案

<template>
  <ion-page>
    <ion-content>
      <swiper>
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
  });
</script>

從這裡，我們需要使用 swiper 元件上的 modules 屬性，將這些模組提供給 Swiper

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom],
      };
    },
  });
</script>

最後，我們可以透過使用適當的屬性來開啟這些功能

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" :autoplay="true" :keyboard="true" :pagination="true" :scrollbar="true" :zoom="true">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom],
      };
    },
  });
</script>

注意

如需模組的完整清單，請參閱https://swiper.dev.org.tw/vue#usage。

IonicSlides 模組

透過 ion-slides，Ionic 自動自訂了數十個 Swiper 屬性。這帶來了在行動裝置上滑動時感覺流暢的體驗。我們建議使用 IonicSlides 模組，以確保在使用 Swiper 時也會設定這些屬性。但是，使用此模組並**非**在 Ionic 中使用 Swiper.js 的必要條件。

建議檢閱 IonicSlides 設定的屬性，並判斷您要自訂哪些屬性。

我們可以透過從 @ionic/vue 匯入 IonicSlides 模組，並將其作為 modules 陣列中的最後一個項目傳遞來安裝它

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" :autoplay="true" :keyboard="true" :pagination="true" :scrollbar="true" :zoom="true">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/autoplay';
  import 'swiper/css/keyboard';
  import 'swiper/css/pagination';
  import 'swiper/css/scrollbar';
  import 'swiper/css/zoom';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides],
      };
    },
  });
</script>

注意

IonicSlides 模組必須是陣列中的最後一個模組。這將使其自動自訂分頁、捲軸、縮放等模組的設定。

屬性

Swiper 選項是直接作為 props 提供在 <swiper> 元件上，而不是透過 ion-slides 中的 options 物件。

假設在具有 ion-slides 的應用程式中，我們設定了 slidesPerView 和 loop 選項

<template>
  <ion-slides :options="{ slidesPerView: 3, loop: true }">
    <ion-slide>Slide 1</ion-slide>
    <ion-slide>Slide 2</ion-slide>
    <ion-slide>Slide 3</ion-slide>
  </ion-slides>
</template>

若要遷移，我們會將這些選項從 options 物件中移出，並直接作為屬性移至 <swiper> 元件

<template>
  <swiper :slides-per-view="3" :loop="true">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper>
</template>

以下是從 ion-slides 轉換為 Swiper Vue 時的屬性變更完整清單

名稱	注意事項
options	將每個選項設定為直接在 <swiper> 元件上的屬性。
mode	針對基於模式的不同樣式，您可以在 CSS 中使用 .ios .swiper 或 .md .swiper 來指定幻燈片。
pager	改用 pagination 屬性。需要安裝分頁模組。
scrollbar	您可以繼續使用 scrollbar 屬性，只需確保先安裝捲軸模組即可。

注意

Swiper Vue 中可用的所有屬性都可以在https://swiper.dev.org.tw/vue#swiper-props 中找到。

事件

由於 Swiper 元件不是由 Ionic Framework 提供，因此事件名稱不會有 ionSlide 前綴。

假設在具有 ion-slides 的應用程式中，我們使用了 ionSlideDidChange 事件

<template>
  <ion-slides @ionSlideDidChange="onSlideChange">
    <ion-slide>Slide 1</ion-slide>
    <ion-slide>Slide 2</ion-slide>
    <ion-slide>Slide 3</ion-slide>
  </ion-slides>
</template>

若要遷移，我們會將事件的名稱變更為 slideChange

<template>
  <swiper @slideChange="onSlideChange">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper>
</template>

以下是從 ion-slides 轉換為 Swiper Vue 時的事件名稱變更完整清單

ion-slides 事件	Swiper 事件
ionSlideWillChange	slideChangeTransitionStart
ionSlideDidChange	slideChangeTransitionEnd
ionSlideDoubleTap	doubleTap
ionSlideDrag	sliderMove
ionSlideNextStart	slideNextTransitionStart
ionSlideNextEnd	slideNextTransitionEnd
ionSlidePrevStart	slidePrevTransitionStart
ionSlidePrevEnd	slidePrevTransitionEnd
ionSlideReachStart	到達起始點
ionSlideReachEnd	到達終點
ionSlideTap	點擊
ionSlideTouchStart	觸摸開始
ionSlideTouchEnd	觸摸結束
ionSlideTransitionStart	轉場開始
ionSlideTransitionEnd	轉場結束
ionSlidesDidLoad	初始化

注意

所有在 Swiper Vue 中可用的事件都可以在這裡找到：https://swiper.dev.org.tw/vue#swiper-events。

方法

大多數方法已被移除，改為直接存取 <swiper> 的 props。此外，當調用方法時，您不再需要先存取 $el。

存取這些屬性可能會有些棘手，因為您想要存取的是 Swiper 實例本身的屬性，而不是您的 Vue 組件。為此，我們建議透過 @swiper 事件處理器取得 Swiper 實例的參考。

<template>
  <swiper @swiper="setSwiperInstance"> ... </swiper>
</template>

<script>
  import { defineComponent, ref } from 'vue';
  export default defineComponent({
    ...,
    setup() {
      const slides = ref();
      const setSwiperInstance = (swiper: any) => {
        slides.value = swiper;
      }
      return { setSwiperInstance };
    }
  });
</script>

從這裡開始，如果您想存取 Swiper 實例上的屬性，您可以存取 slides.value。例如，如果您想檢查 isBeginning 屬性，您可以執行：slides.value.isBeginning。請確保先定義 slides.value！

以下是從 ion-slides 遷移到 Swiper Vue 時方法的完整變更列表

ion-slides 方法	注意事項
getActiveIndex()	請改用 activeIndex 屬性。
getPreviousIndex()	請改用 previousIndex 屬性。
getSwiper()	使用 @swiper 取得 Swiper 實例的參考。請參閱上面的範例。
isBeginning()	請改用 isBeginning 屬性。
isEnd()	請改用 isEnd 屬性。
length()	請改用 slides 屬性。(例如：swiperRef.slides.length)
lockSwipeToNext()	請改用 allowSlideNext 屬性。
lockSwipeToPrev()	請改用 allowSlidePrev 屬性。
lockSwipes()	請改用 allowSlideNext、allowSlidePrev 和 allowTouchMove 屬性。
startAutoplay()	請改用 autoplay 屬性。
stopAutoplay()	請改用 autoplay 屬性。

效果

如果您正在使用 Cube 或 Fade 等效果，您可以像我們對其他模組一樣安裝它們。在此範例中，我們將使用淡入淡出效果。首先，我們將從 swiper 匯入 EffectFade 並在 modules 陣列中提供它

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

接下來，我們需要匯入與效果相關的樣式表

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/effect-fade';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

之後，我們可以透過將 swiper 上的 effect 屬性設定為 "fade" 來啟用它

<template>
  <ion-page>
    <ion-content>
      <swiper :modules="modules" effect="fade">
        <swiper-slide>Slide 1</swiper-slide>
        <swiper-slide>Slide 2</swiper-slide>
        <swiper-slide>Slide 3</swiper-slide>
      </swiper>
    </ion-content>
  </ion-page>
</template>
<script>
  import { defineComponent } from 'vue';
  import { EffectFade } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/vue';
  import { IonContent, IonPage, IonicSlides } from '@ionic/vue';

  import 'swiper/css';
  import 'swiper/css/effect-fade';
  import '@ionic/vue/css/ionic-swiper.css';

  export default defineComponent({
    components: { Swiper, SwiperSlide, IonContent, IonPage },
    setup() {
      return {
        modules: [EffectFade, IonicSlides],
      };
    },
  });
</script>

注意

有關 Swiper 中效果的更多資訊，請參閱https://swiper.dev.org.tw/vue#effects。

總結

現在您已經安裝了 Swiper，您可以享受一整套新的 Swiper 功能。我們建議從 Swiper Vue 介紹開始，然後參考 Swiper API 文件。

常見問題

在哪裡可以找到此遷移的範例？

您可以在 https://github.com/ionic-team/slides-migration-samples 找到使用 ion-slides 和等效 Swiper 用法的範例應用程式。

在哪裡可以獲得此遷移的協助？

如果您在遷移時遇到問題，請在 Ionic 論壇上建立貼文。

在哪裡提交錯誤報告？

在提出問題之前，請考慮在 Swiper 討論區或 Ionic 論壇上建立貼文，看看您的問題是否可以由社群解決。

如果您在使用 Swiper 函式庫時遇到問題，則應在 Swiper 儲存庫上提交新的錯誤：https://github.com/nolimits4web/swiper/issues

如果您在使用 IonicSlides 模組時遇到問題，則應在 Ionic Framework 儲存庫上提交新的錯誤：https://github.com/ionic-team/ionic-framework/issues