Getting Started

基本的な使い方

インストール

Splideを導入するには、以下に示す4つの方法があります。

NPM

NPMを利用して最新版をインストールしてください(推奨)。

$ npm install @splidejs/splide

ホスティング

ファイルをサーバに直接配置してインストールすることができます。以下のリンクからパッケージをダウンロードしてください。

ダウンロード

dist/jsディレクトリ下にあるsplide.min.jsファイルを<script>で読み込みます。

<script src="path-to-the-file/splide.min.js"></script>
HTML

CDNの利用

自身のサーバにホストする代わりに、CDNからファイルを参照する事もできます。

jsDelivr

バージョンアップによる意図せぬ不具合を避けるため、本番用には"latest"キーワードを避け、特定のバージョン番号を指定することを強くおすすめします。

インテグレーション用パッケージ

React、VueまたはSvelteプロジェクトの場合、専用のインテグレーション用パッケージが用意されています。

CSSのインポート

使用するCSSファイルを選び、サイトに読み込みます。

読み込むファイルの選択

dist/cssあるいはdist/css/themesディレクトリの中に、いくつかのCSSがファイルが入っています。 これらには以下のような違いがあります。

ファイル説明
splide.min.cssすべてのスタイルが含まれています。 内容はsplide-default.min.cssと同じです。
splide-[theme].min.cssすべてのスタイルが含まれています。
splide-core.min.cssスライダーを構築するための最低限のスタイルのみ含まれています。

スライダーの見た目を完全にカスタマイズしたい場合は、splide-core.min.cssを選ぶとよいでしょう。このファイルは必要最低限のスタイルしか含まれていないため、セレクタによる不要な上書き作業を避けることができます。そうでない場合は、splide.min.cssあるいはsplide-[theme].min.cssから選んでください。

スタイルシートへのリンク

ファイルを選んだら<link>タグを用いてサイトにリンクします。

<!-- サーバに置いたファイルを参照 -->
<link rel="stylesheet" href="path-to-the-file/splide.min.css">
<!-- またはCDN上のファイルを参照 -->
<link rel="stylesheet" href="url-to-cdn/splide.min.css">
HTML

バンドラがCSSに対応している場合は、スクリプトから直接読み込んでもかまいません。

// デフォルトのテーマ
import '@splidejs/splide/css';
// または、そのほかのテーマ
import '@splidejs/splide/css/skyblue';
import '@splidejs/splide/css/sea-green';
// あるいは、コアスタイルのみ
import '@splidejs/splide/css/core';
JavaScript

HTML

次に、スライダーをHTMLで記述していきます。

HTMLの構成はおおまかに2種類存在し、配置するスライダーが直接ページのメインコンテンツと関係するかどうかによって決まります。たとえば、バナー、ギャラリー、商品一覧などのように、ページの主たるコンテンツの一部である場合は、以下のようなマークアップを記載してください。

<section class="splide" aria-label="Splideの基本的なHTML">
<div class="splide__track">
<ul class="splide__list">
<li class="splide__slide">Slide 01</li>
<li class="splide__slide">Slide 02</li>
<li class="splide__slide">Slide 03</li>
</ul>
</div>
</section>
HTML

もしスライダーが装飾目的であったり、あるいは直接メインコンテンツとはならない場合は(たとえば<aside>で記載されるような内容であるなら)、以下のマークアップを使用します。

<div class="splide" role="group" aria-label="Splideの基本的なHTML">
<div class="splide__track">
<ul class="splide__list">
<li class="splide__slide">Slide 01</li>
<li class="splide__slide">Slide 02</li>
<li class="splide__slide">Slide 03</li>
</ul>
</div>
</div>
HTML

.splide__slideクラスが付与された各スライドの中には、画像、テキストなどの任意のコンテンツを入れることができます。この構成では<section><ul>および<li>を用いていますが、<div>で置き換えても動作します。

どのような構成であっても、スライダーのルート要素には簡潔なラベルを付けてください。もしスライダーに対して適切な見出しが「目に見える形」で存在する場合は、aria-labelではなくaria-labelledbyで両者を関連付けてください。

<section class="splide" aria-labelledby="carousel-heading">
<h2 id="carousel-heading">Splideの基本的なHTML</h2>
<div class="splide__track">
<ul class="splide__list">
<li class="splide__slide">Slide 01</li>
<li class="splide__slide">Slide 02</li>
<li class="splide__slide">Slide 03</li>
</ul>
</div>
</section>
HTML

より詳しい内容については、Structureを参照してください。

Splideの適用

最後に、記述したHTMLに対してSplideを適用します。

import文による導入

ESMの場合は、Splideクラスを読み込んでインスタンス化し、mount()メソッドを呼んでください。コンストラクタの引数には対象を特定するためのCSSセレクタ、あるいはエレメントそのものを渡します。

import Splide from '@splidejs/splide';
new Splide( '.splide' ).mount();
JavaScript

このとき、mount()を呼ぶのを忘れないようにしてください(忘れると何も表示されません😥)。

グローバル空間のSplideを使用

Splideを<script>で読み込んだ場合、どこからでもSplideクラスにアクセスすることができます。

<script>
new Splide( '.splide' ).mount();
</script>
HTML

初期化は、対象となる要素がすでにロードされている必要があります。<body>を閉じる直前に初期化処理を記載する場合は問題ありませんが、<head>など別の場所に記載する場合は、次のようにしてロードタイミングを監視してください。

<script>
document.addEventListener( 'DOMContentLoaded', function() {
var splide = new Splide( '.splide' );
splide.mount();
} );
</script>
HTML

複数のスライダー

Splideのインスタンスは、一つにつき一つのスライダーしか作れません。セレクタにクラス名を指定してコンストラクタに渡したとしても、Splideは最初にマッチした要素にしかスライダーを適用しません。複数のスライダーを作成する場合は、それぞれに対してインスタンスを作成してください。

new Splide( '#slider1' ).mount();
new Splide( '#slider2' ).mount();
new Splide( '#slider3' ).mount();
JavaScript

あるいは、以下のようにまとめて初期化することもできます。

var elms = document.getElementsByClassName( 'splide' );
for ( var i = 0; i < elms.length; i++ ) {
new Splide( elms[ i ] ).mount();
}
JavaScript