跳至主要內容
版本：v8

從 ion-slides 遷移至 Swiper.js

正在尋找 ion-slides 嗎？

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

如果您需要現代的觸控滑塊元件，我們建議使用 Swiper.js。Swiper 9 引入了 Swiper Element 來取代其 Angular 元件，因此本指南將說明如何在您的 Ionic Framework 應用程式中設定 Swiper Element。它還將說明您可能需要從 ion-slides 移動到 Swiper Element 的任何遷移資訊。

開始使用​

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

npm install @ionic/angular@latest

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

npm install swiper@latest

接下來，我們需要新增 CUSTOM_ELEMENTS_SCHEMA，這會告訴 Angular 我們將使用自訂元素。這可以在 app.module.ts 中完成，或在您將使用 Swiper 的元件的模組檔案中完成。

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [..., CUSTOM_ELEMENTS_SCHEMA]
});
...

最後，我們需要呼叫 Swiper 的 register 函數來全域註冊 Swiper 的自訂元素。這應該只執行一次，因此請將它放在 app.component.ts 中。

import { register } from 'swiper/element/bundle';

register();

@Component({
  ...
})
...

從那裡，我們只需要將 ion-slides 元素替換為 swiper-container，並將 ion-slide 元素替換為 swiper-slide。請注意，這些自訂元素不需要匯入，因為呼叫 register 會自行告知 Angular 這些元素。

<swiper-container>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

捆綁版與核心版​

依預設，請確保從 swiper/element/bundle 匯入 register 函數。這會使用 Swiper 的捆綁版，其中會自動包含執行 Swiper 各種功能所需的所有模組和樣式表。

如果您想改用核心版，其中不包含其他模組，請參閱 https://swiper.dev.org.tw/element#core-version-and-modules。本遷移指南的其餘部分將假設您使用的是捆綁版。

滑動樣式​

若要遷移您的 CSS，請先更新您的選取器以鎖定新的自訂元素

ion-slides 選取器Swiper 選取器
ion-slidesswiper-container
ion-slideswiper-slide

如果您使用的是在 ion-slides 上找到的 CSS 自訂屬性，以下是 Swiper 中使用的對應屬性清單。

ion-slides CSS 屬性swiper-container CSS 屬性
--bullet-background--swiper-pagination-bullet-inactive-color
--bullet-background-active--swiper-pagination-color
--progress-bar-background--swiper-pagination-progressbar-bg-color
--progress-bar-background-active--swiper-pagination-color
--scroll-bar-background--swiper-scrollbar-bg-color
--scroll-bar-background-active--swiper-scrollbar-drag-bg-color

如需額外的自訂 CSS，由於 Swiper Element 使用 Shadow DOM 封裝，樣式將需要注入到 Shadow DOM 範圍內。如需指示，請參閱 https://swiper.dev.org.tw/element#injecting-styles。

其他 ion-slides 樣式​

ion-slides 元件具有額外的樣式，可協助建立原生的外觀和風格。使用 Ionic 搭配 Swiper.js 時，這些樣式並非必須的，但如果您想盡可能地維持 ion-slides 的外觀，請將下列 CSS 新增至您的 global.scss

swiper-container {
  --swiper-pagination-bullet-inactive-color: var(--ion-text-color-step-800, #cccccc);
  --swiper-pagination-color: var(--ion-color-primary, #0054e9);
  --swiper-pagination-progressbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.25);
  --swiper-scrollbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.1);
  --swiper-scrollbar-drag-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.5);
}

swiper-slide {
  display: flex;
  position: relative;

  flex-direction: column;
  flex-shrink: 0;
  align-items: center;
  justify-content: center;

  width: 100%;
  height: 100%;

  font-size: 18px;

  text-align: center;
  box-sizing: border-box;
}

swiper-slide img {
  width: auto;
  max-width: 100%;
  height: auto;
  max-height: 100%;
}

IonicSlides 模組​

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

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

我們可以透過匯入 IonicSlides 模組並將其以陣列形式傳遞至 swiper-container 的 modules 屬性來安裝它

// home.page.ts

import { IonicSlides } from '@ionic/angular';

@Component({
  ...
})
export class HomePage {
  swiperModules = [IonicSlides];
}
<!-- home.page.html -->

<swiper-container [modules]="swiperModules"> ... </swiper-container>
注意

如果您使用的是 Swiper 的核心版並安裝了其他模組，請確保 IonicSlides 是陣列中的最後一個模組。這將使其自動自訂諸如分頁、捲軸、縮放等模組的設定。

屬性​

Swiper 選項應以個別屬性的形式直接在 <swiper-container> 元件上提供。

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

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

若要將這些選項設定為 <swiper-container> 上的屬性，我們會執行下列動作

<swiper-container [slidesPerView]="3" [loop]="true">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

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

名稱附註
選項將每個選項設定為直接在 <swiper-container> 元件上的屬性。
模式針對基於模式的不同樣式，您可以使用 CSS 中的 .ios swiper-container 或 .md swiper-container 來鎖定幻燈片。
呼叫器改用 pagination 屬性。
注意

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

事件​

由於 swiper-container 元件不是由 Ionic Framework 提供，事件名稱將不會有 ionSlide 字首。此外，所有事件名稱應使用小寫而非駝峰式大小寫。

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

<ion-slides (ionSlideDidChange)="onSlideChange()">
  <ion-slide>Slide 1</ion-slide>
  <ion-slide>Slide 3</ion-slide>
  <ion-slide>Slide 3</ion-slide>
</ion-slides>

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

<swiper-container (swiperslidechange)="onSlideChange()">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

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

ion-slides 事件Swiper 事件
ionSlideWillChangeswiperslidechangetransitionstart
ionSlideDidChangeswiperslidechange
ionSlideDoubleTapswiperdoubletap
ionSlideDragswiperslidermove
ionSlideNextStartswiperslidenexttransitionstart
ionSlideNextEndswiperslidenexttransitionend
ionSlidePrevStartswiperslideprevtransitionstart
ionSlidePrevEndswiperslideprevtransitionend
ionSlideReachStartswiperreachbeginning
ionSlideReachEndswiperreachend
ionSlideTapswipertap
ionSlideTouchStartswipertouchstart
ionSlideTouchEndswipertouchend
ionSlideTransitionStartswipertransitionstart
ionSlideTransitionEndswipertransitionend
ionSlidesDidLoadswiperinit
注意

所有 Swiper Element 中可用的事件都可以在 https://swiper.dev.org.tw/swiper-api#events 找到，並且應該使用小寫字母，並以 swiper 作為前綴。

方法​

大多數方法已被移除，改為直接存取 Swiper 實例的屬性。要存取 Swiper 實例，首先需要取得 <swiper-container> 元素的參考 (例如透過 ViewChild)，然後存取其 swiper 屬性。

<!-- slides.component.html -->

<swiper-container #swiper>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>
// slides.component.ts

import { ..., ElementRef, ViewChild } from '@angular/core';

@Component({
  ...
})
export class SlidesExample {
  @ViewChild('swiper')
  swiperRef: ElementRef | undefined;

  logActiveIndex() {
    console.log(this.swiperRef?.nativeElement.swiper.activeIndex);
  }
}

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

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

Swiper 實例上所有可用的方法和屬性都可以在 https://swiper.dev.org.tw/swiper-api#methods-and-properties 找到。

特效​

只要您使用的是 Swiper 的捆綁版本，就可以在 Swiper Element 中使用諸如 Cube 或 Fade 之類的效果，而無需額外導入。例如，以下程式碼將使幻燈片具有翻轉過渡效果

<swiper-container effect="flip"> ... </swiper-container>
注意

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

總結​

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

常見問題​

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

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

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

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

我應該在哪裡提交錯誤報告？​

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

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

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

目錄

編輯此頁面