Appearance
场景配方
7 个完整业务场景的接线方式。和在播放器上做 UI 的区别: 那篇讲单个覆盖层组件怎么写,这里讲一个完整需求从头到尾怎么串。
这些不是我编的
每一篇都对应 examples/team-video-vue/ 里一份真实可跑的代码 —— 那份代码是本项目的验收基准(见 ACCEPTANCE.md),业务方按它接入必须一次跑通, 且不允许为了迁就 SDK 去改它。文中的代码片段都标了来源文件。
| 配方 | 你的需求长这样 | 参考实现 |
|---|---|---|
| 首页静音预览卡 | 列表页卡片自动播放,点击进详情 | LivePreviewCard.vue |
| 播完推荐联动 | 播完倒计时跳下一集,可取消 | VideoPageWithRec.vue |
| 高清需要登录 | 未登录只给标清,点高清弹登录 | AuthGatedVideoPlayer.vue |
| 直播间弹幕 | WebSocket 推弹幕,SDK 渲染 | useDanmakuStream.ts |
| 签名 URL 与过期 | 防盗链,签名会过期 | useVideoSource.ts |
| 埋点与监测 | 要卡顿率、错误率、起播耗时 | useTeamAnalytics.ts |
| CMS / Markdown 嵌入 | 只能贴一段 HTML,跑不了 npm | embed-helper |
三条贯穿所有配方的原则
1. SDK 不发业务 HTTP
弹幕数据、字幕文件、签名 URL、埋点上报 —— 全部由你的代码去取, SDK 只接收结果。这是一条硬红线(禁引 axios / ky / node-fetch 等)。
好处是 SDK 不会替你决定超时、重试、鉴权头怎么带;代价是这些你得自己写。
2. 换源改 source prop,不调方法
vue
<VideoPlayerFrame :source="currentSource" />
<!-- currentSource 变了 → 内部自动换源,不重建 iframe -->load() 不在组件句柄上。唯一需要绕过的情况是「同一个 URL 重新拉一次」, 见 API 按场景查。
3. 品牌 UI 在你那边,不在 SDK 里
SDK 只给 xgplayer 原生控件 + 契约事件。所有按钮、菜单、toast、倒计时 都是团队层用原生 UI 库(参考实现用 Vant)自己写的覆盖层(ADR-021)。
这也是为什么这些配方的代码大部分不是在调 SDK —— SDK 那部分通常只有两三行。