Stories Core

驱动 @reelkit/react-stories-player的引擎。纯 TypeScript，不依赖任何框架。可以用它为 Angular、Vue 或原生 JS 构建 Stories Player。

与框架无关

纯 TypeScript，不依赖任何 DOM 框架

两级导航

分组，以及每个分组内部的 story

RAF 计时器

基于 requestAnimationFrame 的自动播放，支持暂停 / 恢复

Canvas 进度条

适配 Retina 的分段进度条，带滑动窗口

点击区域

可配置的左右点击检测

响应式信号

构建在 @reelkit/core 的信号原语之上

安装

bash

Stories 控制器

createStoriesController(config, events?) 负责在分组和 story 之间导航。它跟踪暂停 / 恢复状态，记住每个分组最后看到的 story，并在每次切换时触发回调。

配置（StoriesControllerConfig）

属性	类型	默认值	说明
groupCount	number	必填	story 分组总数
storyCounts	number[]	必填	每个分组内的 story 数量
initialGroupIndex	number	0	初始分组索引
initialStoryIndex	number	0	分组内的初始 story 索引
defaultImageDuration	number	5000	图片类 story 的默认自动播放时长（毫秒）

事件（StoriesControllerEvents）

事件	类型	说明
onStoryChange	(groupIndex, storyIndex) => void	当前 story 变化时触发
onGroupChange	(groupIndex) => void	当前分组变化时触发
onStoryViewed	(groupIndex, storyIndex) => void	某个 story 变为可见时触发
onStoryComplete	(groupIndex, storyIndex) => void	Fired when a story's timer completes (before advancing)
onComplete	() => void	最后一个分组的最后一个 story 播完时触发
onClose	() => void	浮层应当关闭时触发

状态（响应式信号）

Signal	类型	说明
state.activeGroupIndex	Signal<number>	当前分组索引
state.activeStoryIndex	Signal<number>	分组内当前 story 的索引
state.isPaused	Signal<boolean>	自动播放是否已暂停

方法

方法	类型	说明
nextStory()	() => void	在分组内前进；越过边界时进入下一个分组
prevStory()	() => void	在分组内后退；越过边界时回到上一个分组
nextGroup()	() => void	切到下一个分组，并从上次看到的 story 继续
prevGroup()	() => void	切到上一个分组，并从上次看到的 story 继续
goToGroup(index)	(number) => void	按索引跳到指定分组
pause()	() => void	暂停自动播放
resume()	() => void	恢复自动播放
onStoryTimerComplete()	() => void	计时结束时调用；先触发 onStoryComplete 再前进
getLastStoryIndex(groupIndex)	(number) => number	某分组最后看到的 story 索引（从未访问过则为 0）

示例

typescript

计时控制器

createTimerController(config) 用 requestAnimationFrame 循环驱动自动播放。进度信号（0 到 1）供给进度条。暂停和恢复会精确保留位置。

配置（TimerControllerConfig）

属性	类型	默认值	说明
duration	number	必填	默认时长（毫秒）
onComplete	() => void	undefined	计时到达 100% 时调用

状态

Signal	类型	说明
progress	Signal<number>	进度信号（0 到 1）
isRunning	Signal<boolean>	计时器当前是否在运行

方法

方法	类型	说明
start(duration?)	(number?) => void	启动（或重启）计时器，可选地覆盖时长
pause()	() => void	把进度冻结在当前位置
resume()	() => void	从冻结的位置继续
reset()	() => void	把进度重置为 0 并停止
dispose()	() => void	清理资源

示例

typescript

Canvas 进度渲染器

createCanvasProgressRenderer(config?) 在 canvas 上绘制分段进度条。它会针对 Retina 屏缩放，通过 ResizeObserver 测量容器，并在分段放不下时启用滑动窗口。

配置（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 和内部状态

示例

typescript

工具函数

用于点击区域检测和进度条计算的纯函数。

函数	类型	说明
getTapAction(tapX, containerWidth, splitRatio?)	(number, number, number?) => 'prev' \| 'next'	Determines whether a tap triggers 'prev' or 'next' based on position. Default splitRatio is 0.3.
getSegments(totalStories, activeIndex, progress)	(number, number, number) => SegmentState[]	计算进度条中每个分段的状态和填充比例
getVisibleWindow(totalStories, activeIndex, progress, containerWidth, minSegmentWidth?, gap?)	(number, number, number, number, number?, number?) => VisibleWindow	当分段总数超出容器容量时，计算可见的滑动窗口

类型

全部类型定义均导出自 @reelkit/stories-core.

typescript