Reel Player для Vue

Features

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

Імпортуйте таблицю стилів один раз у точці входу застосунку (або в будь-якому компоненті):

Базове використання

Покажіть сітку мініатюр і відкривайте оверлей на натиснутому індексі. Прив’язка v-model:is-open означає, що батьківський ref лишається синхронним, коли користувач закриває плеєр кнопкою, жестом або клавішею Escape.

Слоти з областю видимості

Вісім слотів з областю видимості дають замінити будь-яку частину інтерфейсу плеєра. Кожен отримує строго типізований об’єкт області. Слоти, які ви не передали, лишаються стандартними.

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

Замініть вбудовану смугу відтворення власним інтерфейсом перемотування через слот #timeline . Слот спрацьовує лише тоді, коли за правилами показу оверлей вивів би стандартну смугу (та сама логіка timeline плюс timelineMinDurationSeconds), so you don't re-implement it. Reuse the .rk-reel-timeline на своєму корені, щоб успадкувати притиснення до низу, відступи безпечної зони та проміжок на дотикових пристроях.

Власні типи вмісту

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

Той самий патерн працює для будь-якого іншого слота. Імпортуйте відповідний тип області (SlideSlotScope, ControlsSlotScope, NavigationSlotScope, NestedSlideSlotScope, LoadingSlotScope) and annotate the destructure.

Стан в URL

Build a controller with useOverlayUrlState from @reelkit/vue і передайте його в ReelPlayerUrlOverlay as controller: плеєр належить адресному рядку, тож він відкривається, коли параметр називає слайд, і закривається, коли параметр зникає. Відкриття додає один запис в історію, а кожна зміна слайда його замінює, тож гортання стрічки не додає записів і один крок назад завжди виводить. Глибина URL залежить від ключа контролера: одновісний urlIndexKey адресує лише допис (?reel=3), a two-axis urlIndexTwoAxisKey несе ще й індекс внутрішнього медіа мультимедійного допису (?reel=3.2); pick one key per app, the two wire shapes do not cross-decode. It is a separate component from ReelPlayerOverlay, so each carries exactly one open-state driver — the is-open модель або url controller, never both.

Застосунок із роутером має передати адаптер на базі роутера, щоб той лишався єдиним джерелом правди про навігацію: запис в історію повз нього лишає його місцеположення застарілим і втрачає параметр на наступній навігації. useVueRouterUrlAdapter from @reelkit/vue/vue-router-url-adapter — готовий адаптер для Vue Router.

Full useOverlayUrlState опції — у довіднику API для Vue.

• Відкриття додає один запис в історію. Свайп стрічки замінює його, тож N свайпів не додають записів, і один крок назад завжди виходить із плеєра. «Назад» закриває, а не гортає слайди.
• «Назад» закриває лише тоді, коли плеєр відкрили всередині застосунку — посилання додало запис. За надісланим посиланням у новій вкладці історії позаду немає, тож кнопка «назад» виведе із сайту; кнопка ✕ або Escape прибирає параметр на місці й лишає вас на сторінці.
• Пряме посилання ?reel=3 відкриває плеєр одразу на цьому слайді.
• Параметр, який не називає жодного слайда — застаріла закладка, змінене вручну значення, — прибирається з URL, а не лишає в адресному рядку слайд, який не відкриється.
• Глибина URL залежить від ключа контролера: одна вісь для самого допису або дві (urlIndexTwoAxisKey) to also carry a multi-media post’s inner image index. Pick one key per app; the shapes do not cross-decode.

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

Той самий ReelPlayerOverlay працює з обома формами; він розрізняє їх під час виконання за 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.

Стабільні посилання. Індекс адресує за позицією, тож збережений у закладках ?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

Пропси ReelPlayerOverlay

ReelPlayerOverlayProps

Пропси ReelPlayerUrlOverlay

ReelPlayerUrlOverlayProps

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

Events

v-model:is-open

Використовуйте v-model:is-open щоб керувати оверлеєм однією прив’язкою. Давніший патерн :is-open + @close теж працює, якщо вам потрібна явна подія.

Types

ContentItem

TimelineBarProps

TimelineSlotScope<T>

MediaItem

Sub-Components

Вставляйте їх у власні шаблони #controls, #slide, or #slideOverlay . Передавайте розміри й колбеки з області слота, щоб автовідтворення, знімок постера й синхронізація звуку далі працювали.

CloseButton

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

SoundButton

Перемикач звуку. Рендерте його всередині SoundProvider (ReelPlayerOverlay надає його). Ховається, коли на активному слайді немає відео.

TimelineBar

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

SlideOverlay

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

ImageSlide

Слайд-зображення з лінивим завантаженням і object-fit: cover за замовчуванням. Складайте його всередині слота #slide щоб змінити рендеринг зображення, зберігши вбудовану поведінку.

VideoSlide

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

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

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

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

Коли використовуєте слот #slide , викликайте ці колбеки з області слота, щоб керувати індикатором завантаження:

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

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

Таймлайн

Оверлей показує вбудовану смугу таймлайну відтворення над активним відео. Керуйте показом через пропс timeline prop: 'auto' (типово) показує її, коли активне медіа — відео, довше за timelineMinDurationSeconds (default 30), 'always' щойно активне відео, 'never' вимикає її. Для повністю власної смуги перемотування беріть слот #timeline ; його область відкриває timelineState на основі TimelineController.

Тему задавайте через власні властивості CSS --rk-reel-timeline-* власними властивостями CSS.

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

ReelPlayerOverlay монтує SoundProvider у своєму корені, тож будь-який компонент усередині може читати або перемикати стан звуку через useSoundState. Композабл реекспортовано з @reelkit/vue-reel-player тож окремий @reelkit/vue import.

Класи CSS

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

Theming

Кожен колір, розмір, z-index і перехід живе у власній властивості CSS. Перевизначайте одну чи кілька на :root (або на будь-якому предку оверлея), щоб змінити тему, не чіпаючи код компонентів. Токени збігаються з @reelkit/react-reel-player, so overrides port between bindings.

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

Accessibility

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

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