版本：v8

從 IonSlides 遷移到 Swiper.js

正在尋找 IonSlides 嗎？

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

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

注意

Swiper 的 React 元件將在 Swiper 的未來版本中移除，並以 Swiper Element 作為替代。然而，本指南將說明如何遷移至 React 元件，因為它在撰寫本文時提供了最穩定的體驗。值得注意的是，React 目前尚未對 Web Components 提供強大的支援。

使用 Swiper 的 React 元件並非將 Swiper.js 與 Ionic Framework 一起使用的必要條件。

開始使用

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

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

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

npm install swiper@latest

注意

使用 Create React App 的開發人員必須使用 react-scripts v5.0.0+ 和最新版本的 Swiper。

滑動樣式

接下來，我們需要匯入基本的 Swiper 樣式。我們還將匯入 Ionic 提供的樣式，這將讓我們可以使用我們在 IonSlides 中使用的相同 CSS 變數來自訂 Swiper 樣式。

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

注意

使用 Swiper.js 與 Ionic 時，不需匯入 @ionic/react/css/ionic-swiper.css。此檔案用於與 IonSlides 元件的向後相容性，如果您不想使用樣式表中提供的 CSS 變數，可以安全地省略此檔案。

更新選擇器

先前，我們可以鎖定 ion-slides 和 ion-slide 以套用任何自訂樣式。這些樣式區塊的內容保持不變，但我們需要更新選擇器。以下是從 ion-slides 移至 Swiper React 時的選擇器變更清單

ion-slides 選擇器	Swiper 選擇器
`ion-slides`	`.swiper`
`ion-slide`	`.swiper-slide`

預處理器（選用）

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

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    ...
  );
};
export default Home;

使用元件

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

這些元件是從 swiper/react 匯入的

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

使用模組

預設情況下，Swiper for React 不會匯入任何其他模組。若要使用 Navigation 或 Pagination 等模組，您需要先匯入它們。

IonSlides 會自動包含 Pagination、Scrollbar、Autoplay、Keyboard 和 Zoom 模組。本指南的此部分將說明如何安裝這些模組。

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper
          modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom]}
          autoplay={true}
          keyboard={true}
          pagination={true}
          scrollbar={true}
          zoom={true}
        >
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

注意

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

IonicSlides 模組

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

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

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper/modules';

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/react/css/ionic-swiper.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper
          modules={[Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides]}
          autoplay={true}
          keyboard={true}
          pagination={true}
          scrollbar={true}
          zoom={true}
        >
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

注意

IonicSlides 模組必須是陣列中的最後一個模組。這將使其自動自訂 Pagination、Scrollbar、Zoom 等模組的設定。

屬性

Swiper 選項以 props 的形式直接在 <Swiper> 元件上提供，而不是透過 IonSlides 中的 options 物件提供。

假設在具有 IonSlides 的應用程式中，我們已設定 slidesPerView 和 loop 選項

const MyComponent: React.FC = () => {
  return (
    <IonSlides
      options={{
        slidesPerView: 3,
        loop: true,
      }}
    >
      <IonSlide>Slide 1</IonSlide>
      <IonSlide>Slide 2</IonSlide>
      <IonSlide>Slide 3</IonSlide>
    </IonSlides>
  );
};

若要遷移，我們將這些選項移出 options 物件，並直接作為屬性放在 <Swiper> 元件上

const MyComponent: React.FC = () => {
  return (
    <Swiper slidesPerView={3} loop={true}>
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
};

以下是從 IonSlides 移至 Swiper React 時的完整屬性變更清單

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

注意

Swiper React 中提供的所有屬性都可以在 https://swiper.dev.org.tw/react#swiper-props 中找到。

事件

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

假設在具有 IonSlides 的應用程式中，我們使用了 onIonSlideDidChange 事件

const MyComponent: React.FC = () => {
  return (
    <IonSlides onIonSlideDidChange={() => onSlideChange()}>
      <IonSlide>Slide 1</IonSlide>
      <IonSlide>Slide 2</IonSlide>
      <IonSlide>Slide 3</IonSlide>
    </IonSlides>
  );
};

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

const MyComponent: React.FC = () => {
  return (
    <Swiper onSlideChange={() => onSlideChange()}>
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
    </Swiper>
  );
};

以下是從 IonSlides 移至 Swiper React 時的完整事件名稱變更清單

IonSlides 事件	Swiper 事件
`onIonSlideWillChange`	`onSlideChangeTransitionStart`
`onIonSlideDidChange`	`onSlideChangeTransitionEnd`
`onIonSlideDoubleTap`	`onDoubleTap`
`onIonSlideDrag`	`onSliderMove`
`onIonSlideNextStart`	`onSlideNextTransitionStart`
`onIonSlideNextEnd`	`onSlideNextTransitionEnd`
`onIonSlidePrevStart`	`onSlidePrevTransitionStart`
`onIonSlidePrevEnd`	`onSlidePrevTransitionEnd`
`onIonSlideReachStart`	`onReachBeginning`
`onIonSlideReachEnd`	`onReachEnd`
`onIonSlideTap`	`onTap`
`onIonSlideTouchStart`	`onTouchStart`
`onIonSlideTouchEnd`	`onTouchEnd`
`onIonSlideTransitionStart`	`onTransitionStart`
`onIonSlideTransitionEnd`	`onTransitionEnd`
`onIonSlidesDidLoad`	`onInit`

注意

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

方法

大多數方法已被移除，改為直接存取 Swiper 的 props。

由於您需要存取 Swiper 實例本身的屬性，而不是您的 React 元件，因此存取這些屬性可能會有些棘手。為此，我們建議透過 onSwiper 取得 Swiper 實例的參考。

import React, { useState } from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import { Swiper as SwiperInterface } from 'swiper';
...
const Home: React.FC = () => {
  const [swiperInstance, setSwiperInstance] = useState<SwiperInterface>();
  return (
    ...
    <Swiper
      onSwiper={(swiper) => setSwiperInstance(swiper)}
    >
      ...
    </Swiper>
  )
};
export default Home;

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

以下是從 IonSlides 轉換到 Swiper React 時的所有方法變更列表

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

效果

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]}>
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

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

import React from 'react';
import { IonContent, IonPage, IonicSlides } from '@ionic/react';
import { EffectFade } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonContent>
        <Swiper modules={[EffectFade, IonicSlides]} effect="fade">
          <SwiperSlide>Slide 1</SwiperSlide>
          <SwiperSlide>Slide 2</SwiperSlide>
          <SwiperSlide>Slide 3</SwiperSlide>
        </Swiper>
      </IonContent>
    </IonPage>
  );
};
export default Home;

注意

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

總結

現在您已安裝 Swiper，您可以享受一整套新的 Swiper 功能。我們建議從Swiper React 簡介開始，然後參考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

開始使用​

滑動樣式​

更新選擇器​

預處理器（選用）​

使用元件​

使用模組​

IonicSlides 模組​

屬性​

事件​

方法​

效果​

總結​

常見問題​

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

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

在哪裡提交錯誤報告？​

目錄