Stories Core

Рушій, на якому працює @reelkit/react-stories-player. Чистий TypeScript, без залежностей від фреймворків. Беріть його, щоб будувати плеєри історій для Angular, Vue чи звичайного JavaScript.

Framework-Agnostic

Чистий TypeScript, жодних залежностей від DOM-фреймворків

Дворівнева навігація

Групи та історії всередині кожної групи

Таймер на requestAnimationFrame

Автоперехід на requestAnimationFrame із паузою та відновленням

Прогрес на Canvas

Сегментована смуга прогресу з рухомим вікном, готова до Retina

Зони дотику

Налаштовне розпізнавання дотиків ліворуч і праворуч

Реактивні сигнали

Побудовано на примітивах сигналів @reelkit/core

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

bash

Контролер Stories

createStoriesController(config, events?) керує навігацією між групами та історіями. Стежить за станом паузи, запам’ятовує останню переглянуту історію в кожній групі й викликає колбеки на кожному переході.

Конфігурація (StoriesControllerConfig)

Властивість	Тип	Типове значення	Опис
groupCount	number	required	Загальна кількість груп історій
storyCounts	number[]	required	Кількість історій у кожній групі
initialGroupIndex	number	0	Початковий індекс групи
initialStoryIndex	number	resumeStoryIndex(initialGroupIndex), інакше 0	Початковий індекс історії всередині групи. Явно названий переважає над збереженим; пропустіть — і початкова група відновлюється, як і всі інші.
defaultImageDuration	number	5000	Типова тривалість автопереходу для історій-зображень у мілісекундах
resumeStoryIndex	(groupIndex: number) => number	undefined	Історія, на якій відкривається ще не відвідана група; обмежена наявними історіями

Події (StoriesControllerEvents)

Event	Тип	Опис
onStoryChange	(groupIndex, storyIndex) => void	Спрацьовує, коли змінюється активна історія
onGroupChange	(groupIndex) => void	Спрацьовує, коли змінюється активна група
onStoryViewed	(groupIndex, storyIndex) => void	Спрацьовує, коли історія стає видимою
onStoryComplete	(groupIndex, storyIndex) => void	Спрацьовує, коли завершується таймер історії (перед переходом)
onComplete	() => void	Спрацьовує, коли завершується остання історія останньої групи
onClose	() => void	Спрацьовує, коли оверлей має закритися

Стан (реактивні сигнали)

Signal	Тип	Опис
state.activeGroupIndex	Signal<number>	Індекс поточної активної групи
state.activeStoryIndex	Signal<number>	Індекс поточної активної історії всередині групи
state.isPaused	Signal<boolean>	Чи призупинено автоперехід

Методи

Метод	Тип	Опис
nextStory()	() => void	Перехід уперед у межах групи; на межі переходить у наступну групу
prevStory()	() => void	Перехід назад у межах групи; на межі переходить у попередню групу
nextGroup()	() => void	Перемикає на наступну групу, продовжуючи з останньої переглянутої історії
prevGroup()	() => void	Перемикає на попередню групу, продовжуючи з останньої переглянутої історії
goToGroup(index)	(number) => void	Перехід до конкретної групи за індексом
pause()	() => void	Призупиняє автоперехід
resume()	() => void	Відновлює автоперехід
onStoryTimerComplete()	() => void	Викликається, коли таймер завершується; спрацьовує onStoryComplete, а потім відбувається перехід
getLastStoryIndex(groupIndex)	(number) => number	Де відкривається група: історія, на якій її залишили в цій сесії, інакше та, що назве resumeStoryIndex
reportInitialView()	() => void	Повідомляє історію, на якій відкрився плеєр, як переглянуту — один раз. Викликайте після монтування, а не під час рендерингу.

Example

typescript

Контролер таймера

createTimerController(config) керує автопереходом через цикл requestAnimationFrame . Сигнал прогресу (від 0 до 1) живить смугу прогресу. Пауза й відновлення зберігають точну позицію.

Конфігурація (TimerControllerConfig)

Властивість	Тип	Типове значення	Опис
duration	number	required	Типова тривалість у мілісекундах
onComplete	() => void	undefined	Викликається, коли таймер доходить до 100%

State

Signal	Тип	Опис
progress	Signal<number>	Сигнал прогресу (від 0 до 1)
isRunning	Signal<boolean>	Чи таймер зараз працює

Методи

Метод	Тип	Опис
start(duration?)	(number?) => void	Запускає (або перезапускає) таймер із необов’язковою заміною тривалості
pause()	() => void	Заморожує прогрес на поточній позиції
resume()	() => void	Продовжує із замороженої позиції
reset()	() => void	Скидає прогрес до 0 і зупиняє
dispose()	() => void	Звільняє ресурси

Example

typescript

Рендерер прогресу на Canvas

createCanvasProgressRenderer(config?) малює сегментовані смуги прогресу на canvas. Масштабується під дисплеї Retina, вимірює свій контейнер через ResizeObserver і вмикає рухоме вікно, коли сегменти не вміщаються.

Config (CanvasProgressRendererConfig)

Властивість	Тип	Типове значення	Опис
gap	number	2	Проміжок між сегментами в пікселях
barHeight	number	2	Висота смуги в пікселях
minSegmentWidth	number	8	Мінімальна ширина сегмента, після якої вмикається рухоме вікно
bgColor	string	'rgba(255,255,255,0.3)'	Колір тла незаповнених сегментів
fillColor	string	'#ffffff'	Колір заповнення завершених та активних сегментів

Методи

Член	Тип	Опис
attach(canvas)	(HTMLCanvasElement) => void	Підключає до елемента canvas; запускає ResizeObserver на батьківському елементі
draw(totalStories, activeIndex, progress)	(number, number, number) => void	Малює смугу прогресу для заданого стану
width	number (readonly)	Поточна виміряна ширина в пікселях CSS
dispose()	() => void	Прибирає ResizeObserver і внутрішній стан

Example

typescript

Переглянуте

createStoriesViewedState(controller, groups) читає ViewedStateController ядра в термінах плеєра — групи, автори, індекси історій, — лишаючи саме сховище про них необізнаним. Повертає StoriesViewedState. Побудуйте сховище з того самого ключа, що й адресний рядок, з відстеженням на групу — і збережений запис читатиметься точно як параметр спільного посилання.

Параметр	Тип	Опис
controller	ViewedStateController<TwoAxisPosition>	Сховище ядра, побудоване з того самого ключа, що й адресний рядок, розгорнуте з twoAxisViewedTracking, щоб кожна група мала власний запис
groups	() => StoriesGroup<T>[]	Читає поточні групи. Гетер, тож стрічка, що довантажується або перевпорядковується після налаштування, вимірюється на момент виклику.

StoriesViewedState

Метод	Тип	Опис
viewedCounts()	() => Map<string, number>	Переглянуті історії на групу, за id автора — форма, яку StoriesRingList приймає як viewedState
resumeStoryIndex(groupIndex)	(number) => number	Перша непереглянута історія або 0, коли групу переглянуто до кінця
markViewed(groupIndex, storyIndex)	(number, number) => void	Записує історію як переглянуту. Під'єднайте до onStoryViewed.

Приклад

typescript

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

Utility Functions

Чисті функції для розпізнавання зон дотику та обчислень смуги прогресу.

Function	Тип	Опис
getTapAction(tapX, containerWidth, splitRatio?)	(number, number, number?) => 'prev' \| 'next'	Визначає за позицією, що спричиняє дотик — 'prev' чи 'next'. Типове значення splitRatio — 0.3.
getSegments(totalStories, activeIndex, progress)	(number, number, number) => SegmentState[]	Обчислює стан і відсоток заповнення кожного сегмента смуги прогресу
getVisibleWindow(totalStories, activeIndex, progress, containerWidth, minSegmentWidth?, gap?)	(number, number, number, number, number?, number?) => VisibleWindow	Обчислює видиме рухоме вікно сегментів, коли їх більше, ніж уміщає контейнер

Types

Усі визначення типів, експортовані з @reelkit/stories-core.

typescript