English

React Splide

Reactインテグレーション

概要

React SplideはSplideをReactプロジェクトに導入するためのパッケージです。

v0.7.0以上のドキュメントです。

インストール

最新版をNPMから取得してください。

$ npm install @splidejs/react-splide

使用方法

コンポーネント

パッケージから、SplideとSplideSlideの2つのコンポーネントをインポートします。

import { Splide, SplideSlide } from '@splidejs/react-splide';
JavaScript

これらを、以下のようにしてレンダリングしてください。

<Splide aria-label="お気に入りの写真">
  <SplideSlide>
    <img src="image1.jpg" alt="Image 1"/>
  </SplideSlide>
  <SplideSlide>
    <img src="image2.jpg" alt="Image 2"/>
  </SplideSlide>
</Splide>
JSX

CSS

CSSファイルを選択し、インポートしてください。<link>タグで読み込んでも構いません。

// デフォルトのテーマ
import '@splidejs/react-splide/css';


// または、ほかのテーマ
import '@splidejs/react-splide/css/skyblue';
import '@splidejs/react-splide/css/sea-green';


// あるいは、コアスタイルのみ
import '@splidejs/react-splide/css/core';
JavaScript

構成のカスタマイズ

<Splide>はトラック要素をレンダリングしますが、hasTrackと<SplideTrack>を用いれば、別々に管理できます。例えば、次の2つのコンポーネントは、全く同じ結果を出力します。

import { Splide, SplideTrack, SplideSlide } from '@splidejs/react-splide';


<Splide>
  <SplideSlide>...</SplideSlide>
</Splide>


<Splide hasTrack={ false }>
  <SplideTrack>
    <SplideSlide>...</SplideSlide>
  </SplideTrack>
</Splide>
JSX

<SplideTrack>を<Splide>から分離することで、矢印やページネーション、あるいはそのほかのコントロール要素を自由に配置できるようになります。例えば、Splideはデフォルトで、矢印をトラック要素の直前にレンダリングしますが、プレースホルダを用いてこの位置を指定できます。

<Splide hasTrack={ false } aria-label="...">
  <div className="custom-wrapper">
    <SplideTrack>
      <SplideSlide>...</SplideSlide>
    </SplideTrack>


    <div className="splide__arrows" />
  </div>
</Splide>
JSX

または、独自の矢印も定義できます。

<Splide hasTrack={ false } aria-label="...">
  <SplideTrack>
    <SplideSlide>...</SplideSlide>
  </SplideTrack>


  <div className="splide__arrows">
    <button className="splide__arrow splide__arrow--prev">Prev</button>
    <button className="splide__arrow splide__arrow--next">Next</button>
  </div>
</Splide>
JSX

同じようにして、自動再生のトグルボタンや、プログレスバーの表示も行えます。

<Splide hasTrack={ false } aria-label="...">
  <SplideTrack>
    <SplideSlide>...</SplideSlide>
  </SplideTrack>


  <div className="splide__progress">
    <div className="splide__progress__bar" />
  </div>


  <button class="splide__toggle" type="button">
 	  <span class="splide__toggle__play">Play</span>
 	  <span class="splide__toggle__pause">Pause</span>
  </button>
</Splide>
JSX

あるいは：

<Splide hasTrack={ false } aria-label="...">
  <div className="custom-wrapper">
    <button class="splide__toggle" type="button">
      <span class="splide__toggle__play">Play</span>
      <span class="splide__toggle__pause">Pause</span>
    </button>


    <div className="splide__progress">
      <div className="splide__progress__bar" />
    </div>


    <SplideTrack>
      <SplideSlide>...</SplideSlide>
    </SplideTrack>
  </div>
</Splide>
JSX

Props

<Splide>はDOMAttributes以外のHTMLAttributesを受け付け、ルート要素に展開します。例えば、classNameや'aria-label'を設定できます。

<Splide className="my-carousel" aria-label="お気に入りの写真">
</Splide>
JSX

加えて、以下で述べるいくつかのプロパティを取ります。

options

options: Options

Splideのオプション をオブジェクトで渡します。

<Splide
  options={ {
    rewind: true,
    width : 800,
    gap   : '1rem',
  } }
>
</Splide>
JSX

このプロパティはリアクティブであり、値を更新するとスライダー自身も更新されますが、読み取り専用のオプションは変更しないでください。

tag

tag: 'div' | 'section' | 'header' | 'footer' | 'nav' = 'div'

ルート要素に使用するタグを変更します。後方互換のため、初期値は'div'ですが、'section'を推奨します。

もしheader、footerならびにnavを使用する場合は、適切なランドマークロールも同時に指定する必要があります。そうしないと、不適切なアクセシビリティツリーが出来上がります。

<Splide tag="section"></Splide>
JSX

extensions

Extensions: Record<string, ComponentConstructor>

エクステンションをオブジェクト形式で追加します。

transition

Transition: ComponentConstructor

トランジションコンポーネントを上書きます。

hasTrack

hasTrack: boolean

トラック要素をレンダリングするかどうかを決めます。

イベント

Splideコンポーネント経由で、Splide内のすべてのイベントにハンドラを登録できます。ハンドラの関数名はイベント名から生成されますが、"on"接頭子の付加、キャメルケースへの変換、コロンの削除という3つの処理が行われます。たとえば、"arrows:mounted"は"onArrowsMounted"に変換されます。

実際のイベントリストは、このソースから確認できます。

<Splide onArrowsMounted={ ( splide, prev, next ) => { console.log( prev, next ) } }>
JSX

なお、ハンドラの第一引数は常にSplideのインスタンスで、オリジナルの引数はそのあとに続きます。

Splideインスタンスの取得

Splideインスタンスを取得し、直接操作したい場合は、React.createRefメソッドまたはuseRefフックによるRefオブジェクトを介して取得できます。

<Splide ref={ ref }>
  ...
</Splide>
JSX

ReactがSplideコンポーネントをマウントした後で、ref.current.splideからインスタンスを取得してください（マウント前はundefinedです）。

componentDidMount() {
  if ( this.ref.current ) {
    console.log( this.ref.current.splide.length );
  }
}


// または
useEffect( () => {
  if ( ref.current ) {
    console.log( ref.current.splide.length );
  }
} );
JSX

サンプル

以下に簡単な例を示します。

import React from 'react';
import { Splide, SplideSlide } from '@splidejs/react-splide';


export default () => {
  return (
    <Splide
      options={ {
        rewind: true,
        gap   : '1rem',
      } }
      aria-label="お気に入りの写真"
    >
      <SplideSlide>
        <img src="image1.jpg" alt="Image 1"/>
      </SplideSlide>
      <SplideSlide>
        <img src="image2.jpg" alt="Image 2"/>
      </SplideSlide>
      <SplideSlide>
        <img src="image3.jpg" alt="Image 3"/>
      </SplideSlide>
    </Splide>
  );
}
JSX

このページで、実際に動作している例を見ることができ、それぞれのソースコードは以下の場所に置いてあります。

v3からの移行方法

v3からv4へ移行するには、次の手順を参考にしてください。

  1. 破壊的変更に目を通します
  2. もしこれらの変更が既存のスライダーに影響を与える場合は、v3からv4への移行を参考に「スライダー要素」以外を修正します
  3. 下に記載した「廃止されたプロパティ」を利用している場合は、構成のカスタマイズを参考に、コンポーネントをアップデートします
  4. ExtensionsプロパティをextensionsにTransitionプロパティをtransitionに変更します
  5. CSSを更新します（古いパスのままでも動作しますが、短縮パスも利用可能になりました）
  6. （任意）あたらしく追加されたi18nを翻訳します
  7. （任意）aria-labelまたはaria-labelledbyをそれぞれのスライダーに挿入します

以下のプロパティは廃止されました。

  • hasSliderWrapper
  • hasAutoplayProgress
  • hasAutoplayControls
  • playButtonLabel
  • pauseButtonLabel
  • renderControls