Angular Lightbox

@reelkit/angular-lightbox で作られた、Angular 用のフルスクリーンの画像と動画のギャラリーです。

ライブデモを見る →

機能

インストール

基本的な使い方

スタイルとスタンドアロンの RkLightboxOverlayComponent を、コンポーネントの imports 配列にインポートします。

テンプレートスロット

4 つのテンプレートスロットのディレクティブで、コンポーネントを複製せずにオーバーレイの UI を自由にカスタマイズできます。各スロットは厳密に型付けされたコンテキストのオブジェクトを受け取ります。

動画のサポート

動画スライドを使うには、rkLightboxSlide のテンプレートスロットと RkLightboxVideoSlideComponent でオプトインする必要があります。画像だけでよいギャラリーに動画プレイヤーをバンドルしないための設計です。

フルスクリーン

フルスクリーンの状態を監視したり切り替えたりするには、@reelkit/angular の fullscreenSignal、requestFullscreen、exitFullscreen を使います。

URL の状態

ライブデモを見る →

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

インジェクションコンテキスト（フィールドの初期化子かコンストラクター）の中で呼んでください。すぐに接続し、DestroyRef で解放されるので、ギャラリーが開いたままコンポーネントが破棄されてもリスナーは残りません。すべてのオプションは Angular API リファレンス にあります。

• 開くと履歴エントリーを 1 つ 積みます。スライドを送るとそれを 置き換え るので、N 回移動してもエントリーは増えず、1 回戻れば必ずギャラリーから出られます。
• 戻るで閉じるのは、アプリ内からギャラリーを開いた場合だけです（リンクがエントリーを積んだ場合）。新しいタブで直接開いた共有リンクには前の履歴がないので、ブラウザーの戻るではサイトを離れます。✕ ボタンか Escape なら、その場でパラメーターを取り除いてページにとどまります。
• どのスライドも指さないパラメーター（古いブックマークや手で書き換えた値）は、開けないスライドを指したままにならないよう、URL から取り除かれます。
• テンプレートスロットはそのまま使えます。URL のコンポーネントが 6 つのスロットの問い合わせを自分で行い、それぞれのテンプレートをギャラリーへ渡すので、rkLightboxControls などは rk-lightbox-overlay の中と同じように置けます。
• ルーティングを使うアプリケーションでは、Router の上に作ったアダプターを渡してください。Router の裏で履歴を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます。

ルーターを使うアプリでは、アダプターを渡します。 Router の裏で履歴を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます。Router の上にアダプターを作り、adapter として渡してください：

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

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

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

無限またはページングされたギャラリー。 locate は同期なので、読み込み済みの画像にしか答えません。20 件を読み込んだフィードの 400 番目の画像への共有リンクは見つかりません。locateAsync はフォールバックで、locate が見つけられなかったときだけ呼ばれます。必要なページを読み込み、その識別子が最終的に持ったインデックスを返してください。保留中のあいだギャラリーは閉じたままで、パラメーターはそのまま残るので、ディープリンクは取得のあいだも失われません。null か reject でパラメーターは取り除かれます。

RkLightboxUrlOverlayComponent の入力

rk-lightbox-overlay の入力をすべて受け取りますが、isOpen の代わりにコントローラーを使います。出力は同じ closed と slideChange です。閉じるのは URL が行うので、closed は仕組みではなく通知です。

RkLightboxOverlayComponent の入力

RkLightboxOverlayComponent の出力

LightboxItem インターフェース

テンプレートスロットのコンテキスト型

トランジション

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

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

rkLightboxSlide のテンプレートスロットを使う場合、読み込み状態を報告するための 3 つのライフサイクルのコールバックがコンテキストで使えます。ギャラリーはスライドごとの状態を追跡し、それに応じてスピナーかエラーアイコンを表示します。コンテンツのプリローダーは壊れた URL をキャッシュするので、失敗したスライドを再訪しても再試行はしません。

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

rkLightboxSlide でコールバックをつなぐ

独自の読み込みテンプレート

rkLightboxLoading ディレクティブで、デフォルトのスピナーを置き換えます。

独自のエラーテンプレート

rkLightboxError ディレクティブで、デフォルトのエラーアイコンを置き換えます。

CSS クラス

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

テーマ設定

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

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

アクセシビリティ

オーバーレイのルートはモーダルダイアログ（role="dialog"、aria-modal="true"）です。ariaLabel 入力を指定すると、スクリーンリーダーの読み上げが変わります。デフォルトは「Image gallery」です。各スライドは role="group"、aria-roledescription="slide"、そして画像のタイトルと位置から作られる aria-label を持ちます。

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

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