久しぶりにSwiperを使おうと思ったら、前に使ったときからいろいろ変わっていた（最近こんなんばっかりだ）。まずドキュメントの読み方から躓いたため、備忘録としてSwiper(v11)の基本的な使い方をまとめておく。

Swiperのインストール方法

Swiperを使うには、まず必要なパッケージをインストールする必要がある。

bash
npm i -D swiper

CDNを利用する場合は、以下のようにバンドルされたCSSファイルとJavaScriptファイルをWebページに直接埋め込む。

html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css"
/>

<script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js"></script>

これらのCSSファイルとJavaScriptファイルには、後述するモジュールがすべて含まれている。したがってバージョンの差をあまり意識せずに、Swiperを利用できる。

Swiper v11の基本的な使い方

私が以前使ったSwiperは、v8だった。現在はv11だそうである。光と陰は弓矢のように速い。どうやらv10でモジュール構造が採用されたらしく、それ以前の感覚でSwiperを使おうとするとマゴマゴする。

HTMLレイアウト

Swiperを利用するには、所定のHTMLレイアウトに従う必要がある。以下のようなものである。

html
<!-- メインのコンテナ要素 -->
<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 class="swiper-pagination"></div>

  <!-- 任意の矢印ボタン用要素 -->
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>

  <!-- 任意のスクロールバー用要素 -->
  <div class="swiper-scrollbar"></div>
</div>

swiper、swiper-wrapper、swiper-slideの3つのクラスを持つ要素は必須である。残りは任意のクラス名を使える。ただ、上記のクラス名でデフォルトのスタイリングがなされている。任意のクラス名を使う場合は、そのクラス名でのスタイリングを忘れてはならない。

このHTMLのレイアウトは、v8から変わっていない（たぶん）。

デフォルトCSSとカスタムCSS

Swiperには、先のHTMLレイアウトを前提に、デフォルトのCSSが用意されている。これもJavaScriptファイルと同じようにモジュール化されており、使いたいものを適宜インポートする。

また、各モジュールのCSSファイルへのパスは、公式ドキュメントか、swiperパッケージのpackage.jsonのexportプロパティで確認できる。

独自にスタイルを指定したい場合は、先のクラスでスタイリングを上書きする。具体的には、デフォルトのCSSファイルをインポートした後に、自前のCSSファイルをインポートすれば良い。

コア機能とモジュール

ナビゲーションやページネーション、スライダの自動再生といった諸機能は、かつてSwiperクラス単体で賄われていた。現在のSwiperは機能ごとにモジュール化され、必要に応じてそれらを取り込む構造となっている。

CSSも同様で、モジュールごとに用意されたCSSファイルをJavaScriptファイルでインポートしてバンドルする。これにより、使用されない大部分のコードを削減できる。コードの削減は、バンドラによるツリーシェイキングというステップを経て行われる。

以下は、ナビゲーションとページネーションを備えたスライダーを作るサンプルである。

js
// Swiperのコア機能とナビゲーション、ページネーションモジュールをインポート
import Swiper from "swiper";
import { Navigation, Pagination } from "swiper/modules";

// コア機能と各モジュールのCSSファイルをインポート
import "swiper/css";
import "swiper/css/navigation";
import "swiper/css/pagination";

const swiper = new Swiper(".swiper", {
  modules: [Pagination, Navigation],
  loop: true,

  // ページネーション（スライダーの位置を示す丸いドット）用の要素を指定
  pagination: {
    el: ".swiper-pagination",
  },

  // 矢印ボタン用の要素を指定
  navigation: {
    nextEl: ".swiper-button-next",
    prevEl: ".swiper-button-prev",
  },
});

modulesというプロパティで、インポートしたモジュール（PaginationとNavigation）を読み込んでいる。下部のpaginationプロパティ、navigationプロパティは、modulesプロパティで該当のモジュールが読み込まれていないと用を成さない。v8からの流れで適当に使うと、ここでハマる。というかハマった。要注意ポイントだ。

上記コードを適当なバンドラ（webpackやrollupなど）でバンドルして、HTMLファイルで読み込む。これがSwiperの基本的な使い方である。

バンドラの設定

例えばwebpackでは、以下のような設定で必要なファイルをバンドルできる。

js
const path = require("path");

module.exports = [
  {
    mode: "development",
    entry: {
      index: "./src/index.js",
    },
    resolve: {
      extensions: [".js"],
    },
    output: {
      path: path.resolve(__dirname, "dist"),
      filename: "/assets/js/bundle.js",
    },
    module: {
      rules: [
        {
          test: /\.js$/,
          exclude: /node_modules/,
          use: {
            loader: "babel-loader",
          },
        },
        {
          test: /\.css$/i,
          use: ["style-loader", "css-loader"],
        },
      ],
    },
  },
];

この設定だと、JavaScriptファイルでインポートしているCSSファイル（swiper/cssなど）は、JavaScriptファイルが読み込まれた段階で<head>タグ内にそれぞれ別の<style>タグで追加される。ファイルを分けたいときは、style-loaderの代わりにMiniCssExtractPluginなどを使う。

HTMLでの読み込み

バンドルファイルを読み込むHTMLファイルは、以下のようになる。

html
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="content-type" content="text/html" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <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 class="swiper-pagination"></div>

      <!-- 任意の矢印ボタン用要素 -->
      <div class="swiper-button-prev"></div>
      <div class="swiper-button-next"></div>

      <!-- 任意のスクロールバー用要素 -->
      <div class="swiper-scrollbar"></div>
    </div>
    <script defer src="assets/js/bundle.js"></script>
  </body>
</html>

実用に耐えないサンプルであるが、Swiperの大まかな使い方を理解するには十分かと思う。

CDNを使う場合

先に示したように、全モジュールをバンドルしたJavaScriptファイルとCSSファイルがCDNで提供されている。ファイルサイズを気にせず、手っ取り早くSwiperを使いたいという剛の者には、こちらの使い方が向いている。

以下は、CDNを利用した場合のデモである。

html
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="content-type" content="text/html" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css"
    />
  </head>
  <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 class="swiper-pagination"></div>

      <!-- 任意の矢印ボタン用要素 -->
      <div class="swiper-button-prev"></div>
      <div class="swiper-button-next"></div>

      <!-- 任意のスクロールバー用要素 -->
      <div class="swiper-scrollbar"></div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js"></script>
    <script>
      const swiper = new Swiper(".swiper", {
        loop: true,

        // ページネーション（スライダーの位置を示す丸いドット）用の要素を指定
        pagination: {
          el: ".swiper-pagination",
        },

        // 矢印ボタン用の要素を指定
        navigation: {
          nextEl: ".swiper-button-next",
          prevEl: ".swiper-button-prev",
        },
      });
    </script>
  </body>
</html>

不細工なスライダーで、正しく動いているか疑わしいかもしれない。わかりやすさを心掛けて、公式ドキュメントで解説されている最小限のコードに留めた（本当は綺麗に装飾するのがただ面倒だった）。とはいえ、矢印をポチポチするとスライダーは正しく動くはずである。

Swiperのドキュメントの読み方

モジュールと、それに付随するCSSをインポートする。この構造を踏まえていれば、ドキュメントも読みやすい。

ドキュメントは、以下のような順番でまとめられている。

  1. HTMLの構造
  2. モジュールごとのCSSファイルの種類
  3. コア機能に指定できるパラメータ
  4. コア機能で使えるメソッドとプロパティ
  5. イベント
  6. 各モジュール

例えば自動再生機能が欲しければ、モジュールの一覧からそれっぽい名称（この場合はAutoplay）を探し、必要なパラメータを把握する。その上で、該当のCSSファイルとモジュールをインポートし、Sipwerコンストラクタに必要なパラメータを渡せば良い。

なお、各モジュールのパラメータは、モジュールと同名（ただしすべて小文字）のプロパティに設定する。

js
// Swiperのコア機能とAutoplayモジュールをインポート
import Swiper from "swiper";
import { Autoplay } from "swiper/modules";
// コア機能とAutoplayモジュールのCSSファイルをインポート
import "swiper/css";
import "swiper/css/autoplay";

const swiper = new Swiper(".swiper", {
  modules: [Autoplay],
  loop: true,
  // モジュールのパラメータは、モジュールと同名（ただしすべて小文字）のプロパティに設定する
  autoplay: {
    delay: 3000,
  },
});

こんな感じである。

参考資料