Vue Reel Player

@reelkit/vue-reel-player で作られた、Vue 3 用の Instagram／TikTok 風のフルスクリーン縦型メディアプレイヤーです。

ライブデモを見る →

機能

インストール

アプリのエントリー（または任意のコンポーネント）でスタイルシートを 1 回インポートします：

基本的な使い方

サムネイルのグリッドを描画し、クリックしたインデックスでオーバーレイを開きます。v-model:is-open をバインドすると、ユーザーがボタン、ジェスチャー、Escape でプレイヤーを閉じたときにも、親の ref が同期されます。

スコープ付きスロット

8 つのスコープ付きスロットで、プレイヤーの UI のどの部分でも置き換えられます。それぞれが厳密に型付けされたスコープのオブジェクトを受け取ります。渡さなかったスロットはデフォルトが使われます。

独自のタイムライン

#timeline スロットで、組み込みの再生バーを独自のシーク UI に置き換えます。スロットが呼ばれるのは、オーバーレイの表示条件がデフォルトのバーを描画する場合（同じ timeline モードと timelineMinDurationSeconds）だけなので、それを実装し直す必要はありません。ルート要素で .rk-reel-timeline クラスを使えば、下端に沿った配置、セーフエリアの余白、タッチ端末での間隔を引き継げます。

独自のコンテンツ型

ReelPlayerOverlay は、コンテンツのアイテムの形についてジェネリックです。BaseContentItem を拡張すれば任意のデータモデルを使え、対応するスロットのスコープの型をインポートすれば、スロットのバインディングも厳密に型付けされます：

ほかのすべてのスロットでも同じパターンです。対応するスコープの型（SlideSlotScope、ControlsSlotScope、NavigationSlotScope、NestedSlideSlotScope、LoadingSlotScope）をインポートし、分割代入に型を付けてください。

URL の状態

ライブデモを見る →

@reelkit/vue の useOverlayUrlState でコントローラーを作り、ReelPlayerUrlOverlay に controller として渡します。プレイヤーを持つのはアドレスバーなので、パラメーターがスライドを指すと開き、パラメーターがなくなると閉じます。開くと履歴エントリーを 1 つ積み、スライドが変わるたびにそれを置き換えるので、フィードを送ってもエントリーは増えず、1 回戻れば必ず出られます。URL の深さはコントローラーのキーで決まります。一軸の urlIndexKey は投稿だけを指し（?reel=3）、二軸の urlIndexTwoAxisKey は複数メディアの投稿の内側のメディアのインデックスも運びます（?reel=3.2）。アプリごとにキーを 1 つ選んでください。2 つの通信形式は互いに読み替えられません。これは ReelPlayerOverlay とは別のコンポーネントなので、開閉状態を決めるものはそれぞれ 1 つだけです。is-open のモデルか、URL の controller のどちらかで、両方ではありません。

ルーターを使うアプリでは、ルーターに連動したアダプターを渡して、ナビゲーションの信頼できる情報源をルーターだけに保つべきです。ルーターの裏で履歴を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます。@reelkit/vue/vue-router-url-adapter の useVueRouterUrlAdapter が、Vue Router 用に用意されたアダプターです。

useOverlayUrlState のすべてのオプションは Vue API リファレンス にあります。

• 開くと履歴エントリーを 1 つ 積みます。フィードをスワイプするとそれを 置き換え るので、N 回スワイプしてもエントリーは増えず、1 回戻れば必ずプレイヤーから出られます。戻るとプレイヤーが閉じ、スライドは戻りません。
• 戻るで閉じるのは、アプリ内から開いた場合だけです（リンクがエントリーを積んだ場合）。新しいタブで直接開いた共有リンクには前の履歴がないので、ブラウザーの戻るではサイトを離れます。✕ ボタンか Escape なら、その場でパラメーターを取り除いてページにとどまります。
• ディープリンク ?reel=3 は、読み込み時にそのスライドでプレイヤーを開きます。
• どのスライドも指さないパラメーター（古いブックマークや手で書き換えた値）は、開けないスライドをアドレスバーが指したままにならないよう、URL から取り除かれます。
• URL の深さはコントローラーのキーで決まります。投稿だけなら一軸、複数メディアの投稿の内側の画像のインデックスも運ぶなら二軸（urlIndexTwoAxisKey）です。アプリごとにキーを 1 つ選んでください。形は互いに読み替えられません。

キーは 1 つか 2 つか — URL の深さを選ぶ

同じ ReelPlayerOverlay がどちらの形も扱います。実行時にコントローラーの位置から判別するので、モードを指定するプロップはありません。コントローラーを作るときにキーを選んでください：

2 つの通信形式は意図的に区別されています。二軸のキーは厳密にドットで区切る（3.0 で、3 だけにはしない）ので、一軸のリンクが二軸として読まれることはありません。そのため、アプリでキーを切り替えると、それまでに共有されたリンクは無効になります。形を 1 つ選んで使い続けてください。

安定したリンク。 インデックスは位置なので、ブックマークした ?reel=3 はフィードが並べ替えられると別の投稿を開きます。フィードではそれが例外ではなく普通のことです。urlStableIdKey は各投稿の安定した id で指し、現在のフィードを走査します。よくあるケースは 1 回の呼び出しで済みます。

hashCodec: base64UrlCodec を渡すと、URL の id を base64url でエンコードします。元に戻せる難読化で、暗号学的ハッシュではありません。

別のフィールド（slug）で指したい場合や、locateAsync で無限フィードをページングしたい場合は、codec／locator を自分で作ります。2 つは別の役割です。codec は識別子を URL に書き、locator はその識別子がどこにあるかを探します。

無限フィード。 locate は同期なので、読み込み済みの投稿にしか答えられません。20 件を読み込んだフィードの 400 番目の投稿への共有リンクは見つかりません。locateAsync はフォールバックで、locate が見つけられなかったときだけ呼ばれます。

• locateAsync が保留中のあいだ、プレイヤーは閉じたままで、パラメーターはそのまま残るので、ディープリンクは取得のあいだも失われません。null か reject でパラメーターは取り除かれます。
• URL が変わったあと、閉じたあと、アンマウントしたあとに届いた答えは破棄されます。遅い取得が、誰も求めていないスライドを開くことはありません。
• 保留中は何も描画されません。その読み込み状態はすでにページが持っているので、独自のスケルトンを描画してください。
• タイムアウトはありません。プレイヤーにはフィードの長さがわからないからです。ページングが尽きたら null で決着をつけてください。そうしないとオーバーレイは閉じたままになります。

API リファレンス

ReelPlayerOverlay の Props

ReelPlayerOverlayProps

ReelPlayerUrlOverlay の Props

ReelPlayerUrlOverlayProps

上の props をすべて受け取りますが、is-open の代わりに controller を使います。initial-index は無視されます。スライドはコントローラーの位置で決まるので、一緒に渡した値は開くたびに上書きされます。

イベント

v-model:is-open

v-model:is-open を使うと、1 つのバインディングでオーバーレイを操作できます。明示的なイベントが必要なら、従来の :is-open と @close の組み合わせもそのまま使えます。

型

ContentItem

TimelineBarProps

TimelineSlotScope<T>

MediaItem

サブコンポーネント

独自の #controls、#slide、#slideOverlay のテンプレートに入れて使います。自動再生、ポスターのキャプチャー、サウンドの同期が動き続けるよう、寸法とコールバックはスロットのスコープからそのまま渡してください。

CloseButton

デフォルトのプレイヤーのスタイルを持つ、単独の円形の閉じるボタンです。#controls の中で使います。

SoundButton

ミュートの切り替えボタンです。SoundProvider の中に描画してください（ReelPlayerOverlay が用意します）。アクティブなスライドに動画がないときは非表示です。

TimelineBar

デフォルトの再生シークバーです。いちばん近い TimelineProvider（ReelPlayerOverlay の中に自動でマウントされます）から読み取り、トラック、バッファー済みの範囲、進捗の塗り、シーク用のつまみを描画します。--rk-reel-timeline-* のカスタムプロパティでテーマを変えるか、#timeline スロットで置き換えます。

SlideOverlay

作者、説明、いいねを表示するデフォルトのグラデーションのオーバーレイです。コンテンツにそれらのフィールドがあると描画されます。置き換えるか非表示にするには #slideOverlay スロットを使います。

ImageSlide

遅延読み込みとデフォルトの object-fit: cover を備えた画像スライドです。#slide スロットの中で組み合わせれば、組み込みの挙動を保ったまま画像の描画をカスタマイズできます。

VideoSlide

共有の <video> 要素に支えられた動画スライドです。iOS で音声を途切れさせない処理、ポスターのフレーム、位置の記憶を扱います。SoundProvider の中に描画してください（ReelPlayerOverlay が用意します）。

コンテンツの読み込みとエラー処理

プレイヤーはスライドごとの読み込み中とエラーの状態を追跡します。読み込み中は波のローダーを表示し、壊れたメディアにはエラーアイコンを表示します。失敗した URL はキャッシュされるので、壊れたスライドを開き直しても再試行はしません。

ライフサイクルのコールバック

#slide スロットを使う場合は、スロットのスコープにあるこれらのコールバックを呼んで読み込み表示を制御します：

独自の読み込みとエラーの UI

#loading と #error のスロットで、デフォルトの波のローダーとエラーアイコンを置き換えます：

タイムライン

オーバーレイは、アクティブな動画の上に組み込みの再生タイムラインバーを描画します。timeline プロップで表示条件を決めます。'auto'（デフォルト）はアクティブなメディアが timelineMinDurationSeconds（デフォルト 30）より長い動画のときに表示し、'always' は動画がアクティブなら常に表示し、'never' で無効にします。完全に独自のシークバーには #timeline スロットを使います。そのスコープは、内部の TimelineController に支えられた timelineState を公開します。

テーマは --rk-reel-timeline-* の CSS カスタムプロパティで変えます。

サウンドコンテキスト

ReelPlayerOverlay はルートに SoundProvider をマウントするので、中に描画されたどのコンポーネントでも useSoundState でミュートの状態を読んだり切り替えたりできます。このコンポーザブルは @reelkit/vue-reel-player から再エクスポートされているので、@reelkit/vue を別にインポートする必要はありません。

CSS クラス

CSS クラスは通常のクラス（スコープなし）です。@reelkit/vue-reel-player/styles.css のあとに読み込むスタイルシートで、詳細度の高いセレクターを使えばどれでも上書きできます。色、サイズ、z-index を変えるなら、下の テーマ設定 の CSS カスタムプロパティを使ってください。

テーマ設定

色、サイズ、z-index、トランジションはすべて CSS カスタムプロパティにあります。:root（またはオーバーレイの任意の祖先）で 1 つでも複数でも上書きすれば、コンポーネントのソースに触れずにテーマを変えられます。トークンは @reelkit/react-reel-player と共通なので、上書きはバインディング間でそのまま使えます。

下のスニペットを、@reelkit/vue-reel-player/styles.css のあとに読み込むスタイルシートに入れてください。

アクセシビリティ

オーバーレイのルートはモーダルダイアログ（role="dialog"、aria-modal="true"）です。aria-label プロップを指定すると、スクリーンリーダーの読み上げが変わります。デフォルトは「Video player」です。各スライドは role="group"、aria-roledescription="slide"、aria-label="Slide N of M" を持ちます。

オーバーレイは開くとフォーカスを取り込み、閉じるとトリガーに戻します。Tab と Shift+Tab は中のフォーカス可能な要素を循環し、外へ出たフォーカス（外側のクリック、プログラムからのフォーカス）は引き戻されます。@reelkit/core の captureFocusForReturn と createFocusTrap で実装されています。

キーボードショートカット