Angular Reel Player

特性

安装

基本用法

把样式表和独立组件 RkReelPlayerOverlayComponent 引入组件的 imports 数组。

模板插槽

六个模板插槽指令让你定制播放器界面的每个部分。每个都会收到带完整类型的上下文对象。只需提供你想覆盖的插槽 —— 其余的沿用默认实现。

自定义时间轴

rkPlayerTimeline 模板插槽只有在浮层的门控规则会渲染默认条时才会调用（同样是 timeline 模式 + timelineMinDurationSeconds），所以不必自己重写一遍。在你的根元素上复用 .rk-reel-timeline 类，即可继承贴底定位、安全区内边距和触摸设备上的留白。在你的拖动轨道上调用 state.bindInteractions(el) 即可接上指针 + 键盘拖动。

嵌套滑动器（多媒体条目）

When a ContentItem 包含多个 media 条目时，播放器会把它们渲染成一个横向的嵌套滑动器（Instagram 轮播风格）。用 rkPlayerNestedSlide 插槽即可自定义内层幻灯片的内容。

内容加载与错误处理

播放器会逐张跟踪加载和错误状态。内容加载时显示波浪加载动画；媒体损坏时显示错误图标。出错的 URL 会被缓存，再次访问时立刻显示错误而不重试。

生命周期回调

使用 rkPlayerSlide 模板插槽时，请用上下文里的回调来控制加载提示：

自定义加载与错误界面

用自定义模板替换默认的波浪加载动画和错误图标：

时间轴

浮层会在当前视频上方渲染一个内置的播放时间轴条。用 timeline 输入控制： 'auto' （默认）只要当前媒体是时长超过 timelineMinDurationSeconds （默认 30）的视频就渲染， 'always' 则只要有视频在播就渲染， 'never' 则关闭。若要完全自定义拖动条，请用 rkPlayerTimeline 模板指令；它的上下文会暴露一个 timelineState ，其数据来自底层的 TimelineController.

通过 --rk-reel-timeline-* CSS 自定义属性。若要在自定义的使用方组件里直接控制，请注入 TimelineStateService.

RkTimelineBarComponent

默认的播放拖动条组件。它消费 TimelineStateService （由 RkReelPlayerOverlayComponent提供），并渲染轨道、缓冲区间、进度填充和拖动手柄。选择器： rk-timeline-bar。输入： class?: string, style?: Record<string, string>。在 rkPlayerTimeline 模板内部使用它来包裹或增强默认条；只有在提供了该服务的使用方内部才可以单独使用。

SoundStateService

在 RkReelPlayerOverlayComponent 级提供。默认的声音按钮会注入它，控件模板插槽的上下文里也会暴露它。作为浮层 children 的自定义控件也可以注入它来直接访问。

URL 状态

RkReelPlayerUrlOverlayComponent 是一个独立组件，它的打开状态存放在地址栏里。用 createOverlayUrlState ，并把它作为 [controller]传入：参数指向某张幻灯片时播放器打开，参数消失时关闭。链接可以分享，返回键会关闭播放器。 RkReelPlayerOverlayComponent 仍然由 [isOpen]控制，因此每个组件都只有一个打开状态的驱动源。

带路由的应用会传入基于 Router 的适配器，让 Router 始终是导航的唯一真相来源 —— 绕过它直接写历史会让 location 过期，下一次导航就会把参数丢掉。 createRouterUrlAdapter from @reelkit/angular/ng-router-url-adapter 就是现成的适配器。

• 打开时压入 一条 历史记录。滑动信息流则是 替换 它，因此滑 N 次也不会多出记录，退一步永远就是离开播放器。返回键关闭播放器，不会逐张后退。
• 只有在应用内部打开播放器时返回键才会关闭它 —— 因为那次链接压入了一条记录。在新标签页里直接打开的分享链接背后没有历史，浏览器返回会离开站点；这时用 ✕ 按钮或 Escape 就地移除参数并留在页面上。
• 深链 ?reel=3 会在加载时直接把播放器打开到那一张。
• 指向不存在幻灯片的参数 —— 过期的书签、手改的值 —— 会从 URL 中移除，而不是让地址栏继续声称一张打不开的幻灯片。
• URL 的深度取决于控制器用的 key：单轴只表示帖子，双轴（urlIndexTwoAxisKey）还会携带多媒体帖子的内层图片索引。每个应用只选一种；两种形态不会互相解码。

完整的 createOverlayUrlState 选项见 Angular API 参考.

一条轴还是两条 —— 自己决定 URL 的深度

同一个 RkReelPlayerUrlOverlayComponent 两种形态都能驱动；它在运行时根据控制器的 position 自行判别，所以没有 mode 输入。在构建控制器时选好 key 即可：

两种形态是刻意区分开的 —— 双轴 key 严格使用点分隔（3.0，绝不会是裸的 3），因此单轴链接不会被错误解码。也正因如此，应用在两种 key 之间切换会让此前分享出去的链接全部失效。选定一种形态就别再改。

稳定的链接。 索引是按位置的，所以收藏下来的 ?reel=3 在信息流重新排序后就会打开另一条帖子 —— 对信息流来说这是常态。 urlStableIdKey 按每条帖子稳定的 id来寻址，扫描当前的信息流 —— 一次调用就覆盖了常见场景。

传入 hashCodec: base64UrlCodec 即可把 URL 中的 id 做 base64url 编码 —— 这是可逆的混淆，不是加密哈希。

想按别的字段（比如 slug）来寻址，或者用 locateAsync给无限信息流翻页，就自己构建 codec/locator 。这是两件事： codec 把身份写进 URL， locator 则负责找到这个身份在哪。

无限信息流。 locate 是同步的，因此只能回答已经加载过的帖子 —— 只加载了 20 条时，指向第 400 条的分享链接就查不到。 locateAsync 是兜底，只有在 locate 未命中时才调用：把需要的页拉进来，再返回该身份最终对应的索引。

• 在 locateAsync 未完成期间，播放器保持关闭，参数也不动，因此深链能熬过这次请求。 null 或请求被拒绝则会移除参数。
• 如果结果在 URL 已经变化、播放器已关闭或组件已卸载之后才到达，就会被丢弃 —— 慢请求不能打开一张没人要的幻灯片。
• 等待期间什么都不渲染；加载状态本来就归页面自己管，所以请渲染你自己的骨架屏。
• 没有超时机制 —— 播放器无从得知信息流有多长。分页用尽时请以 null 结束，否则浮层会一直关着。

自定义数据类型

扩展 BaseContentItem 即可使用你自己的领域模型。这个组件是泛型的： RkReelPlayerOverlayComponent<T extends BaseContentItem>.

RkReelPlayerOverlayComponent 输入

RkReelPlayerOverlayComponent 输出

RkReelPlayerUrlOverlayComponent 输入

接受上面所有输入，除了 isOpen 和 initialIndex，它被 controller ，由它的 position 决定打开哪一张。输出 closed 和 slideChange.

MediaItem 接口

模板插槽上下文类型

CSS 类名

所有 CSS 类名都是普通类名（没有 scoped），因此可以在 @reelkit/angular-reel-player/styles.css之后加载的样式表里用更高优先级的选择器覆盖它们。若只是改颜色、尺寸和 z-index，请优先使用下面 主题定制 一节记录的 CSS 自定义属性 —— 它们正是为此设计的。

主题定制

每一个颜色、尺寸、z-index 和过渡都放在 CSS 自定义属性里。在 :root （或浮层的任意祖先元素）上覆盖，即可在不改组件源码的情况下换主题。这些变量与 React 和 Vue 包保持一致，因此覆盖样式可以在不同框架绑定之间通用。

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

无障碍

浮层根节点是一个模态对话框（role="dialog", aria-modal="true"). Set the ariaLabel 输入可以改变屏幕阅读器的播报内容，默认是 “Video player”。每张幻灯片都带有 role="group", aria-roledescription="slide"、 aria-label="第 N 张，共 M 张".

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