API リファレンス

Lightbox はスライドごとの meta 型についてジェネリックです。<Lightbox slides={...} /> は渡した slides から T を推論します。

コンテンツ

Prop	Type	Default	説明
`slides`	`Slide<T>[]`	—	表示する画像（必須）。
`open`	`boolean`	`false`	ビューワーの表示状態。バインド可能。
`index`	`number`	`0`	アクティブなスライドのインデックス。バインド可能 — 開いている間に書き込むと移動します。

挙動

Prop	Type	Default	説明
`zoom`	`ZoomOptions`	`{ max: 2, doubleTap: 2, wheel: true }`	ズームの上限。実寸に対する倍率で指定します。
`dismiss`	`DismissOptions`	`{ drag: true, threshold: 0.22, pinch: true }`	ドラッグで閉じる操作とピンチで閉じる操作。
`tapAction`	`'toggle-ui' \| 'close' \| 'none'`	`'toggle-ui'`	画像をシングルタップしたときの動作。
`backdropClose`	`boolean`	`true`	画像の外側をクリックするとビューワーが閉じます。
`wheel`	`'zoom' \| 'navigate' \| 'none'`	`'zoom'`	ホイールの動作。トラックパッドのピンチは常にズームします。
`keyboard`	`boolean`	`true`	Escape / 矢印キー / `+` / `-` を処理します。
`history`	`boolean`	`false`	履歴エントリを追加し、プラットフォームの戻るジェスチャーでビューワーを閉じられるようにします。
`loop`	`boolean`	`false`	端を越えてループします。スライドが 3 枚以上ならシームレスに、それ未満なら折り返しでループします。
`preload`	`readonly [number, number]`	`[1, 1]`	アクティブなスライドの前後 `[before, after]` でマウントし続けるスライド数。

外観

Prop	Type	Default	説明
`chrome`	`boolean`	`true`	組み込み UI を描画します。ヘッドレスなビューワーにするには `false` を設定します。
`counter`	`boolean`	`true`	`n / total` のカウンターを表示します。
`zoomButton`	`boolean`	`true`	ズーム切り替えボタンを表示します。
`showCaption`	`boolean`	`true`	代替テキストのキャプションを表示します。
`backdropOpacity`	`number`	`0.9`	完全に開いたときの背景の不透明度（`0`–`1`）。
`slideGap`	`number`	`16`	隣接するスライド間の間隔（px）。
`transitionMs`	`number`	`260`	開く / 閉じるトランジションの時間（ms）。
`labels`	`LightboxLabels`	—	組み込み UI 向けのアクセシブルなラベル（i18n）。

高度な設定

Prop	Type	Default	説明
`origin`	`(index: number) => HTMLElement \| OriginRect \| null`	—	開く / 閉じるトランジションの起点となる要素 / 矩形。
`container`	`HTMLElement`	`document.body`	ビューワールートのポータル先。
`viewer`	`Viewer<T> \| null`	`null`	開いている間のコアビューワーのインスタンス。バインド可能（`bind:viewer`）。

イベント

最もよく使うイベントはコールバックプロップとして公開されています。

Prop	Payload	発火するタイミング
`onopen`	`{ index }`	開くトランジションが開始したとき。
`onchange`	`{ index, slide }`	アクティブなスライドが変わったとき。
`onload`	`{ index, slide }`	スライドのフル品質画像のデコードが完了したとき。
`onerror`	`{ index, slide, error }`	スライドのフル品質画像の読み込みに失敗したとき。
`onzoomintent`	`{ index, slide }`	ユーザーがスライドを初めてズームしたとき（スライドごとに一度）。
`onclose`	`{ index }`	閉じるトランジションが開始したとき。
`onclosed`	—	閉じるトランジションが完了したとき（クリーンアップして安全）。

それ以外のイベントについては、viewer.on(name, listener) でコアビューワーを購読してください。コアイベントの全一覧はフレームワークに依存しないコアを参照してください。

スニペット

Snippet	Argument
`toolbar`	`LightboxContext<T>`
`caption`	`LightboxContext<T> & { expanded: boolean; toggle(): void }`

どちらも型付けされたコンテキストを受け取ります。

Member	Type	説明
`viewer`	`Viewer<T>`	コアビューワー。高度な操作に使います。
`index`	`number`	アクティブなスライドのインデックス。
`slide`	`Slide<T> \| undefined`	アクティブなスライド（`meta` を含む）。
`count`	`number`	スライドの総数。
`close`	`() => void`	ビューワーを閉じます。
`next` / `prev`	`() => void`	隣接するスライドへ移動します。
`goTo`	`(index: number) => void`	指定したスライドへ移動します。
`updateSlide`	`(index, patch) => void`	スライドをその場で更新します。
`setKeyboardEnabled`	`(enabled: boolean) => void`	独自のモーダルを表示している間、キー操作の処理を一時停止 / 再開します。

命令的な操作

ほとんどの操作は宣言的に行えます。bind:open、bind:index、そしてリアクティブな slides 配列です。それ以外の操作については、bind:this でコンポーネントインスタンスをバインドします。

<script lang="ts">
  import { Lightbox } from 'picola/svelte';
  let lightbox: Lightbox;
</script>

<Lightbox bind:this={lightbox} bind:open {slides} />
<button onclick={() => lightbox.next()}>Next</button>

Method	説明
`close()`	閉じるトランジションを開始します。
`next()` / `prev()`	隣接するスライドへ移動します。
`goTo(index)`	指定したスライドへ移動します。
`updateSlide(index, patch)`	スライドをその場で更新します。
`getViewer()`	コアの `Viewer` インスタンス。閉じているときは `null`。

Slide 型

Field	Type	説明
`src`	`string`	フル品質画像の URL（必須）。
`placeholder`	`string`	`src` の読み込み中に即座に表示される低解像度の代替画像。
`width` / `height`	`number`	実寸のピクセル寸法（事前に分かっている場合）。
`alt`	`string`	アクセシブルな説明。キャプションにも使われます。
`srcset` / `sizes`	`string`	`src` のレスポンシブ候補。
`meta`	`T`	スライドごとの任意のデータ。`Slide<T>` によって完全に型付けされます。

アクセシブルなラベル

labels プロパティは組み込み UI をローカライズします。すべてのフィールドは省略可能です。

Field	説明
`dialog`	ビューワーダイアログのアクセシブルな名前。
`close`	閉じるボタン。
`next`	次のスライドへの矢印。
`prev`	前のスライドへの矢印。
`zoom`	ズーム切り替えボタン。
`caption`	キャプション切り替えボタン。

エクスポート

picola/svelte

コンポーネント — Lightbox、ToolbarButton
ヘルパー — createGalleryOrigins
型 — Slide、Viewer、SlideView、ViewerEvents、ViewerStatus、 ZoomOptions、DismissOptions、TapAction、OriginRect、LightboxContext、 LightboxLabels、GalleryOrigins

picola（コア） — createViewer、Viewer、そしてアダプタの基盤となっている低レベルのプリミティブ（attachGestures、PanZoom、decodeImage、trapFocus、bindHistory、fitScale、panBounds、rubberBand、zoomAroundPoint）に加えて、オプションとイベントの完全な型が含まれます。

Lightbox のプロパティ