Reel Player

Features

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

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

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

The ReelPlayerOverlay рендерить повноекранний оверлей плеєра. Передайте масив ContentItem і керуйте видимістю через isOpen.

Демо наживо

PreviewCode

ReelPlayerPage.tsxStackBlitz

2

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

Customization

Узагальнений тип вмісту

Використовуйте власні типи даних, розширивши BaseContentItem:

Власний оверлей слайда

Замініть вбудований оверлей слайда власним вмістом для кожного слайда:

Слайди без медіа

Використовуйте renderSlide щоб вставити власний вміст (наприклад, картки із закликом до дії). Поверніть null щоб лишити стандартний:

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

Складайте готові підкомпоненти разом із власними доповненнями:

Власний таймлайн

Замініть вбудовану смугу відтворення власним інтерфейсом перемотування через renderTimeline. Колбек спрацьовує лише тоді, коли за правилами показу оверлей вивів би стандартну смугу (та сама логіка timeline плюс timelineMinDurationSeconds ), тож переписувати її не доведеться. Використайте клас .rk-reel-timeline на своєму корені, щоб успадкувати притиснення до низу, відступи безпечної зони та проміжок для оверлея слайда на дотикових пристроях.

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

Власна вкладена навігація

Замініть стрілки ліворуч і праворуч усередині мультимедійних слайдів (горизонтальна карусель) власною навігацією:

Власні вкладені слайди

Налаштуйте окремі слайди всередині мультимедійних каруселей через renderNestedSlide. Use props.defaultContent щоб загорнути стандартний ImageSlide чи VideoSlide або замінити його повністю:

Стан в URL

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

Full useOverlayUrlState опції — param, adapter, codec, locator — у довіднику API для React. Покроковий розбір — у посібнику для React.

• Відкриття додає один запис в історію. Свайп стрічки замінює його, тож N свайпів не додають записів, і один крок назад завжди виходить із плеєра. «Назад» закриває, а не гортає слайди.
• «Назад» закриває лише тоді, коли плеєр відкрили всередині застосунку — посилання додало запис. За надісланим посиланням у новій вкладці історії позаду немає, тож кнопка «назад» виведе із сайту; кнопка ✕ або Escape прибирає параметр на місці й лишає вас на сторінці.
• Пряме посилання ?reel=3 відкриває плеєр одразу на цьому слайді.
• Параметр, який не називає жодного слайда — застаріла закладка, змінене вручну значення, — прибирається з URL, а не лишає в адресному рядку слайд, який не відкриється.
• Типово параметр адресує лише vertical допис (?reel=3). Opt into a two-axis key to also carry the inner media index of a multi-media carousel — see below.

Один ключ чи два — оберіть глибину URL

Той самий ReelPlayerUrlOverlay працює з обома формами; він розрізняє їх під час виконання за position контролера, тож жодного пропса режиму немає. Ключ обирайте, коли будуєте контролер:

Дві форми запису навмисно різні — двовісний ключ строго з крапкою (3.0, never a bare 3), so a bare one-axis link does not cross-decode. Switching an app between keys therefore invalidates any previously shared links. Pick one shape and keep it.

Застосунок із роутером — передайте адаптер. Writing history.pushState повз роутер лишає його місцеположення застарілим, і наступна навігація втрачає параметр:

Стабільні посилання. Індекс адресує за позицією, тож збережений у закладках ?reel=3 відкриє інший допис, щойно стрічку перевпорядкують — а для стрічки це радше правило, ніж виняток. urlStableIdKey адресує за стабільним id, scanning the live feed — 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 самі. Дві окремі задачі: codec записує ідентичність в URL, locator знаходить, де ця ідентичність лежить.

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

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

Довідник API

Пропси ReelPlayerOverlayProps

ReelPlayerOverlayProps<T>

Пропси ReelPlayerUrlOverlay

ReelPlayerUrlOverlayProps<T>

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

Колбеки

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

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

Types

BaseContentItem

Тип-обмеження для узагальнення. Розширюйте його, щоб використовувати власні типи даних із ReelPlayerOverlay.

ContentItem

MediaItem

MediaType

ControlsRenderProps<T>

NavigationRenderProps

SlideRenderProps<T>

NestedSlideRenderProps

SlideOverlayProps

ImageSlideProps

VideoSlideProps

CloseButtonProps

SoundButtonProps

TimelineBarProps

TimelineRenderProps<T>

Sub-Components

Повторно використовувані блоки, експортовані для складання власних render props:

CloseButton

Окрема кнопка закриття зі стандартними стилями плеєра. Використовуйте всередині renderControls.

SoundButton

Окремий перемикач звуку. Має бути всередині SoundProvider (ReelPlayerOverlay додає його автоматично).

TimelineBar

Стандартна смуга перемотування. Читає з найближчого TimelineProvider (автоматично монтується всередині ReelPlayerOverlay) and renders the track, buffered ranges, progress fill, and scrub pill. Theme via the --rk-reel-timeline-* власними властивостями або замініть через renderTimeline.

SlideOverlay

Стандартний градієнтний оверлей з автором, описом і лайками. Показується автоматично, коли у вмісті є потрібні поля. Через renderSlideOverlay його можна замінити або сховати.

ImageSlide

Слайд-зображення з лінивим завантаженням і object-fit: cover за замовчуванням. Використовуйте всередині renderSlide щоб складати власні слайди-зображення зі своїми стилями.

VideoSlide

Слайд-відео зі спільним елементом <video> заради безперервності звуку на iOS, з постерами, пам’яттю позиції та індикатором завантаження. Має бути всередині SoundProvider (ReelPlayerOverlay додає його автоматично).

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

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

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

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

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

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

Таймлайн

Оверлей показує вбудовану смугу таймлайну відтворення над активним відео. Пропс timeline визначає, коли її показувати:

• 'auto' (типово): показується, коли активне медіа — відео, тривалість якого перевищує timelineMinDurationSeconds (типово 30). Працює і для слайдів з одним відео, і для мультимедійних каруселей; смуга слідує за активним вкладеним елементом і ховається на зображеннях.
• 'always': показується, щойно на активному слайді є відео.
• 'never': не показується ніколи. Власну смугу будуйте через renderTimeline.

Тему задавайте через власні властивості CSS --rk-reel-timeline-* (висота, кольори, розмір повзунка). Для повністю власної смуги перемотування, таймкоду чи індикатора прогресу беріть renderTimeline; the callback receives a timelineState на основі TimelineController.

Контекст звуку

Для власних реалізацій доступ до стану звуку відкритий:

Класи CSS

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

Theming

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

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

Accessibility

Корінь оверлея — модальний діалог (role="dialog", aria-modal="true"). Set ariaLabel щоб змінити оголошення для екранного читача; типове значення — «Video player». Кожен слайд несе role="group", aria-roledescription="slide", and an aria-label="Слайд N з M", so swiping announces position in the sequence.

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