バージョン: v8

ion-slidesからSwiper.jsへの移行

ion-slidesをお探しですか？

ion-slidesはv6.0.0で非推奨となり、v7.0.0で削除されました。Swiper.jsライブラリを直接使用することをお勧めします。移行プロセスについては、以下で詳しく説明します。

最新のタッチスライダーコンポーネントが必要な場合は、Swiper.jsをお勧めします。Swiper 9では、Angularコンポーネントの代替としてSwiper Elementが導入されたため、このガイドではIonic FrameworkアプリケーションでSwiper Elementを設定する方法について説明します。また、ion-slidesからSwiper Elementに移行するために必要な移行情報についても説明します。

はじめに

まず、Ionicの最新バージョンに更新します。

npm install @ionic/angular@latest

それが完了したら、プロジェクトにSwiperの依存関係をインストールします。

npm install swiper@latest

次に、カスタム要素を使用することをAngularに伝えるCUSTOM_ELEMENTS_SCHEMAを追加する必要があります。これは、app.module.ts、またはSwiperを使用するコンポーネントのモジュールファイルで行うことができます。

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

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

最後に、Swiperのカスタム要素をグローバルに登録するために、Swiperのregister関数を呼び出す必要があります。これは一度だけ行う必要があるため、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.dokyumento.jp/element#core-version-and-modulesを参照してください。この移行ガイドの残りの部分では、バンドル版を使用していることを前提としています。

スタイリッシュなスワイプ

CSSを移行するには、まずセレクターを新しいカスタム要素をターゲットにするように更新します。

ion-slidesセレクター	Swiperセレクター
`ion-slides`	`swiper-container`
`ion-slide`	`swiper-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.dokyumento.jp/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の多数のプロパティを自動的にカスタマイズしました。これにより、モバイルデバイスでスワイプするときにスムーズな体験が得られました。Swiperを直接使用する場合でもこれらのプロパティが設定されるように、IonicSlidesモジュールを使用することをお勧めします。ただし、このモジュールの使用は、IonicでSwiper.jsを使用するために必須ではありません。

IonicSlidesで設定されたプロパティを確認し、カスタマイズするものを決定することをお勧めします。

IonicSlidesモジュールは、swiper-containerのmodulesプロパティに配列としてインポートして渡すことでインストールできます。

Angular
Angular（スタンドアロン）

// home.page.ts

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

@Component({
  ...
})
export class HomePage {
  swiperModules = [IonicSlides];
}

// home.page.ts

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

@Component({
  ...
})
export class HomePage {
  swiperModules = [IonicSlides];
}

<!-- home.page.html -->

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

注意

Swiperのコアバージョンを使用しており、追加のモジュールをインストールしている場合は、IonicSlidesが配列の最後のモジュールであることを確認してください。これにより、Pagination、Scrollbar、Zoomなどのモジュールの設定を自動的にカスタマイズできます。

プロパティ

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.dokyumento.jp/swiper-api#parametersにあります。

イベント

swiper-containerコンポーネントはIonic Frameworkによって提供されていないため、イベント名にはionSlideプレフィックスは付きません。さらに、すべてのイベント名はcamelCaseではなく小文字にする必要があります。

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イベント
`ionSlideWillChange`	`swiperslidechangetransitionstart`
`ionSlideDidChange`	`swiperslidechange`
`ionSlideDoubleTap`	`swiperdoubletap`
`ionSlideDrag`	`swiperslidermove`
`ionSlideNextStart`	`swiperslidenexttransitionstart`
`ionSlideNextEnd`	`swiperslidenexttransitionend`
`ionSlidePrevStart`	`swiperslideprevtransitionstart`
`ionSlidePrevEnd`	`swiperslideprevtransitionend`
`ionSlideReachStart`	`swiperreachbeginning`
`ionSlideReachEnd`	`swiperreachend`
`ionSlideTap`	`swipertap`
`ionSlideTouchStart`	`swipertouchstart`
`ionSlideTouchEnd`	`swipertouchend`
`ionSlideTransitionStart`	`swipertransitionstart`
`ionSlideTransitionEnd`	`swipertransitionend`
`ionSlidesDidLoad`	`swiperinit`

注意

Swiper Element で利用可能なすべてのイベントは、https://swiper.dokyumento.jp/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.dokyumento.jp/swiper-api#methods-and-properties に記載されています。

エフェクト

バンドル版の Swiper を使用している限り、Cube や Fade などのエフェクトは、追加のインポートなしで Swiper Element で使用できます。たとえば、以下のコードでは、スライドにフリップトランジションエフェクトが適用されます。

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

注意

Swiper のエフェクトの詳細については、https://swiper.dokyumento.jp/swiper-api#fade-effect を参照してください。

まとめ

Swiper がインストールされたので、Swiper の新しい機能をすべて楽しむことができます。Swiper Element ドキュメントから開始し、次に Swiper API ドキュメントを参照することをお勧めします。

FAQ

この移行の例はどこにありますか？

ion-slides と同等の Swiper の使用例を含むサンプルアプリは、https://github.com/ionic-team/slides-migration-samples で確認できます。

この移行に関するヘルプはどこで入手できますか？

移行で問題が発生した場合は、Ionic Forum に投稿してください。

バグレポートはどこに提出すればよいですか？

問題を提起する前に、Swiper ディスカッションボードまたは Ionic Forum に投稿して、コミュニティで問題を解決できるかどうかを確認してください。

Swiper ライブラリで問題が発生した場合は、新しいバグは Swiper リポジトリに提出する必要があります: https://github.com/nolimits4web/swiper/issues

IonicSlides モジュールで問題が発生した場合は、新しいバグは Ionic Framework リポジトリに提出する必要があります: https://github.com/ionic-team/ionic-framework/issues

はじめに​

バンドル版とコア版​

スタイリッシュなスワイプ​

追加のion-slidesスタイル​

IonicSlidesモジュール​

プロパティ​

イベント​

メソッド​

エフェクト​

まとめ​

FAQ​

この移行の例はどこにありますか？​

この移行に関するヘルプはどこで入手できますか？​

バグレポートはどこに提出すればよいですか？​

目次