Vue ガイド

@reelkit/vue でスライダーを作る方法を説明します。

基本のスライダー

<Reel> コンポーネントはコアのスライダーコントローラーを包みます。#item スロットで各スライドを仮想化して描画し、マウントされるのは表示中のスライドだけです。

ReelIndicator

スライダー内の現在位置を示す、Instagram 風の進捗インジケーターを表示する任意のコンポーネントです。<Reel> の中に置くと、Vue の provide/inject を通じて親の count と active の値に自動で接続するので、手でつなぐ必要はありません。

命令的 API — テンプレート参照

<Reel> コンポーネントは、テンプレート参照を通じて ReelExpose インターフェースを公開します。ref() で参照を保持し、next()、prev()、goTo() などの命令的なメソッドを呼びます。

横方向

左右にスワイプするスライダーにするには direction="horizontal" を指定します。インジケーターの向きも合わせてください。

サイズの自動計測

size プロップは任意です。省略すると、<Reel> は ResizeObserver でコンテナーを自動計測し、CSS で決まるレイアウトに合わせます。コンテナーのサイズは親要素で決める必要があります（flex、grid、または CSS での明示的な寸法など）。

トランジション

スライドのアニメーションをカスタマイズするには transition プロップを渡します。ReelKit にはツリーシェイキングできる 5 つのトランジションが用意されています。slideTransition（デフォルト）、fadeTransition、flipTransition、cubeTransition、zoomTransition です。

ループモード

loop プロップで、終わりのない循環ナビゲーションを有効にします。スライダーは最後のスライドから最初のスライドへ（逆も同様に）継ぎ目なく戻ります。

イベントコールバック

<Reel> コンポーネントは、スライダーの状態を追跡するためのイベントをいくつか発行します：

ナビゲーション

組み込みの操作方法：

URL の状態

useOverlayUrlState はオーバーレイ用の URL 状態コントローラーを作り、そのまま返します。それを <LightboxUrlOverlay> の :controller プロップに渡します。開閉状態はアドレスバーが持つので、結び付けられたオーバーレイは自分で開き、開く操作は通常リンクになります。存在しないパラメーターへの最初の書き込みは履歴エントリーを 1 つ積み、以降の書き込みはそれを置き換えるので、ページを送っても戻るボタンが埋もれることはありません。コントローラーは手元に残しておき、value／position を読んだり、set(null) でプログラムから閉じたりするのに使います。これは、オーバーレイがスライドの切り替え時に内部で使っているのと同じ低レベルの書き込みです。

オプションのオブジェクトは param、codec、locator（3 つとも必須）と、任意の adapter を受け取ります。codec と locator は同じ Id を共有する対なので、単純な ?photo=3 のギャラリーなら ...urlIndexKey(() => props.images.length) を展開すれば、両方が一度に返されます。urlIndexKey はパラメーターをスライドのインデックスに対応させ、getter が返す現在の件数で範囲を制限するので、古いまたは範囲外の ?photo=99 は拒否され、指されていないスライドを開く代わりに URL から自動で取り除かれます。数値ではなく getter を渡してください。Vue の setup は一度しか実行されないので、取り込んだ長さはページングされたフィードが伸びると古くなります。内部では createIndexLocator（locator の側）を包み、indexCodec と組み合わせています。ページングされたフィードや識別子で指すギャラリーは、代わりに独自の codec と locator の対を用意します。すべてのオプションの表は Vue API リファレンス にあります。

#item スロットのパターン

React のレンダープロップの代わりに、Vue ではスコープ付きの #item スロットを使います。これによって仮想化が可能になり、マウントされるのは表示中のスライドだけです。スロットのスコープは 3 つのプロパティを提供します：

コンポーザブル

@reelkit/vue には、よくあるオーバーレイの場面のためのコンポーザブルがあります：

ポイント

• Composition API

  Reel、ReelIndicator、コンポーザブルを <script setup> に直接インポートします。プラグインの登録は必要ありません

• スコープ付きの #item スロット

  React の itemBuilder プロップに相当する Vue の仕組みで、なじみのあるテンプレート構文のまま仮想化が使えます

• テンプレート参照

  命令的なナビゲーションには ref<ReelExpose>() を使います。イベントコールバックは必要ありません

• @after-change

  (index, rangeIndex) を発行します。UI を更新するために現在のインデックスを追跡します

• provide/inject のコンテキスト

  ReelIndicator は Vue の provide/inject で親の Reel に自動で接続します。props を手でたどって渡す必要はありません

パフォーマンスのヒント

• スライドのテンプレートを軽く保つ

  #item スロットは表示中のスライドごと（通常は同時に 3 枚）に実行されます。中で重い計算や深い入れ子の構造を使わないでください。

• 端に近づいたらデータを読み込む

  @after-change でユーザーが終わりに近づいたことを検知し、スライドが尽きる前に次のバッチを取得します。これで無限スクロールのフィードが作れます。

• 命令的な状態には ref を使う

  ReelExpose の参照と現在のインデックスを Vue の ref() に保持すると、不要な再描画なしに細かなリアクティビティが得られます。

• スクロールするページではホイールを無効にする

  スクロールするレイアウトの中にスライダーを埋め込むときは、ページのスクロールを奪わないよう :enable-wheel="false" を指定してください。