Swiper（v7）へのアップグレード対応

2021.11.16 2024.01.12

TIPS

inoue

Swiperって？

過去記事に載せているスライダーのJSプラグインSwiperのことです。

スライダーといえばSwiper！

この記事では、v6から記事執筆時の最新バージョンのv7.2.0へのアップグレード方法についてのメモになります。v6からの変更点がありますので、v6のデモをv7にアップデートする形で説明しようと思います。

公式のv7への移行ガイドは下記。

Migration Guide to Swiper 7
https://swiperjs.com/migration-guide

2021/08末あたりにv7が公開されたので情報としてはちょっと遅いと思いますが、今後過去プロジェクトを更新する時にv7に変える場合が出てくると思うので忘れないようにひとまずメモ。

v6→v7へのアップグレード方法

上にも書きましたが、公式にv7への移行ガイドがありますので、まずはそれに沿って内容を把握していきます。
サンプルコードは説明のためにほぼ公式そのまま引用させてもらってます。

HTMLクラス名の変更

まず1番大きな変更が、HTMLに付与するクラス名の変更です。

具体的には.swiper-containerというクラス名の指定が.swiperに変わっています。

実際のソースコードで説明すると、v6では下記のようなクラスでした。

<body>
  <div class="swiper-container">
    <div class="swiper-wrapper">
        <div class="swiper-slide">Slide 1</div>
        <div class="swiper-slide">Slide 2</div>
        <div class="swiper-slide">Slide 3</div>
    </div>
  </div>
</body>

v7では下記のようになります。

<body>
  <div class="swiper"> <!-- ←この要素のクラス名が変わる -->
    <div class="swiper-wrapper">
        <div class="swiper-slide">Slide 1</div>
        <div class="swiper-slide">Slide 2</div>
        <div class="swiper-slide">Slide 3</div>
    </div>
  </div>
</body>

CSSファイルの読み込み変更（npm インストール時）

npmでSwiperをインストールしてローカル環境からCSSをインポートして使う場合、パスが変わっています。

v6までは下記。

// swiper bundle styles
import 'swiper/swiper-bundle.min.css'

// swiper core styles
import 'swiper/swiper.min.css'

// modules styles
import 'swiper/components/navigation/navigation.min.css'
import 'swiper/components/pagination/pagination.min.css'
...

v7では下記のように変更

// swiper bundle styles
import 'swiper/css/bundle'

// swiper core styles
import 'swiper/css'

// modules styles
import 'swiper/css/navigation'
import 'swiper/css/pagination'
...

正直、筆者はこの機能は使わないので個人的にはあまり影響がありませんでした。
影響があるとすれば、WebpackでJSファイルにimportの記述を書いて使っている場合、もしくはSassでnode-sassを使っていて廃止予定の@importをまだ使っている場合、などでしょうか。
筆者はCSSもJSもSwiperの公式ドキュメントに載っている「カスタムビルド」で毎回必要なモジュールだけ含めたファイルを生成して必要最低限のコードだけ使っています。そういった場合はv7でも影響がありません。

Swiperのカスタムビルドについては下記。

Custom Build
https://swiperjs.com/swiper-api#custom-build

パラメータの変更

Swiperのオプションで指定できるパラメータがいくつか変更になっています。

touchEventsTarget デフォルトの指定が'wrapper'になりました。
watchOverflow がデフォルトでtrueになったので省略可能になりました。
resizeObserver resizeObserver対応のブラウザ（IE以外）の場合は、デフォルトでtrueになりました。
watchVisibleSlides パラメーターが削除され、watchSlidesProgressに統合されました。

個人的に影響があるのはwatchOverflowぐらいですかね。スライドの数が足りない時にスライドを無効にするオプションです。今まで毎回書いていたので、デフォルトに組み込まれたのは良かったです。

モジュールのインストール方法の変更

Swiperは必要な機能だけ個別でモジュールとしてインストールできる機能があります。
その記述方法が若干変わりました。

v6では下記。

import Swiper, { Navigation, Pagination } from 'swiper';

Swiper.use([Navigation, Pagination]);

new Swiper('.my-swiper', {
  // ...
});

v7では下記のようになります。

import Swiper, { Navigation, Pagination } from 'swiper';

new Swiper('.my-swiper', {
  // pass modules here
  modules: [Navigation, Pagination],
  // ...
});

Swiper.use()がなくなり、オプションパラメーターにmoduleとして指定できるようになりました。
確かにこの方がシンプルでわかりやすいですね。

Free Modeパラメータの指定方法の変更

freeMode パラメータの指定方法が変更になりました。
通常のスライドの場合は1回スワイプした時にslidesPerGroupに指定した数だけ1回スライドが動くようになっていますが、フリーモードの場合は指定した数に縛られないようになり、スワイプの強度で慣性が効くような動きになります。

v6では下記のようにFreeMode関連のパラメータは分かれていました。

import Swiper from 'swiper';

new Swiper('.my-swiper', {
  freeMode: true,
  freeModeMinimumVelocity: 0.2,
  freeModeMomentum: false,
});

v7では下記のようにオブジェクトでの指定に変わりました。

// import FreeMode module if you use core version of Swiper
import Swiper, { FreeMode } from 'swiper';

new Swiper('.my-swiper', {
  // install FreeMode module if you use core version of Swiper
  modules: [FreeMode],
  freeMode: {
    enabled: true,
    minimumVelocity: 0.2,
    momentum: false,
  },
});

Manipulationモジュールの変更

swiper.appendSlide()やswiper.prependSlide()といった操作系の機能はManipulationというモジュールに分割されたので使うときは他のモジュールと同様にmodulesパラメータの指定が必要になりました。

// import Manipulation module if you use core version of Swiper
import Swiper, { Manipulation } from 'swiper';

new Swiper('.my-swiper', {
  // install Manipulation module if you use core version of Swiper
  modules: [Manipulation],
  // ...
});

// Now slides manipulation methods are available
swiper.appendSlide('<div class="swiper-slide">Slide 1</div>');

Gridモジュールの変更

slidesPerColumnパラメータを使ったグリッド表示のスライドを使いたい場合、Gridというモジュールに分割され、記述方法も変更されました。

v6では下記のようにしていたものを、

import Swiper from 'swiper';

new Swiper('.my-swiper', {
  slidesPerColumn: 2,
  slidesPerColumnFill: 'row',
});

v7では下記のように変更します。

// import Grid module if you use core version of Swiper
import Swiper, { Grid } from 'swiper';

new Swiper('.my-swiper', {
  // install Grid module if you use core version of Swiper
  modules: [Grid],
  grid: {
    rows: 2,
    fill: 'row',
  },
});

端的でわかりやすい指定方法に変わっています。
正直あまり使わないパラメータではあったので、モジュールに分割されたことで使う時だけインポートできるのも良いと思います。

プラグインAPIの変更

プラグインAPIはかなり大幅に作り直されたようで、v6とv7は全く互換性がなくなるみたいです。
筆者は標準のSwiperでも機能盛りだくさんで充分すぎて自作プラグインを追加しようと思ったことがなく、今回初めて存在を知りました。笑

v6では下記のような記述でしたが、

/**
 * Plugin Definition
 **/
const MyPlugin = {
  params: {
    myPluginParameter: false,
  },
  create() {
    const swiper = this;
    swiper.myPlugin = {
      doSomething() {
        console.log('my plugin does something');
      },
    };
  },
  on: {
    init(swiper) {
      if (!swiper.params.myPluginParameter) return;
      console.log('my plugin init');
    },
  },
};

/**
 * Plugin Usage
 **/

Swiper.use([MyPlugin]);

const swiper = new Swiper('.my-swiper', {
  myPluginParameter: true,
});

swiper.myPlugin.doSomething();

v7では下記のようになります。

/**
 * Plugin Definition
 **/
function MyPlugin({ swiper, extendParams, on }) {
  extendParams({
    myPluginParameter: false,
  });
  swiper.myPlugin = {
    doSomething() {
      console.log('my plugin does something');
    },
  };
  on('init', (_swiper) => {
    if (!swiper.params.myPluginParameter) return;
    console.log('my plugin init');
  });
}
/**
 * Plugin Usage
 **/

const swiper = new Swiper('.my-swiper', {
  modules: [MyPlugin],
  myPluginParameter: true,
});

swiper.myPlugin.doSomething();

プラグイン関数ではparamsがextendParamsに変わって、create()がなくなっています。
あとは他のモジュールと同じようにSwiperのオプションにmodulesパラメータで指定してあげると、プラグイン内で定義したパラメータが使えるようになる、ということみたいです。

コード見てみると割と簡単そう。Swiper使う時にリサイズ処理したりサムネイル付きにしたりとか毎回同じような処理を書くことが多いので、そこだけプラグイン化してパラメータ1つ指定するだけで再現できるようにするっていうのもありかなーって思いました。

ここまでで一通り公式に書いてある移行ガイドはさらっと触れました。

次は実際にv6で書いていたものをv7に移行してみます。

実際にSwiperをv6からv7に移行してみる

ここからは実際にv6のデモをv7に変更してみます。

CDNを使っている場合

SwiperをCDNを使って設置している場合の移行方法について。

読み込むファイルの変更

CDNの場合は下記のように変更。

//v6のCSS
<link rel="stylesheet" href="https://unpkg.com/swiper@6.0.4/swiper-bundle.min.css">
//v6のJS
<script src="https://unpkg.com/swiper@6.0.4/swiper-bundle.min.js"></script>

//v7のCSS
<link rel="stylesheet" href="https://unpkg.com/swiper@7.2.0/swiper-bundle.min.css">
//v7のJS
<script src="https://unpkg.com/swiper@7.2.0/swiper-bundle.min.js"></script>

HTMLの変更

v6で.swiper-containerとしていた部分を

<div class="swiper-container">
  ・・・
</div>

下記のように.swiperに変更。

<div class="swiper">
  ・・・
</div>

JSの変更

もしクラス指定に.swiper-containerを使っていた場合は.swiperに変更

<script>
  const mySwiper = new Swiper ('.swiper', {
    loop: true,
    pagination: {
      el: '.swiper-pagination',
    },
    navigation: {
      nextEl: '.swiper-button-next',
      prevEl: '.swiper-button-prev',
    }
  });
</script>

長々と公式の移行ガイドに沿って説明しましたが、これだけですね。笑
CDNを使う場合で、ほんとにシンプルなスライド機能を使うだけの場合は特に移行の手間はかかりません。

ではnpmを使ってインストールしたSwiperを使う場合はどうか。

npmインストールで使っている場合

読み込みファイルはWebpackなどで生成した任意のファイル、
HTMLは.swiper-containerを.swiperに変更するところは同じなので割愛します。

Sassの変更を見ていきます。

Sassの変更

ここではgulpでdart-sassを使ってコンパイルする場合について書きます。
@useを使って、node_modulesから必要なファイルを下記のようにして引っ張ってきます。

@use '../../../../node_modules/swiper/swiper.scss';
@use '../../../../node_modules/swiper/modules/navigation/navigation.scss';
@use '../../../../node_modules/swiper/modules/pagination/pagination.scss';

※node_modulesへの相対パスはビルド環境によって変更してください。
ちょっとパスの記述が面倒ですが、これでSassに必要なモジュール分だけ取り込んでコンパイルできます。

公式ではCSSのモジュールの読み込みパスは下記のようになっていますが

import 'swiper/css/navigation'
import 'swiper/css/pagination'

これはWebpackでJSファイルにまとめて読み込む場合に使えるパスであって、GulpでSassコンパイルする場合はscssファイルにこの形式で書いても読み込めませんので注意です。

JSの変更

v6では下記のように書いていたと思いますが、

import Swiper, { Navigation, Pagination } from 'swiper';

Swiper.use([Navigation, Pagination]);

const mySwiper = new Swiper('.swiper-container', {
  loop: true,
  pagination: {
    el: '.swiper-pagination',
  },
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  }
});

JSはv7では下記のようになります。

import Swiper, { Navigation, Pagination } from 'swiper';

const mySwiper = new Swiper('.swiper', {
  modules: [Navigation, Pagination],
  loop: true,
  pagination: {
    el: '.swiper-pagination',
  },
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  }
});