Lightbox

@reelkit/react-lightbox を使った、フルスクリーンの画像と動画のギャラリーのコンポーネントです。

ライブデモを見る →

機能

インストール

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

クイックスタート

LightboxOverlay コンポーネントは画像をフルスクリーンで表示します。LightboxItem オブジェクトの配列を渡し、null を取りうるインデックスで表示を制御します。

ライブデモ

サムネイルをクリックするとギャラリーが開きます。矢印キーかスワイプで移動してください。

動画スライド（オプトイン）

動画のサポートは完全にオプトインで、ツリーシェイキングできます。画像だけを使う場合、バンドルは 1 バイトも増えません。useVideoSlideRenderer をインポートし、その戻り値を LightboxOverlay につないでください。読み込み状態、サウンドの管理、動画のライフサイクルはフックが自動で処理します。

カスタマイズ

独自のコントロール

renderControls で、デフォルトの閉じるボタン、カウンター、フルスクリーン切り替えを置き換えます。公開されているサブコンポーネントと組み合わせてください：

独自の情報オーバーレイ

renderInfo でデフォルトのタイトルと説明のグラデーションを置き換えるか、renderInfo={() => null} を渡して完全に非表示にします：

独自のナビゲーション

renderNavigation で、デフォルトの前後の矢印を置き換えます：

独自のスライド

renderSlide でスライドの内容を完全に独自のものにします。デフォルトの画像スライドに戻すには null を返します：

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

ギャラリーはスライドごとの読み込み中とエラーの状態を追跡します。読み込み中はスピナーを、失敗したメディアには壊れた画像のアイコンを表示します。エラーになった URL はキャッシュされるので、再訪すると再試行せずにすぐエラーを表示します。

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

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

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

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

URL の状態

ライブデモを見る →

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

フックは 1 つのオプションのオブジェクトを受け取り、UrlStateController（set、index、value を持ちます）を返します。プログラムから制御するために手元に残してください。set はオーバーレイが内部で使う低レベルの書き込みです（スライドの切り替えと、set(null) で閉じる処理）。プログラムからオーバーレイを操作することもでき、set(index) はパラメーターへ移動するのと同じように開きます。ただし、開く操作にはリンクを使うほうがよいでしょう。href は共有でき、新しいタブで開け、戻るボタンで閉じられます。ハンドラーなしで、すべてがそのまま手に入ります。

useOverlayUrlState のすべてのオプション（param、adapter、codec、locator）は React API リファレンス を参照してください。

LightboxUrlOverlay 自体が受け取るのは controller（必須）、任意の onClose、そして LightboxOverlay が受け取るすべての見た目と挙動の props（images、ariaLabel、transitionFn、各レンダープロップなど）です。isOpen はありません。

• 開くと履歴エントリーを 1 つ使います。スライドを送るとそれを置き換えるので、100 回スワイプしてもエントリーは増えず、1 回戻れば必ずギャラリーから出られます。戻るとギャラリーが閉じ、写真は戻りません。
• ?photo=3 のような共有リンクは、そのスライドでギャラリーを開きます。ページと一緒に届いたリンクを閉じると、サイトから離れるのではなく、その場でパラメーターを取り除きます。
• 戻るで閉じるのは、アプリ内から開いた場合だけです。 リンクがエントリーを積んだので、戻るとギャラリーの前へ戻ります。新しいタブで直接開いた共有リンクには前の履歴がないので、ブラウザーの戻るではサイトを離れます。閉じるボタンか Escape なら、その場でパラメーターを取り除いてギャラリーにとどまります。同梱のルーターアダプターは同じページでのリンクの push を保証します。エントリーの経緯を伝えられない独自のアダプターでもその場で閉じる動作になり、履歴にページの重複が残ります。その場合 1 回戻っても何も起きないように見えますが、再び開くことはありません。
• どのスライドも指さないパラメーター（古いブックマークや手で書き換えた値）は、開けないスライドをアドレスバーが指したままにならないよう、URL から取り除かれます。

ルーターを使うアプリでは、アダプターを渡します。 履歴に直接書き込むとルーター自身の位置情報が古くなり、次のナビゲーションでパラメーターが消えます。

開く操作はリンクです。 開閉状態が URL にあるので、サムネイルはただのリンクで、クリックハンドラーはいりません。新しいタブで開く、アドレスをコピーする、ホバーでプレビューするといったブラウザー本来の動作がそのまま使えます。ルーターを使うアプリでは、クライアント側で遷移するよう、ルーターのリンクを使ってください。

共有リンクには安定した識別子を使いましょう。 インデックスは位置なので、ブックマークした ?photo=3 はリストが並べ替えられると別の画像を開きます。urlStableIdKey は各アイテムの安定した id で指し、現在のリストを走査します。よくあるケースは 1 回の呼び出しで済みます。

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

別のフィールド（slug）で指したい場合や、locateAsync で無限フィードをページングしたい場合は、codec／locator を自分で作ります：

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

• 読み込み方はあなた次第です。目的の位置まで連続したページを取得しても、その 1 枚だけを取得して追加してもかまいません。URL は位置ではなく識別子で指すので、findIndex はアイテムが置かれた場所を返します。
• locateAsync が保留中のあいだ、ギャラリーは閉じたままで、パラメーターはそのまま残るので、ディープリンクは取得のあいだも失われません。null か reject でパラメーターは取り除かれます。
• URL が変わったあと、閉じたあと、アンマウントしたあとに届いた答えは破棄されます。遅い取得が、誰も求めていないスライドを開くことはありません。
• 保留中は何も描画されません。その読み込み状態はすでにページが持っているので、独自のスケルトンを描画してください。
• タイムアウトはありません。ギャラリーには自分の長さがわからないからです。ページングが尽きたら null で決着をつけてください。そうしないとオーバーレイは閉じたままになります。
• locateAsync が返したものが正です。取得したばかりのデータのインデックスとして、images を読み直さずにそのまま使われます。

API リファレンス

LightboxOverlay の Props

LightboxOverlayProps

LightboxUrlOverlay の Props

LightboxUrlOverlayProps

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

コールバック

Reel の Props（引き継ぎ）

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

型

LightboxItem

ControlsRenderProps

NavigationRenderProps

SlideRenderProps

InfoRenderProps

サブコンポーネント

renderControls で独自のコントロールを組み立てるための、再利用できるサブコンポーネントです。

CloseButton

デフォルトの X の閉じるボタンです。

Counter

「1 / 3」と表示する画像のカウンターです。

FullscreenButton

フルスクリーンの切り替えボタンです（最大化／最小化のアイコン）。

SoundButton

動画スライド用のミュート切り替えボタンです（Volume2／VolumeX のアイコン）。useVideoSlideRenderer の renderControls には自動で含まれます。独自のコントロールの中で単独で使う場合は、useSoundState でサウンドの状態にアクセスしてください。

フック

useVideoSlideRenderer

オプトインの動画サポートのためのフックです。renderSlide、renderControls、SoundProvider を返します。オーバーレイを SoundProvider で包み、描画関数を渡してください。

useFullscreen

ブラウザー間で動くフルスクリーンの状態を管理するフックです。

トランジション

任意の TransitionTransformFn を transitionFn プロップで渡します。使うトランジションだけをインポートすれば、残りはバンドラーがツリーシェイキングします。省略すると slideTransition になります。

独自のトランジション関数

独自の TransitionTransformFn を書き、transitionFn で渡します。シグネチャはコアのスライダーのトランジションと同じです。

CSS クラス

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

テーマ設定

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

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

アクセシビリティ

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

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

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