@sentinel-lab/video-embed-helper

Sentinel Video Player 的静态 iframe 场景 host 侧辅助(L7)。

给 CMS / Markdown / 论坛 / 邮件模板这类「只能嵌一个 URL、跑不了 npm 包」的场景用:让宿主页面能订阅 iframe 里播放器广播出来的契约事件。

只依赖 @sentinel-lab/video-protocol,无框架依赖。

两种用法

1. <script> 标签(无构建工具)

helper.js 和 iframe src 同目录——把 URL 末尾换成 helper.js 即可,版本锁定自动跟随,不用另记地址:

<iframe src="https://sentinel-video.pages.dev/embed/v4/?src=...&autoplay=1"></iframe>
<script src="https://sentinel-video.pages.dev/embed/v4/helper.js"></script>
<script>
  SentinelEmbed.on('ended', () => { location.href = nextUrl })
</script>

2. npm(有构建工具)

pnpm add @sentinel-lab/video-embed-helper

import { createEmbedListener } from '@sentinel-lab/video-embed-helper'

const player = createEmbedListener({
  // 生产环境建议配上播放器 CDN origin,避免收到同页无关 iframe 的消息
  origin: 'https://sentinel-video.pages.dev',
})

const unsubscribe = player.on('timeupdate', ({ time, duration }) => {
  progressBar.style.width = `${(time / duration) * 100}%`
})

player.on('error', (err) => {
  // err.code 是 protocol 注册的 E_* 错误码
})

// 清理
unsubscribe()
player.destroy()

API

| 成员 | 说明 | |:---|:---| | createEmbedListener(options?) | 创建监听器。options.origin 白名单(省略=接受任意 origin,仍过 schema 校验);options.target 挂载目标,默认 window | | listener.on(event, handler) | 订阅事件,返回退订函数 | | listener.off(event, handler) | 退订(需传订阅时的同一 handler 引用) | | listener.destroy() | 卸载 message 监听并清空所有订阅 |

事件名与 payload 形状对齐 protocol 的 PlayerEvent。

边界

• 只收不发——本包只订阅事件,不下发命令。静态 iframe 场景没有命令通道,要控制播放请改用 @sentinel-lab/video-react-frame 或 @sentinel-lab/video-vue-frame
• 所有消息过 Zod schema 校验,非法消息静默丢弃
• SSR 安全——取不到 window 时整体 no-op,不抛错

相关

• 静态 iframe URL 参数清单:USER-GUIDE

MIT