@sentinel-lab/video-react

Sentinel Video Player 的 React inline 消费面(L7)。直连 player-core + player-ui,不走 iframe,首帧最快。

对外只有一个组件 <VideoPlayer /> + 一个命令句柄。见 ADR-001。

什么时候用它

| 场景 | 选这个包 | |:---|:---| | 追求首帧速度、宿主同为 React | ✅ 本包 | | 需要和宿主页面样式/状态深度联动 | ✅ 本包 | | 要把播放器和宿主隔离(第三方内容、CSS 冲突) | ❌ 用 @sentinel-lab/video-react-frame | | 宿主是 Vue | ❌ 用 @sentinel-lab/video-vue(inline,本包的镜像)或 @sentinel-lab/video-vue-frame(iframe) |

安装

pnpm add @sentinel-lab/video-react

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

用法

import { VideoPlayer, type VideoPlayerHandle } from '@sentinel-lab/video-react'
// 别漏 —— 少了它播放器照样能播,但控件是散的。引擎样式和覆盖层样式都拼在这一份里,
// 不需要另外装 xgplayer
import '@sentinel-lab/video-react/style.css'
import { useRef } from 'react'

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

  return (
    <VideoPlayer
      ref={ref}
      source="https://cdn.example.com/live/master.m3u8"
      autoplay
      muted
      onReady={({ duration, quality, subtitles }) => {
        // quality / subtitles 是可切档位与字幕轨清单,团队层据此渲染菜单
      }}
      onError={(err) => {
        // err.code 是 protocol 注册的 E_* 错误码,err.retryable 指示是否可重试
      }}
    />
  )
}

命令走句柄,不走 props:

await ref.current?.play()
ref.current?.seek(30)
ref.current?.setQuality('auto')
ref.current?.setSubtitle(1)       // id 来自 onReady 的 subtitles[]
await ref.current?.enterFullscreen()

边界

• 只做技术——播放能力、事件、命令、容错。品牌 UI(结束覆盖层、清晰度菜单、皮肤)归团队封装层,不在本包(ADR-021)
• props 面刻意和 react-frame 对齐(去掉 iframe 专属的 origin / version),团队封装层在 inline / iframe 间切换成本最低(cross-mode-parity 测试保障)
• 认证只支持签名 URL,不接受自定义请求头(ADR-022)
• getPlayerHandle() 是逃生舱,返回底层 player-core 句柄,给需要绕过 React 直接下命令的高级场景

相关

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

MIT