Stories Player

Features

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

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

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

The StoriesOverlay рендерить повноекранний плеєр історій. Поєднуйте його з StoriesRingList для точок входу в стилі Instagram. Передайте масив об’єктів StoriesGroup і керуйте видимістю через isOpen.

Демо наживо

PreviewCode

StoriesPlayer.tsxStackBlitz

Alice

Bob

Charlie

Натисніть кільце історії, щоб відкрити плеєр. Дотик ліворуч або праворуч гортає, свайп перемикає користувачів.

Стан в URL

StoriesUrlOverlay — окремий компонент, стан відкриття якого живе в адресному рядку. Обидві осі їдуть в одному параметрі — ?story=<group>.<story> — тож історія, що грає, має посилання, яким можна поділитися, зберегти в закладки й закрити кнопкою «назад». Побудуйте контролер через useOverlayUrlState та urlIndexTwoAxisKey, а потім передайте його як controller.

• Відкриття додає один запис в історію. Свайп історій та і перемикання користувачів replace його, тож N переходів не додають записів, і один крок назад завжди закриває плеєр. «Назад» закриває, а не гортає історії.
• Внутрішня навігація теж передається. Індекс історії не застигає на рівні групи — перехід між історіями користувача оновлює ?story=2.n тож пряме посилання відкриває саме потрібну історію.
• «Назад» закриває лише тоді, коли плеєр відкрили всередині застосунку — посилання додало запис. За надісланим посиланням у новій вкладці історії позаду немає, тож кнопка «назад» виведе із сайту; кнопка ✕ або Escape прибирає параметр на місці й лишає вас на сторінці.
• Параметр, який не називає ані групи, ані історії — застаріла закладка, змінене вручну значення, історія за межами групи — прибирається з URL, а не відкриває сусідню.

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

Стабільні посилання. Група типово адресується за позицією, тож збережений у закладках ?story=2.0 відкриє іншого користувача, щойно стрічку перевпорядкують. Адресуйте групу за стабільним id — outerCodec записує id в URL, outerLocator знаходить, де він лежить. Половина з історією лишається звичайним індексом усередині знайденої групи.

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

• While locateAsync у процесі, плеєр лишається закритим, а параметр — недоторканим, тож пряме посилання переживає запит. null або відмова прибирає параметр.
• Відповідь, що приходить після зміни URL, після закриття або після демонтажу, відкидається — повільний запит не відкриє історію, якої ніхто не просив.
• Full useOverlayUrlState опції — у довіднику API для React, а покроковий розбір — у посібнику для React.

Довідник API

StoriesOverlayProps

StoriesOverlayProps<T>

StoriesUrlOverlayProps

StoriesUrlOverlayProps<T>

Приймає всі пропси StoriesOverlay , крім трійки стану відкриття — isOpen, initialGroupIndex, initialStoryIndex , яку натомість дає контролер.

Колбеки

Переходи

The groupTransition керує 3D-ефектом переходу під час свайпу між групами користувачів. Імпортуйте функції переходів із @reelkit/react:

Життєвий цикл завантаження вмісту

Кожен слайд історії повідомляє свій стан завантаження через колбеки, передані в SlideRenderProps:

Render Props

Будь-який елемент інтерфейсу можна замінити через render props. Кожен отримує типізовані пропси з усім потрібним станом і колбеками.

renderHeader

Замініть стандартну шапку (дані автора, кнопки паузи та звуку, кнопка закриття):

renderFooter

Додайте підвал під вмістом історії:

renderSlide

Повністю замініть стандартні слайди із зображенням і відео. Скористайтеся підкомпонентами ImageStorySlide та VideoStorySlide для вбудованої роботи з медіа:

renderNavigation

Замініть стандартні кнопки-стрілки для десктопа:

renderProgressBar

Замініть стандартну смугу прогресу на canvas власною реалізацією. Сигнал progress видає значення від 0 до 1:

renderLoading

Власний індикатор завантаження, поки вміст вантажиться:

renderError

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

StoriesApi

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

Методи

Подвійний дотик і лайки

На подвійний дотик програється вбудована анімація сердечка — миттєвий візуальний відгук. Колбек onDoubleTap спрацьовує з індексами групи та історії, тож ви можете зберегти лайк у власному стані (запит до API, локальне сховище тощо). Сам плеєр стан лайків не веде.

Налаштування анімації сердечка

Змініть швидкість анімації через --rk-stories-heart-duration token (see Theming). Для кольору, розміру чи повного приховування сердечка звертайтеся до .rk-stories-heart напряму. Компонент HeartAnimation також експортовано для окремого використання.

Sub-Components

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

CanvasProgressBar

Швидка сегментована смуга прогресу на canvas. Рендерить сегмент для кожної історії й анімує заповнення активного через requestAnimationFrame. Підтримує рухоме вікно для груп із багатьма історіями.

StoryHeader

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

ImageStorySlide

Слайд-зображення на всю площу з object-fit: cover. Повідомляє про завантаження та помилки через колбеки для відстеження життєвого циклу.

VideoStorySlide

Слайд-відео, що використовує спільний елемент <video> заради безперервності звуку на iOS. Дає раду автовідтворенню, постерам, синхронізації звуку й повідомляє тривалість і події життєвого циклу відтворення.

StoriesRing

Круглий аватар із градієнтним кільцем у стилі Instagram. Сегменти показують переглянуті й непереглянуті історії — градієнт для непереглянутих, приглушений сірий для переглянутих.

StoriesRingList

Горизонтальний прокручуваний ряд компонентів StoriesRing з іменами авторів. Одне кільце на групу.

HeartAnimation

Анімований оверлей сердечка, що спрацьовує на подвійний дотик. Збільшується й згасає за 800 мс. Налаштовується засобами CSS (дивіться розділ про подвійний дотик і лайки).

Types

StoryItem

AuthorInfo

StoriesGroup<T>

HeaderRenderProps<T>

FooterRenderProps<T>

SlideRenderProps<T>

NavigationRenderProps

ProgressBarRenderProps<T>

LoadingRenderProps<T>

ErrorRenderProps<T>

StoriesApi

Власні типи Story

Extend StoryItem власними полями й передайте параметр типу в StoriesOverlay. Усі render props отримають ваш розширений тип:

Класи CSS

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

Theming

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

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

Accessibility

Корінь оверлея — модальний діалог (role="dialog", aria-modal="true"). Set ariaLabel щоб змінити оголошення для екранного читача; типове значення — «Stories player».

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