Lightbox

Features

Встановлення

Не забудьте імпортувати стилі:

Швидкий старт

The LightboxOverlay показує зображення на весь екран. Передайте масив об’єктів LightboxItem і керуйте видимістю через індекс, який може бути null.

Демо наживо

PreviewCode

LightboxPage.tsxStackBlitz

Mountain River

Snowy Peaks

Foggy Forest

Ocean Waves

Autumn Path

Coastal Cliffs

Натисніть мініатюру, щоб відкрити Lightbox. Гортайте стрілками або свайпом.

Слайди-відео (за бажанням)

Підтримка відео вмикається за бажанням і піддається tree-shaking — використання лише зображень нічого не додає до бандла. Імпортуйте useVideoSlideRenderer і передайте повернені значення у LightboxOverlay. Хук сам дає раду станам завантаження, керуванню звуком і життєвим циклом відео.

Customization

Власні елементи керування

Використовуйте renderControls щоб замінити стандартну кнопку закриття, лічильник і перемикач повного екрана. Складайте з експортованих підкомпонентів:

Власний інформаційний оверлей

Використовуйте renderInfo щоб замінити стандартний градієнт із заголовком та описом, або передайте renderInfo={() => null} щоб сховати його повністю:

Власна навігація

Використовуйте renderNavigation щоб замінити стандартні стрілки вперед і назад:

Власний слайд

Використовуйте renderSlide для повністю власного вмісту слайда. Поверніть null щоб лишити стандартний слайд-зображення:

Завантаження вмісту та обробка помилок

Lightbox стежить за станом завантаження й помилок кожного слайда. Поки вміст вантажиться, показується індикатор; для медіа, що не завантажилося, — значок зіпсованого зображення. URL з помилками кешуються, тож повторний перехід одразу показує помилку без нової спроби.

Колбеки життєвого циклу

Якщо ви використовуєте renderSlide, call these callbacks to control the loading indicator:

Власний інтерфейс завантаження та помилок

Замініть стандартний індикатор і значок помилки власними компонентами:

Стан в URL

LightboxUrlOverlay — окремий компонент, стан відкриття якого живе в адресному рядку. Побудуйте контролер через useOverlayUrlState from @reelkit/react і передайте його як controller: галерея відкривається сама, коли параметр називає слайд, і закривається, коли параметр зникає. Посиланнями можна ділитися, а кнопка «назад» закриває галерею, а не виводить зі сторінки.

Хук приймає один об’єкт опцій і повертає UrlStateController (with set, index, value). Keep it for programmatic control: set — низькорівневий запис, який оверлей робить усередині (зміна слайда та set(null) для закриття). Ним же можна керувати оверлеєм програмно: set(index) відкриває його — так само, як перехід за параметром. Але для відкриття краще звичайне посилання: href можна надіслати, відкрити в новій вкладці, а кнопка «назад» його закриє — і все це без жодного обробника.

Full useOverlayUrlState options (param, adapter, codec, locator): see the довіднику API для React.

LightboxUrlOverlay приймає лише controller (обов’язково), необов’язковий onClose, plus every visual and behavior prop LightboxOverlay takes (images, ariaLabel, transitionFn, the render props, and so on) — but no isOpen.

• Відкриття коштує одного запису в історії. Гортання слайдів замінює його, тож сто свайпів не додають жодного — один крок назад завжди виходить із галереї. «Назад» закриває, а не гортає фотографії.
• Надіслане посилання на кшталт ?photo=3 відкриває галерею на цьому слайді. Закриття посилання, що прийшло разом зі сторінкою, прибирає параметр на місці, а не виводить із сайту.
• «Назад» закриває лише тоді, коли ви відкрили галерею всередині застосунку — посилання додало запис, тож «назад» повертає до галереї. За надісланим посиланням у новій вкладці історії позаду немає, тож кнопка «назад» виведе із сайту; кнопка закриття або Escape прибирає параметр на місці й лишає вас у галереї.
• Параметр, який не називає жодного слайда — застаріла закладка, змінене вручну значення, — прибирається з URL, а не лишає в адресному рядку слайд, який не відкриється.

У застосунку з роутером передайте адаптер. Прямий запис в історію лишає власне місцеположення роутера застарілим, і наступна навігація втрачає параметр.

Відкриття — це посилання. Оскільки стан відкриття живе в URL, мініатюра — звичайне посилання без обробника кліку, і вся поведінка браузера дістається безкоштовно: відкрити в новій вкладці, скопіювати адресу, побачити підказку при наведенні. У застосунку з роутером беріть посилання роутера, щоб перехід лишався на клієнті.

Для посилань, якими діляться, краще стабільна ідентичність. Індекс адресує за позицією, тож збережений у закладках ?photo=3 відкриє інше зображення, щойно список перевпорядкують. urlStableIdKey адресує за стабільним id, scanning the live list — one call covers the common case.

Pass hashCodec: base64UrlCodec щоб закодувати id в URL у base64url — оборотне маскування, а не криптографічний хеш.

Адресуєте за іншим полем ( slug), or page an infinite feed with locateAsync, and build the codec/locator самі:

Нескінченні та посторінкові галереї. Синхронний locate відповідає лише за вже завантажені зображення — надіслане посилання на зображення 400 у стрічці, де завантажено 20, нічого не знайде. locateAsync — запасний варіант, що викликається лише коли locate misses.

• Як саме вантажити — ваша справа: тягніть сторінки поспіль до потрібної або лише одне зображення й додайте його. URL адресує за ідентичністю, а не за позицією, тож findIndex поверне те місце, де елемент опинився.
• While locateAsync у процесі, Lightbox лишається закритим, а параметр — недоторканим, тож пряме посилання переживає запит. null або відмова прибирає параметр.
• Відповідь, що приходить після зміни URL, після закриття або після демонтажу, відкидається — повільний запит не відкриє слайд, якого ніхто не просив.
• Поки триває очікування, нічого не рендериться: цей стан завантаження вже належить сторінці, тож малюйте власний скелетон.
• Тайм-ауту немає — Lightbox не може знати, яка галерея завдовжки. Завершуйте значенням null коли сторінки скінчилися, інакше оверлей лишиться закритим назавжди.
• Whatever locateAsync є остаточним — це індекс щойно завантажених даних, узятий як є, без повторного читання images.

Довідник API

Пропси LightboxOverlay

LightboxOverlayProps

Пропси LightboxUrlOverlay

LightboxUrlOverlayProps

Приймає всі візуальні та поведінкові пропси вище, крім isOpen, and replaces it with a controller. initialIndex тут ігнорується — слайд обирає position контролера, тож передане поруч значення перезаписувалося б на кожному відкритті.

Колбеки

Пропси Reel (передані далі)

Ці пропси передаються далі в Reel component.

Types

LightboxItem

ControlsRenderProps

NavigationRenderProps

SlideRenderProps

InfoRenderProps

Sub-Components

Повторно використовувані підкомпоненти для складання власних елементів керування через renderControls.

CloseButton

Стандартна кнопка закриття у вигляді хрестика.

Counter

Значок лічильника зображень на кшталт «1 / 3».

FullscreenButton

Кнопка перемикання повного екрана (іконка Maximize або Minimize).

SoundButton

Кнопка перемикання звуку для слайдів-відео (іконка Volume2 або VolumeX). Автоматично входить у renderControls from useVideoSlideRenderer. Для окремого використання у власних елементах керування доступ до стану звуку — через useSoundState.

Hooks

useVideoSlideRenderer

Хук для підтримки відео за бажанням. Повертає renderSlide, renderControls, та SoundProvider — загорніть оверлей у SoundProvider і передайте функції рендерингу.

useFullscreen

Хук для керування станом повного екрана з кросбраузерною підтримкою.

Переходи

Передайте будь-яку TransitionTransformFn via the transitionFn Якщо імпортувати лише той перехід, який використовуєте, решту збирач прибере через tree-shaking. Типово — slideTransition , коли не задано.

Власна функція переходу

Напишіть власну TransitionTransformFn and pass it via transitionFn. Сигнатура повторює переходи слайдера в ядрі.

Класи CSS

Усі елементи інтерфейсу використовують звичайні класи CSS (не CSS-модулі), які можна перекрити селекторами вищої специфічності в таблиці стилів, підключеній після @reelkit/react-lightbox/styles.css. Для змін кольору, розміру та z-index краще беріть власні властивості CSS, описані в розділі Theming нижче.

Theming

Кожен колір, розмір, z-index і перехід живе у власній властивості CSS. Перевизначайте одну чи кілька на :root (або на будь-якому предку Lightbox), щоб змінити тему, не чіпаючи код компонентів.

Вставте фрагмент нижче в таблицю стилів, підключену після @reelkit/react-lightbox/styles.css.

Accessibility

Корінь оверлея — модальний діалог (role="dialog", aria-modal="true"). Set ariaLabel щоб змінити оголошення для екранного читача; типове значення — «Image gallery». Кожен слайд несе role="group", aria-roledescription="slide", та aria-label="Зображення N з M".

Lightbox захоплює фокус під час відкриття й повертає його на елемент-тригер після закриття. Tab і Shift+Tab циклічно проходять фокусовані елементи всередині; фокус, що вислизнув (клік поза Lightbox, програмна установка), повертається назад. Реалізовано через captureFocusForReturn та createFocusTrap from @reelkit/core.