初心者向け Swiper jsの使い方 覚書

Twitterに勝手に表示されるおすすめ投稿で「Swiperの使い方がわからない!」という叫びと、それに共感する声をたくさん見たので、ざっくりとした基本の使い方と、実際使用して遭遇したエラーなどをまとめておくことにします。

Swiperの解説サイトは日本語でも山ほどあるので、基本的な性能説明やインストール方法みたいな部分は省略します。そこは各自で調べてください。

Swiperを動かす

「Swiperが動かない」と言っている人もいたのでここから書きます。

Swiperを使う場合、基本的なコードは、下のようになります( 公式サイトから引用 )。

<head>
<!-- たまにCSS読み込まずに「動かない〜!」って言ってる人もいます -->
<link rel="stylesheet" href="https://unpkg.com/swiper@8/swiper-bundle.min.css"
/>
</head>
<body>

<!-- Swiper -->
<div class="swiper">

 <!-- .swiper-wrapper と .swiper-slide は必須 -->
  <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><!-- 「prev」ボタンがいるとき -->
  <div class="swiper-button-next"></div><!-- 「next」ボタンがいるとき -->
  <div class="swiper-scrollbar"></div><!-- スクロールバーがいるとき -->

</div>
<!-- // Swiper -->

<script type="module">
import Swiper from 'https://unpkg.com/swiper@8/swiper-bundle.esm.browser.min.js'

const swiper = new Swiper( '.swiper' , {} )
</script>
</body>

HTMLコードの解説

Swiper部分を包括している「 .swiper 」が、Swiperを適用させるときの目印となっています。

スライド本体となる、 .swiper-wrapper と .swiper-slide のクラス名は変更してはいけません。

これを勝手に「.mySlide」とかにして動かなくなっている人が前にいました。

「divじゃなくて、ulとliタグで作りたい」とかなら勝手に変えてくれれば良いですが、class名やその階層を変えると動作しないか表示がおかしくなります。

.swiper-wrapper .swiper-slide は必須で、他の .swiper-pagenation などはSwiperのオプションで使うのであれば記述。オプションを使わないのであれば書きません。

HTMLにページネーションを書いても、Swiperのオプションを指定していなければ表示されません。当たり前ですが念の為に書いておきます。

JSコードの解説

Swiperの指定は、

const 適当な名前 = new Swiper( 'Swiperを指定する要素' , { オプション } )

これだけです。

コンストラクタなので、オプション違いで複数のSwiperを使うときは

const swiper1 = new Swiper('#samle' , {OPTIONS} )
const swiper2 = new Swiper('#test'  , {OPTIONS} )

のように複数作成すればOKです。あとで出てきますが、サムネイル連動させるときなどは2つのSwiperを指定します。

Swiperを使う要素はidでもclassでも好きなセレクタで動きます。当然ながら対象が複数あれば全てにSwiperが適用されます。下のcodepenのように、オプションが必要なければ何も指定しなくて良いです。

See the Pen Untitled by Takashi Abe (@TakeshiAbe) on CodePen.

オプションは次項でよく使うものをいくつか紹介しますが、全て紹介するのは大変なので気になる方は公式のSwiper Demosで確認してください。

Swiperでよく使うオプション

Pagination

スライドにページネーーション(スライド下のドット)を表示します。el で指定した要素(.swiper-pagination)の位置にページネーションを生成します。

オプションの指定要素がHTMLコードに見つからないと表示されませんので、HTMLにちゃんとページネーションを書く・クラス名が間違っていないか にご注意。

const demo = new Swiper('demo', {
  pagination: {
    el: ".swiper-pagination", //ページネーションを表示させる要素を指定 
    clickable: true,  //ページネーションをクリック可能要素にするか否か
  }
})

Navigation

ナビゲーション(左右の矢印)を表示します。

デフォルトでは無味乾燥な矢印が表示されますので、変更したいときはCSSで編集します。

ページネーションと同じくHTMLコードに対応した要素が必要です。

const demo = new Swiper('demo', {
  navigation: {
    nextEl: ".swiper-button-next",  //次へ を表示する要素
    prevEl: ".swiper-button-prev",  //前へ
  }
})

Slides Per View

一度に表示させるスライドの枚数を指定します。

const demo = new Swiper('demo', {
  slidesPerView: 5 
  }
})

Responsive breakpoints

レスポンシブ設定を行なう場合に必要です。設定はmin-width(px) で行います。先ほどのSlides Per Viewと組み合わせたサンプルが以下です。

const demo = new Swiper('demo' , {
  slidesPerView: 1,  // 599px以下は1枚表示
  breakpoints: {
    600: {
      slidesPerView: 2  //600px ~ 1024px は2枚
    },
    1025: {
      slidesPerView: 3  //1025px以上は3枚
    }
  }
})

Autoplay

スライドを自動再生する場合、何ミリ秒でスライドを動かすか(delay)、スライドにマウスや指があたったときに自動再生を解除するかどうか(disableOnInteraction)を指定します。

const demo = new Swiper('demo' , {
  autoplay : {
    delay: 3000 ,  //3秒ごとにスライドが動く
    disableOnInteraction : false //マウスホバーしても自動再生が継続
  }
})

Thumbs

ページネーションの代わりにサムネイルスライドを使用します。サムネイルスライドもHTMLに記述し、両方をSwiperで動かす必要があります。

注意点としては、先にサムネイルSwiperを設定しておくこと。

const thumbSlides = new Swiper('thumb' , { OPTIONS } )

const mainSlides  = new Swiper('main'  , {
  thumbs: {
    swiper: thumbSlides
  }
})

watchSlidesProgress

サムネイルスライドが、メインのスライドの動きに連動するかどうかをtrue / falseで指定します。

サムネイルのSwiperに設定します。先ほどのコードに追記してみると以下のようになります。

const thumbSlides = new Swiper('thumb' , { 
  watchSlidesProgress: true
})

const mainSlides  = new Swiper('main'  , {
  thumbs: {
    swiper: thumbSlides
  }
})

SwiperのCSSを編集する

Swiperのオプションを全部使うことなどまず無いと思いますが、当然、CDNで用意されているSwiperのCSSは全てのオプションに対応できるようになっています。

ここから必要なものだけ抽出・編集して、ローカルに上げ直すだけでも、結構スライドの描画速度が速くなります(Swiperフォントの読み込み有無が影響大きいと思う)ので、私はいつもそうしています。

別におすすめはしませんが、描画速度が気になる方は試していてください。

Swiperで起こりうるエラー

ソースが読まれる順番にもよると思いますが、Swiperは表示範囲のサイズが明確に定義されていないときエラーを起こしやすいです。

ほぼ間違いなくエラーとなるのは、gridレイアウトで作成していて、swiperの表示範囲を「 1fr 」にしているとき

Swiperが永遠にサイズを計算し続けるという致命的なエラーが起こります。gridレイアウトのときはpxなりvwなりで明確なwidthを指定しましょう。

grid-template-columns: 300px 1fr ;