Reel Player

@reelkit/react-reel-player を使った、Instagram Reels／TikTok 風のフルスクリーン動画プレイヤーのコンポーネントです。

ライブデモを見る →

機能

インストール

スタイルのインポートを忘れないでください：

クイックスタート

ReelPlayerOverlay コンポーネントはフルスクリーンのプレイヤーを描画します。ContentItem オブジェクトの配列を渡し、isOpen で表示を制御します。

ライブデモ

サムネイルをクリックするとフルスクリーンのプレイヤーが開きます。Escape か閉じるボタンで戻ります。

カスタマイズ

ジェネリックなコンテンツ型

BaseContentItem を拡張して、独自のデータ型を使います：

独自のスライドオーバーレイ

組み込みのスライドオーバーレイを、スライドごとの独自の内容に置き換えます：

メディア以外のスライド

renderSlide で独自の内容（たとえば CTA カード）を差し込みます。デフォルトに戻すには null を返します：

独自のコントロール

再利用できるサブコンポーネントに、自分の追加要素を組み合わせます：

独自のタイムライン

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

独自のナビゲーション

独自のネストしたナビゲーション

複数メディアのスライド（横方向のカルーセル）の中にある左右の矢印を、独自のナビゲーションに置き換えます：

独自のネストしたスライド

renderNestedSlide で、複数メディアのカルーセル内の個々のスライドをカスタマイズします。props.defaultContent でデフォルトの ImageSlide／VideoSlide を包むか、完全に置き換えます：

URL の状態

ライブデモを見る →

ReelPlayerUrlOverlay は、開閉状態をアドレスバーに持つ別のコンポーネントです。@reelkit/react の useOverlayUrlState でコントローラーを作り、controller として渡します。パラメーターがスライドを指すとプレイヤーは自分で開き、パラメーターがなくなると閉じます。リンクは共有でき、戻るボタンはページを離れる代わりにプレイヤーを閉じます。

useOverlayUrlState のすべてのオプション（param、adapter、codec、locator）は React API リファレンス にあります。手順は React ガイド にあります。

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

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

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

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

ルーターを使うアプリでは、アダプターを渡します。 ルーターの裏で history.pushState を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます：

安定したリンク。 インデックスは位置なので、ブックマークした ?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 リファレンス

ReelPlayerOverlayProps の Props

ReelPlayerOverlayProps<T>

ReelPlayerUrlOverlay の Props

ReelPlayerUrlOverlayProps<T>

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

コールバック

Reel の Props（引き継ぎ）

これらの props は、内部の Reel コンポーネントに渡されます。

型

BaseContentItem

ジェネリックの制約となる型です。これを拡張すると、ReelPlayerOverlay で独自のデータ型を使えます。

ContentItem

MediaItem

MediaType

ControlsRenderProps<T>

NavigationRenderProps

SlideRenderProps<T>

NestedSlideRenderProps

SlideOverlayProps

ImageSlideProps

VideoSlideProps

CloseButtonProps

SoundButtonProps

TimelineBarProps

TimelineRenderProps<T>

サブコンポーネント

独自のレンダープロップで組み合わせるために公開されている、再利用できる部品です：

CloseButton

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

SoundButton

単独のサウンド切り替えボタンです。SoundProvider の中に置く必要があります（ReelPlayerOverlay が自動で用意します）。

TimelineBar

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

SlideOverlay

作者、説明、いいねを表示するデフォルトのグラデーションのオーバーレイです。コンテンツに必要なフィールドがあれば自動で描画されます。置き換えるか非表示にするには renderSlideOverlay を使います。

ImageSlide

遅延読み込みとデフォルトの object-fit: cover を備えた画像スライドです。renderSlide の中で使い、独自のスタイルの画像スライドを組み立てます。

VideoSlide

iOS で音声を途切れさせないための共有 <video> 要素、ポスターのフレーム、位置の記憶、読み込み表示を備えた動画スライドです。SoundProvider の中に置く必要があります（ReelPlayerOverlay が自動で用意します）。

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

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

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

renderSlide を使う場合は、これらのコールバックを呼んで読み込み表示を制御します：

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

デフォルトの波のローダーとエラーアイコンを、独自のコンポーネントに置き換えます：

タイムライン

オーバーレイは、アクティブな動画の上に組み込みの再生タイムラインバーを描画します。timeline プロップで表示条件を決めます：

• 'auto'（デフォルト）：アクティブなメディアが timelineMinDurationSeconds（デフォルト 30）より長い動画のときに表示します。単一動画のスライドにも複数メディアのカルーセルにも使え、バーはアクティブなネストしたアイテムに追従し、画像では非表示になります。
• 'always'：アクティブなスライドに動画があれば常に表示します。
• 'never'：表示しません。renderTimeline で独自のバーを作ってください。

--rk-reel-timeline-* の CSS カスタムプロパティ（高さ、色、カーソルの大きさ）でテーマを変えます。完全に独自のシークバー、タイムコード、進捗表示を作るには renderTimeline を使います。コールバックは、内部の TimelineController に支えられた timelineState を受け取ります。

サウンドコンテキスト

独自の実装では、サウンドの状態にアクセスできます：

CSS クラス

CSS クラスはすべて通常のクラス（CSS Modules ではありません）なので、@reelkit/react-reel-player/styles.css のあとに読み込むスタイルシートで、詳細度の高いセレクターを使って指定できます。色、サイズ、z-index を変えるなら、下の テーマ設定 で説明している CSS カスタムプロパティを使ってください。まさにそのためのものです。

テーマ設定

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

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

アクセシビリティ

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

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

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