Stories Player

特性

安装

别忘了引入样式：

快速上手

StoriesOverlay 组件渲染一个全屏 Stories Player。搭配 StoriesRingList 作为 Instagram 风格的入口。传入一组 StoriesGroup 对象，并用 isOpen.

在线演示

PreviewCode

StoriesPlayer.tsxStackBlitz

Alice

Bob

Charlie

点圆环打开播放器。点左右两侧切换 story，滑动切换用户。

URL 状态

StoriesUrlOverlay 是一个独立组件，它的打开状态存放在地址栏里。两条轴共用一个参数 —— ?story=<group>.<story> —— 于是正在播放的 story 就有了可分享、可收藏、能用返回键关闭的链接。用 useOverlayUrlState 和 urlIndexTwoAxisKey构建控制器，再作为 controller.

• 打开时压入 一条 历史记录。滑动 story 和 切换用户都是 替换 它，因此导航 N 次也不会多出记录，退一步永远就是关闭播放器。返回键关闭播放器，不会逐个后退 story。
• 内层导航也会被记录。 story 索引不会被冻结在分组粒度上 —— 在某个用户的 story 之间前进时会更新 ?story=2.n ，因此深链能精确落到那一个 story。
• 只有在应用内部打开播放器时返回键才会关闭它 —— 因为那次链接压入了一条记录。在新标签页里直接打开的分享链接背后没有历史，浏览器返回会离开站点；这时用 ✕ 按钮或 Escape 就地移除参数并留在页面上。
• 指向不存在的分组或 story 的参数 —— 过期的书签、手改的值、超出分组末尾的 story —— 会从 URL 中移除，而不是打开相邻的那个。

带路由的应用 —— 请传入适配器。 绕过路由器直接写 history.pushState 会让它的 location 过期，下一次导航就会把参数丢掉：

稳定的链接。 分组默认是按位置的，所以收藏下来的 ?story=2.0 在信息流重新排序后就会打开另一个用户。请改用稳定 id 来寻址分组 —— outerCodec 把 id 写进 URL， outerLocator 负责找到它在哪。story 那一半仍然是解析出的分组内的普通索引。

无限信息流。 翻页是 outerLocator 该管的事，与编解码器无关。 locate 是同步的，因此只能回答已经加载过的分组 —— 只加载了 20 个时，指向第 400 个分组的分享链接就查不到。 locateAsync 是兜底，只有在 locate 未命中时才调用；story 会以最终落到的那个分组重新校准上界。

• 在 locateAsync 未完成期间，播放器保持关闭，参数也不动，因此深链能熬过这次请求。返回 null 或请求被拒绝则会移除参数。
• 如果结果在 URL 已经变化、播放器已关闭或组件已卸载之后才到达，就会被丢弃 —— 慢请求不能打开一个没人要的 story。
• 完整的 useOverlayUrlState 选项见 React API 参考，完整讲解见 React 指南.

记住已观看内容

圆环在分组看完之前显示渐变，分组重新打开时停在观看者尚未看过的第一条 story。两者都来自一个 ViewedStateController，它用地址栏所用的同一个键构建——因此已存记录读起来与分享链接的参数完全一样，并且在键按 id 寻址时能经受信息流重排。

• 打开时的 story 也算。 挂载时就把屏幕上的 story 报告为已看，所以打开只有一条 story 的分组再关闭，也会标记为已看。
• 往后滑同样会续播。 resumeStoryIndex 对本次会话中第一次到达的每个分组生效，包括播放器打开时所在的那个，除非 initialStoryIndex 显式指定了 story；已经滑过的分组会在离开处重新打开。
• 链接仍然优先。 使用 StoriesUrlOverlay 时，由参数决定播放器在哪里打开，无论存了什么。其他情况下由续播回调决定。
• 计数是位置，不是次数。 记录记的是到达的最远一条 story，因此给已看完的分组新增一条会重新点亮圆环，从中间删掉一条则会让计数变短。与分享链接得到的自愈相同。
• 存储可替换。 传入 createSessionStorageAdapter() 在关闭标签页时遗忘，或使用自己的 StorageAdapter。两个打开的标签页通过浏览器的 storage 事件保持一致。

API 参考

StoriesOverlayProps

StoriesOverlayProps<T>

StoriesUrlOverlayProps

StoriesUrlOverlayProps<T>

接受 StoriesOverlay 的所有属性，除了打开状态那三个 —— isOpen, initialGroupIndex, initialStoryIndex —— 它们改由控制器提供。

回调

过渡动画

groupTransition 属性控制在用户分组之间滑动时的 3D 过渡效果。过渡函数请从 @reelkit/react:

内容加载生命周期

每个 story 幻灯片都通过 SlideRenderProps:

Render Props

每个界面元素都可以通过 render props 替换。每个都会收到带类型的属性，包含所需的全部状态和回调。

renderHeader

替换默认页眉（作者信息、暂停 / 静音按钮、关闭按钮）：

renderFooter

在 story 内容下方加一个页脚：

renderSlide

完全替换默认的图片 / 视频幻灯片。可以用 ImageStorySlide 和 VideoStorySlide 这些子组件来复用内置的媒体处理：

renderNavigation

替换默认的桌面端箭头按钮：

renderProgressBar

用自定义实现替换默认的 canvas 进度条。 progress 信号发出 0 到 1 的值：

renderLoading

内容加载期间的自定义加载提示：

renderError

内容加载失败时的自定义错误浮层：

StoriesApi

Use the apiRef 属性做命令式控制：

方法

双击与点赞

双击时会播放内置的爱心动画，给出即时的视觉反馈。 onDoubleTap 回调会带上分组和 story 索引，你可以据此把点赞存进自己的状态里（调接口、本地存储等等）。播放器内部并不管理点赞状态。

定制爱心动画

通过 --rk-stories-heart-duration 变量调整动画速度（见 主题定制）。要改颜色、尺寸或者干脆隐藏爱心，请直接针对 .rk-stories-heart 类。 HeartAnimation 组件也单独导出，可以独立使用。

子组件

对外导出的可复用积木，用于在自定义 render props 中组合：

CanvasProgressBar

基于 canvas 的高性能分段进度条。为每个 story 渲染一段，并用 requestAnimationFrame为当前段做填充动画。story 很多的分组会启用滑动窗口。

StoryHeader

默认页眉，包含作者头像、名称、认证徽章、相对时间、暂停 / 播放开关、静音开关、加载动画和关闭按钮。未提供 renderHeader 时自动使用。

ImageStorySlide

铺满的图片幻灯片，使用 object-fit: cover。通过回调上报加载 / 错误状态以便跟踪生命周期。

VideoStorySlide

视频幻灯片，使用共享的 <video> 元素以保证 iOS 上声音连续。它负责自动播放、封面帧、声音同步，并上报时长和播放生命周期事件。

StoriesRing

带 Instagram 风格渐变圆环的圆形头像。分段表示已读 / 未读 story —— 未读是渐变色，已读是灰色。

StoriesRingList

可横向滚动的一排 StoriesRing 组件，带作者名称。每个分组一个圆环。

HeartAnimation

双击触发的爱心动画浮层。在 800 毫秒内放大并淡出。可通过 CSS 定制（见“双击与点赞”一节）。

类型

StoryItem

AuthorInfo

StoriesGroup<T>

HeaderRenderProps<T>

FooterRenderProps<T>

SlideRenderProps<T>

NavigationRenderProps

ProgressBarRenderProps<T>

LoadingRenderProps<T>

ErrorRenderProps<T>

StoriesApi

自定义 Story 类型

扩展 StoryItem ，加上自定义字段，再把类型参数传给 StoriesOverlay。所有 render props 都会收到你扩展后的类型：

CSS 类名

所有 CSS 类名都是普通类名（不是 CSS Modules），因此可以在 @reelkit/react-stories-player/styles.css之后加载的样式表里用更高优先级的选择器覆盖它们。若只是改颜色、尺寸和 z-index，请优先使用下面 主题定制 一节。

主题定制

每一个颜色、尺寸、z-index 和过渡都放在 CSS 自定义属性里。在 :root （或浮层的任意祖先元素）上覆盖其中一个或多个，即可在不改组件源码的情况下换主题。

把下面这段放进在 @reelkit/react-stories-player/styles.css.

无障碍

浮层根节点是一个模态对话框（role="dialog", aria-modal="true"）。设置 ariaLabel 可以改变屏幕阅读器的播报内容，默认是 “Stories player”。

浮层打开时捕获焦点，关闭时把焦点还给触发元素。Tab 和 Shift+Tab 在内部的可聚焦元素之间循环；跑出去的焦点（点击外部、程序化聚焦）会被拉回来。实现基于 captureFocusForReturn 和 createFocusTrap from @reelkit/core.