English

Vue Splide

Vueインテグレーション

概要

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

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

インストール

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

$ npm install @splidejs/vue-splide

使用方法

コンポーネントの登録

VueSplideプラグインをアプリケーションにインストールしてください。

import { createApp } from 'vue';
import App from './App.vue';
import VueSplide from '@splidejs/vue-splide';
 
const app = createApp( App );
app.use( VueSplide );
app.mount( '#app' );
JavaScript

あるいは、コンポーネントに直接SplideおよびSplideSlideを登録してもかまいません。

<script>
import { Splide, SplideSlide } from '@splidejs/vue-splide';
 
export default defineComponent( {
 components: {
 Splide,
 SplideSlide,
 },
} );
</script>
Vue

登録したら、以下のようにしてスライダーをレンダリングします。

<template>
 <Splide :options="{ rewind: true }" aria-label="お気に入りの写真">
 <SplideSlide>
 <img src="image1.jpg" alt="Sample 1">
 </SplideSlide>
 <SplideSlide>
 <img src="image2.jpg" alt="Sample 2">
 </SplideSlide>
 </Splide>
</template>
Vue

CSS

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

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

構成のカスタマイズ

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

<Splide>
 <SplideSlide>...</SplideSlide>
</Splide>
 
<Splide :has-track="false">
 <SplideTrack>
 <SplideSlide>...</SplideSlide>
 </SplideTrack>
</Splide>
Vue

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

<Splide :has-track="false" aria-label="...">
 <div class="custom-wrapper">
 <SplideTrack>
 <SplideSlide>...</SplideSlide>
 </SplideTrack>
 
 <div class="splide__arrows" />
 </div>
</Splide>
Vue

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

<Splide :has-track="false" aria-label="...">
 <SplideTrack>
 <SplideSlide>...</SplideSlide>
 </SplideTrack>
 
 <div class="splide__arrows">
 <button class="splide__arrow splide__arrow--prev">Prev</button>
 <button class="splide__arrow splide__arrow--next">Next</button>
 </div>
</Splide>
Vue

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

<Splide :has-track="false" aria-label="...">
 <SplideTrack>
 <SplideSlide>...</SplideSlide>
 </SplideTrack>
 
 <div class="splide__progress">
 <div class="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>
Vue

あるいは：

<Splide :has-track="false" aria-label="...">
 <div class="custom-wrapper">
 <button class="splide__toggle" type="button">
 <span class="splide__toggle__play">Play</span>
 <span class="splide__toggle__pause">Pause</span>
 </button>
 
 <div class="splide__progress">
 <div class="splide__progress__bar" />
 </div>
 
 <SplideTrack>
 <SplideSlide>...</SplideSlide>
 </SplideTrack>
 </div>
</Splide>
Vue

Props

options

options: Options

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

<Splide :options="{ rewind: true, gap: '1rem' }"></Splide>
Vue

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

tag

tag: string = 'div'

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

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

<Splide :tag="section"></Splide>
Vue

extensions

extensions: Record<string, ComponentConstructor>

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

transition

transition: ComponentConstructor

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

hasTrack

hasTrack: boolean

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

イベント

Splideコンポーネント経由で、Splide内のすべてのイベントにハンドラを登録できます。ハンドラの関数名はイベント名から生成されますが、先頭に"splide"が付加されます。たとえば、"arrows:mounted"は"splide:arrows:mounted"に変換されます。

<Splide @splide:arrows:mounted="onArrowsMounted"></Splide>
Vue

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

function onArrowsMounted( splide, prev, next ) {
 console.log( splide.length );
}
JavaScript

Splideインスタンスの取得

Splideインスタンスを取得し直接操作したい場合は、Refオブジェクトを利用します。

<template>
 <Splide ref="splide">
 ...
 </Splide>
</template>
 
<script>
import { onMounted, ref } from 'vue';
 
export default defineComponent( {
 setup() {
 const splide = ref();
 
 onMounted( () => {
 if ( splide.value && splide.value.splide ) {
 console.log( splide.value.splide.length );
 }
 } );
 
 return {
 splide,
 }
 },
} );
</script>
Vue

VueがSplideコンポーネントをマウントした後、ref.value.splideを介してインスタンスを取得できます（マウント前はundefinedです）。

サンプル

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

<template>
 <Splide :options="options" aria-label="お気に入りの写真">
 <SplideSlide>
 <img src="image1.jpg" alt="Sample 1">
 </SplideSlide>
 <SplideSlide>
 <img src="image2.jpg" alt="Sample 2">
 </SplideSlide>
 </Splide>
</template>
 
<script>
import { Splide, SplideSlide } from '@splidejs/vue-splide';
import { defineComponent } from 'vue';
 
export default defineComponent( {
 components: {
 Splide,
 SplideSlide,
 },
 
 setup() {
 const options = {
 rewind: true,
 gap : '1rem',
 };
 
 return { options };
 },
} );
</script>
Vue

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

v3からの移行方法

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

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

以下のスロットは廃止されました。

  • beforeTrack
  • afterTrack
  • beforeSlider
  • afterSlider