Swiper Element（Webコンポーネント）

Swiperウェブコンポーネントは、Swiperバージョン9以降で利用できます。

カスタム要素はすべての主要なブラウザーとほとんどすべてのフレームワークでサポートされています。

インストール

Swiper Elementをプロジェクトにインストールする方法はいくつかあります。

NPMからインストールして登録する

SwiperをNPMからインストールできます。

$ npm install swiper

ノードモジュールからSwiperカスタム要素をインポートするときは、手動で登録する必要があります。これは1回だけ行う必要があり、Swiperカスタム要素をグローバルに登録します。

// import function to register Swiper custom elements
import { register } from 'swiper/element/bundle';
// register Swiper custom elements
register();

CDNからSwiperカスタム要素

<script>タグを使用してWebサイトに直接追加することで、CDNからインストールすることもできます。

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

この場合、自動的に登録され、register()を呼び出す必要はありません。

用法

Swiper Elementをインストールすると（ノードモジュールを介してregister()を呼び出すか、スクリプトタグを含めることで）、使用可能な2つのウェブコンポーネント（カスタム要素）があります。

<swiper-container> - すべての参数を定義するSwiperのメイン要素
<swiper-slide> - Swiperスライド要素

<swiper-container>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

属性としてのパラメータ

すべてのSwiperパラメータは、<swiper-container>のkebab-case属性の形式で使用できます。たとえば、

<swiper-container slides-per-view="3" speed="500" loop="true" css-mode="true">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

オブジェクトとして渡されるすべてのパラメータは、[key]-[subkey]="value"の形式の属性としても渡すことができます。

たとえば、そのような構成

new Swiper('.swiper', {
  slidesPerView: 3,
  grid: {
    rows: 3,
  },
  mousewheel: {
    forceToAxis: true,
  },
});

このように渡す必要があります。

<swiper-container
  slides-per-view="3"
  grid-rows="3"
  mousewheel-force-to-axis="true"
>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

プロパティとしてのパラメータ

より複雑なパラメータオブジェクト（ブレークポイントなど）を使用するさらに複雑な場合は、すべてのパラメータをHTMLElementプロパティとして渡すことができます。

ここでは、すべての必須パラメータを渡すまでSwiperの初期化を防止するには、init="false"属性を追加する必要があります。

<!-- Add init="false" -->
<swiper-container init="false">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>
<script>
  // swiper element
  const swiperEl = document.querySelector('swiper-container');

  // swiper parameters
  const swiperParams = {
    slidesPerView: 1,
    breakpoints: {
      640: {
        slidesPerView: 2,
      },
      1024: {
        slidesPerView: 3,
      },
    },
    on: {
      init() {
        // ...
      },
    },
  };

  // now we need to assign all parameters to Swiper element
  Object.assign(swiperEl, swiperParams);

  // and now initialize it
  swiperEl.initialize();
</script>

パラメーターの更新

Swiper のパラメーターは、Swiper 要素の属性または HTMLElement プロパティーを直接変更することで更新できます（プロップで初期化された場合）。

<swiper-container slides-per-view="1">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

<button>Update</button>

<script>
  const swiperEl = document.querySelector('swiper-container');
  const buttonEl = document.querySelector('button');

  buttonEl.addEventListener('click', () => {
    // if it was initialized with attributes
    swiperEl.setAttribute('slides-per-view', '3');

    // or if it was initialized with props
    swiperEl.slidesPerView = 3;
  });
</script>

Swiper インスタンスへのアクセス

初期化された Swiper インスタンスは、Swiper の HTMLElement の swiper プロップとして使用できます。

<swiper-container slides-per-view="1">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

<button>Slide Next</button>

<script>
  const swiperEl = document.querySelector('swiper-container');
  const buttonEl = document.querySelector('button');

  buttonEl.addEventListener('click', () => {
    swiperEl.swiper.slideNext();
  });
</script>

イベント

すべての Swiper イベントはネイティブ DOM イベントとして利用できますが、小文字の名前と swiper プレフィクスを使用します（events-prefix パラメーターで設定可能）。たとえば、slideChange は swiperslidechange になります。

すべてのイベントハンドラーの引数は event.detail に配列として渡されます。

<swiper-container>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

<script>
  const swiperEl = document.querySelector('swiper-container');

  swiperEl.addEventListener('swiperprogress', (event) => {
    const [swiper, progress] = event.detail;
  });

  swiperEl.addEventListener('swiperslidechange', (event) => {
    console.log('slide changed');
  });
</script>

他のライブラリーやネイティブイベントと衝突しないように、events-prefix 属性/パラメーターを使用して、発行されたイベント名にプレフィクスを追加することもできます。

<swiper-container events-prefix="swiper-">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

<script>
  const swiperEl = document.querySelector('swiper-container');

  swiperEl.addEventListener('swiper-progress', (event) => {
    const [swiper, progress] = event.detail;
  });

  swiperEl.addEventListener('swiper-slidechange', (event) => {
    console.log('slide changed');
  });
</script>

ページャー、ナビゲーション、スクロールバー

これらのモジュール要素をパラメーター（例：scrollbar.el、pagination.el）で渡さない場合は、モジュールパラメーターが指定されていれば自動的にレンダリングされます。

<!-- enable navigation, pagination, scrollbar -->
<swiper-container navigation="true" pagination="true" scrollbar="true">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

Lazy

読み込み画像を遅延させる場合は、それぞれのスライドにレイジープリローダー要素を追加する必要があります。swiper-slide コンポーネントは、lazy="true" 属性を追加することでこれを実行します。

<swiper-container>
  <!-- lazy="true" attribute will automatically render the preloader element -->
  <swiper-slide lazy="true">
    <img src="..." loading="lazy" />
  </swiper-slide>
  <swiper-slide lazy="true">
    <img src="..." loading="lazy" />
  </swiper-slide>
  <swiper-slide lazy="true">
    <img src="..." loading="lazy" />
  </swiper-slide>
  ...
</swiper-container>

仮想スライド

Swiper web コンポーネントでは、仮想スライドを使用する際に 2 つのオプションがあります。

1 つ目のオプションは、virtual.slides 配列にスライドを渡すことですが、Swiper 要素を初期化するには要素のプロパティーを使用する必要があります。

<swiper-container init="false"></swiper-container>
<script>
  // swiper element
  const swiperEl = document.querySelector('swiper-container');

  // swiper parameters
  const swiperParams = {
    virtual: {
      // virtual slides
      slides: ['Slide 1', 'Slide 2', 'Slide 3'],
    },
  };

  // assign all parameters to Swiper element
  Object.assign(swiperEl, swiperParams);

  // and now initialize it
  swiperEl.initialize();
</script>

バージョン 9 以降、Swiper の仮想スライドは、もともと DOM 内でレンダリングされたスライドで動作します。初期化時に DOM からそれらを削除し、キャッシュし、その後必要なスライドを再利用します。

<!-- it is enough to add virtual="true" attribute -->
<swiper-container virtual="true">
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

Thumbs

バージョン 9 では、thumbs.swiper パラメーターもサムスワイパーの CSS セレクターを受け付けます。そのため、どちらも Swiper 要素で行うには、以下を使用できます。

<!-- main swiper, pass thumbs swiper as CSS selector -->
<swiper-container thumbs-swiper=".my-thumbs"> ... </swiper-container>

<!-- thumbs swiper -->
<swiper-container class="my-thumbs"> ... </swiper-container>

Controller

Thumbs と同様に、バージョン 9 の Controller も CSS セレクターを受け付けます。

<swiper-container class="swiper-1" controller-control=".swiper-2">
  ...
</swiper-container>

<swiper-container class="swiper-2" controller-control=".swiper-1">
  ...
</swiper-container>

スタイルの注入

シャドウ DOM スコープにスタイルを追加する必要がある場合は、injectStyles または injectStylesUrls パラメーターを使用できます（例）。

<swiper-container init="false"> ... </swiper-container>
<script type="module">
  import { register } from 'swiper/element/bundle';

  register();

  const swiperEl = document.querySelector('swiper-container');

  const params = {
    // array with CSS styles
    injectStyles: [
      `
      :host(.red) .swiper-wrapper {
        background-color: red;
      }
      `,
    ],

    // array with CSS urls
    injectStylesUrls: ['path/to/one.css', 'path/to/two.css'],
  };

  Object.assign(swiperEl, params);

  swiperEl.initialize();
</script>

コアバージョンとモジュール

追加のモジュールなしで利用できる Swiper 要素のコアバージョンもあります。

これはノードモジュールからインポートできます。

// import function to register Swiper Core custom elements
import { register } from 'swiper/element';
// register Swiper custom elements
register();

モジュールを追加するには、モジュールスクリプトを含めるために通常どおりmodulesパラメータを使用する必要があり、モジュールスタイルをグローバルに追加し、モジュールスタイルをシャドウDOMに挿入する必要もあります

<swiper-container init="false"> ... </swiper-container>

<script>
  import { register } from 'swiper/element';
  import { Navigation, Pagination } from 'swiper/modules';

  register();

  const swiperEl = document.querySelector('swiper-container');

  const params = {
    modules: [Navigation, Pagination],
    // inject modules styles to shadow DOM
    injectStylesUrls: [
      'path/to/navigation-element.min.css',
      'path/to/pagination-element.min.css',
    ],
  };

  Object.assign(swiperEl, params);

  swiperEl.initialize();
</script>

次のエレメントモジュールスタイルインポートを使用できます

swiper/element/css/a11y - A11yモジュールに必要なスタイル
swiper/element/css/autoplay - Autoplayモジュールに必要なスタイル
swiper/element/css/controller - Controllerモジュールに必要なスタイル
swiper/element/css/effect-cards - Cards Effectモジュールに必要なスタイル
swiper/element/css/effect-coverflow - Coverflow Effectモジュールに必要なスタイル
swiper/element/css/effect-creative - Creative Effectモジュールに必要なスタイル
swiper/element/css/effect-cube - Cube Effectモジュールに必要なスタイル
swiper/element/css/effect-fade - Fade Effectモジュールに必要なスタイル
swiper/element/css/effect-flip - Flip Effectモジュールに必要なスタイル
swiper/element/css/free-mode - Free Modeモジュールに必要なスタイル
swiper/element/css/grid - Gridモジュールに必要なスタイル
swiper/element/css/hash-navigation - Hash Navigationモジュールに必要なスタイル
swiper/element/css/history - Historyモジュールに必要なスタイル
swiper/element/css/keyboard - Keyboardモジュールに必要なスタイル
swiper/element/css/manipulation - Manipulationモジュールに必要なスタイル
swiper/element/css/mousewheel - Mousewheelモジュールに必要なスタイル
swiper/element/css/navigation - Navigationモジュール必要なスタイル
swiper/element/css/pagination - Paginationモジュール必要なスタイル
swiper/element/css/parallax - Parallaxモジュールに必要なスタイル
swiper/element/css/scrollbar - Scrollbarモジュールに必要なスタイル
swiper/element/css/thumbs - Thumbsモジュールに必要なスタイル
swiper/element/css/virtual - Virtualモジュールに必要なスタイル
swiper/element/css/zoom - Zoomモジュールに必要なスタイル

スロット

既定では、すべてのswiper-container子要素は.swiper-wrapperエレメントの子要素としてレンダリングされます。前または後に要素を追加する必要がある場合は、2つのスロットを使用できます

container-start - .swiper-wrapperの前にレンダリングされます
container-end - .swiper-wrapperの後にレンダリングされます

<swiper-container>
  <div slot="container-start">Rendered before wrapper</div>
  <div slot="container-end">Rendered after wrapper</div>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
  ...
</swiper-container>

パーツ

スタイル設定に使用できる次のCSSパーツがあります

container - <div class="swiper">のスタイル
wrapper - <div class="swiper-wrapper">のスタイル
button-prev - 前のナビゲーションボタンのスタイル<div class="swiper-button-prev">
button-next - 次のナビゲーションボタンのスタイル<div class="swiper-button-next">
pagination - 前のページネーションコンテナーのスタイル<div class="swiper-pagination">
- bullet - ページネーション項目スタイル
- bullet-active - アクティブなページネーション項目スタイル
scrollbar - - スクロールバーコンテナーのスタイル<div class="swiper-scrollbar">

たとえば

swiper-container::part(bullet-active) {
  background-color: red;
}

パラメータを登録する

9.1.0以降、既定のSwiperパラメータに含まれない新しい（または追加の）パラメータを登録する新しいグローバルwindow.SwiperElementRegisterParams関数が追加されています。Swiperパラメータを拡張するカスタムプラグインを使用してSwiperエレメントを使用する場合に必要となる場合があります。

// register swiper-container HTMLElement props to be treated as Swiper parameters
window.SwiperElementRegisterParams(['foo', 'bar']);

const swiperEl = document.querySelector('swiper-container');

Object.assign(swiperEl, {
  foo: 1,
  bar: 2,
});

swiperEl.initialize();

Reactでの使用

Reactは、まだ（バージョン18時点では）Webコンポーネントを完全にサポートしていません。そのため、使用方法は基本的にHTMLでの使用と同じです。

import { useRef, useEffect } from 'react';
import { register } from 'swiper/element/bundle';

register();

export const MyComponent = () => {
  const swiperElRef = useRef(null);

  useEffect(() => {
    // listen for Swiper events using addEventListener
    swiperElRef.current.addEventListener('swiperprogress', (e) => {
      const [swiper, progress] = e.detail;
      console.log(progress);
    });

    swiperElRef.current.addEventListener('swiperslidechange', (e) => {
      console.log('slide changed');
    });
  }, []);

  return (
    <swiper-container
      ref={swiperElRef}
      slides-per-view="3"
      navigation="true"
      pagination="true"
    >
      <swiper-slide>Slide 1</swiper-slide>
      <swiper-slide>Slide 2</swiper-slide>
      <swiper-slide>Slide 3</swiper-slide>
      ...
    </swiper-container>
  );
};

Vueでの使用

Vueは、属性をプロパティとして渡したり、カスタムイベントをリスニングしたりする機能を含め、Webコンポーネントを完全にサポートしています。

<template>
  <swiper-container
    :slides-per-view="3"
    :space-between="spaceBetween"
    :centered-slides="true"
    :pagination="{
      hideOnClick: true
    }"
    :breakpoints="{
      768: {
        slidesPerView: 3,
      },
    }"
    @swiperprogress="onProgress"
    @swiperslidechange="onSlideChange"
  >
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
  </swiper-container>
</template>

<script>
  import { register } from 'swiper/element/bundle';

  register();

  export default function () {
    setup() {
      const spaceBetween = 10;
      const onProgress = (e) => {
        const [swiper, progress] = e.detail;
        console.log(progress)
      };

      const onSlideChange = (e) => {
        console.log('slide changed')
      }

      return {
        spaceBetween,
        onProgress,
        onSlideChange,
      };
    }
  }
</script>

Svelteでの使用

Svelteは、属性をプロパティとして渡したり、カスタムイベントをリスニングしたりする機能を含め、Webコンポーネントを完全にサポートしています。

<script>
  import { register } from 'swiper/element/bundle';

  register();

  const spaceBetween = 10;
  const onProgress = (e) => {
    const [swiper, progress] = e.detail;
    console.log(progress)
  };
  const onSlideChange = (e) => {
    console.log('slide changed')
  }
</script>

<swiper-container
  slides-per-view={3}
  space-between={spaceBetween}
  centered-slides={true}
  pagination={{
    hideOnClick: true,
  }}
  breakpoints={{
    768: {
      slidesPerView: 3,
    },
  }}
  on:swiperprogress={onProgress}
  on:swiperslidechange={onSlideChange}
>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <swiper-slide>Slide 3</swiper-slide>
</swiper-container>

Solidでの使用

Solidは、属性をプロパティとして渡したり、カスタムイベントをリスニングしたりする機能を含め、Webコンポーネントを完全にサポートしています。

import { register } from 'swiper/element/bundle';

register();

export default () => {
  const spaceBetween = 10;
  const onProgress = (e) => {
    const [swiper, progress] = e.detail;
    console.log(progress);
  };
  const onSlideChange = (e) => {
    console.log('slide changed');
  };
  return (
    <swiper-container
      slides-per-view={1}
      space-between={spaceBetween}
      centered-slides={true}
      pagination={{
        hideOnClick: true,
      }}
      breakpoints={{
        768: {
          slidesPerView: 3,
        },
      }}
      onSwiperprogress={onProgress}
      onSwiperslidechange={onSlideChange}
    >
      <swiper-slide>Slide 1</swiper-slide>
      <swiper-slide>Slide 2</swiper-slide>
      <swiper-slide>Slide 3</swiper-slide>
    </swiper-container>
  );
};

次のステップ

ご覧のとおり、SwiperをWebサイトまたはアプリに統合するのは本当に簡単です。そのため、次に実行する手順は次のとおりです。

すべてのSwiper APIとそれらの制御方法についてさらに詳しく知るには、APIドキュメントに進みます。
使用可能なデモを見てください。
Swiperに関する質問がある場合は、StackOverflowまたはSwiper Discussionsで質問してください。
バグが見つかった場合は、GitHubで問題を作成してください。
サポートをお探しの場合は、Swiper Patrons向けのプライベートDiscordサポートチャットルームがあります。

GitHubでこのページを編集します。