@sentinel-lab/video-react-frame

Sentinel Video Player 的 React iframe 消费面(L7)。播放器跑在独立 iframe 里,通过 frame-core 收发契约消息。

对外只有一个组件 <VideoPlayerFrame /> + 一个命令句柄。和 @sentinel-lab/video-vue-frame 行为对齐。

什么时候用它

| 场景 | 选这个包 | |:---|:---| | 要把播放器和宿主隔离(CSS 冲突、第三方内容、崩溃隔离) | ✅ 本包 | | 宿主页面样式复杂,不想被播放器影响 | ✅ 本包 | | 追求首帧速度、能接受同进程 | ❌ 用 @sentinel-lab/video-react(inline,首帧更快) | | 只能嵌 URL、跑不了 npm 包(CMS / Markdown) | ❌ 用 @sentinel-lab/video-embed-helper |

安装

pnpm add @sentinel-lab/video-react-frame

peer:react >=18、react-dom >=18。

用法

import { VideoPlayerFrame, type VideoPlayerFrameHandle } from '@sentinel-lab/video-react-frame'
import { useRef } from 'react'

function Player() {
  const ref = useRef<VideoPlayerFrameHandle>(null)

  return (
    <VideoPlayerFrame
      ref={ref}
      source="https://cdn.example.com/live/master.m3u8"
      autoplay
      muted
      onReady={({ duration, quality, subtitles }) => {}}
      onError={(err) => {}}
    />
  )
}

命令走句柄(经 iframe 通道异步下发):

await ref.current?.play()
ref.current?.seek(30)
await ref.current?.enterFullscreen()

私有化部署

iframe 默认指向官方 CDN。自建时用 origin 覆盖(ADR-023):

<VideoPlayerFrame origin="https://player.your-domain.com" version="v3" source={...} />

边界

• 薄壳——本包不含播放逻辑,只负责建 iframe、握手、转发命令与事件。播放能力在 iframe 内的 embed-app
• props 面和 @sentinel-lab/video-react 对齐,多出 origin / version 两个 iframe 专属项(cross-mode-parity 测试保障)
• 不做团队品牌 UI(ADR-021);认证只支持签名 URL(ADR-022)
• 业务代码通常不直接 import 本包,而是经团队封装层接入

相关

• 完整 props / 事件 / 句柄清单:USER-GUIDE
• 契约定义:@sentinel-lab/video-protocol

MIT