Appearance
能力概览
这张表用同一组公开能力，比较五种接入方式能否提供相同结果。它只回答“能不能用”；如何选择接入方式请看五种接入怎么选，具体调用参数请从 API 按场景查 进入。
| 能力 | 接入条件 | React inline | Vue inline | React iframe | Vue iframe | 静态 iframe URL |
|---|---|---|---|---|---|---|
| 播放与暂停起播、暂停、播完;以及「能不能自动起播」这组开关。播放器最小可用面。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 进度与跳转把播放头移到指定时间,以及播放过程中持续上报当前时间。起播点也算这一条。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 音量与静音音量大小与静音开关。移动端自动起播几乎总要先静音,所以这条和 playback 强相关。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 倍速改变播放速度。⚠️ 契约里没有对应的事件 —— 改了速率消费方收不到回声,只能自己记。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 清晰度多档码率之间切换,含 auto。⚠️ 清晰度菜单归团队层(ADR-025),SDK 只给命令和事件。 | half | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 字幕外挂字幕的选择与关闭,支持 URL 与直接传内容两种模式(ADR-027)。字幕菜单归团队层。 | half | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 弹幕弹幕的推送、开关、清空与显示参数(ADR-028)。⚠️ 全仓唯一有命令族却没有任何专属事件的能力;数据源与输入框归团队层。 | half | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 全屏进入与退出全屏。⚠️ 契约里没有对应的事件 —— 全屏态变化消费方收不到通知。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 文案与语言覆盖层文案的语言与自定义词条(ADR-051)。SEA 语言不内置,由消费方通过 messages 传入。 | configured | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 封面与暂停图起播前的封面、暂停时的贴片图。两者都是静态图层,由 player-ui 的 custom element 渲染。 | configured | 支持 | 支持 | 支持 | 支持 | 支持 |
| 控件与交互开关要不要显示原生控件、允不允许用户交互、用哪一套预设。这三条决定播放器长什么样。 | builtin | 支持 | 支持 | 支持 | 支持 | 支持 |
| 媒体源与换源传入媒体源、运行中换源,以及按类型选内核(HLS / FLV / MP4)。换源跨内核时要重建播放器。 | builtin | 不适用 | 不适用 | 不适用 | 不适用 | 不适用 |
| 直播语义与低延迟把这一路声明成直播:改选源优先级(flv → hls → mp4)、开 LL-HLS、并让若干稳定性插件切到直播分支。 | configured | 支持 | 支持 | 支持 | 支持 | 支持 |
| 断线重连网络中断后自动重连,并把三个阶段报给消费方。也可以由消费方手动触发一次。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 生命周期与可播态播放器建好、可不可播、销毁。playablechange 是九个 reason 的聚合态(ADR-043)。 | builtin | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 媒体元信息标题、简介、时长。SDK 不显示它们,只是接线过去给覆盖层和消费方用。 | configured | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 兼容与降级浏览器不兼容、契约版本不匹配、自动起播被拦 —— 这三类「不是坏了但也不正常」的信号。 | builtin | 支持 | 支持 | 支持 | 支持 | 支持 |
| 诊断与卡顿信号开发期日志开关、卡顿信号 stalled(ADR-026),内核健康 kernelhealth(ADR-062)—— 后者是非致命内核诊断的 5 秒聚合,观测层里唯一带成因的一条。⚠️ FLV 源不发 kernelhealth。再加 bufferhealth(ADR-071):缓冲余量净流失,**观测层里唯一一条「事情还没坏」的信号** —— 其余三条都要等播放真卡住或内核真报错才开口。健康播放时它一条都不发。 | configured | 支持 | 支持 | 支持 | 支持 | 不适用 |
| 上报上下文`contextchange`(ADR-074):这一次播放是谁、用的哪个内核、播的哪个候选源、当前哪一档。**它不是又一条观测信号** —— 上面那三条回答「坏没坏」,这条回答「坏在哪一次播放的什么位置」。判据是「消费方能不能在 SDK 外面自己拿到」:拿得到的一律不进(`mode` / `contractVersion` / `live` 按这条当场出局)。源地址**只给脱敏后的 origin + pathname**,签名参数全在 query 里(ADR-022)。⚠️ `position` 不参与触发判据 —— 要「出错那一刻」的位置得同步取快照,不能读这条事件缓存的值。 | builtin | 支持 | 支持 | 支持 | 支持 | 支持 |
| FLV 音频数据健康FLV 已确认音频轨的数据连续性。音频 Tag 断流超过 3 秒报降级，数据恢复后闭合本次记录；不是静音、静音开关或输出设备故障。 | builtin | 支持 | 支持 | 支持 | 支持 | 支持 |
| 预置插件观测信号ADR-075:xgplayer 的 `DefaultPreset` 里有六个插件**每次播放都在工作**,而 `player-core` 对它们的引用数一直是 **0** —— 算完没人要。本条把其中三条接了出来:`firstframe`(XGLogger 的首帧可见耗时)· `framefreeze`(FpsDetect:**缓冲够但解码器出不了新帧**,**不是掉帧率**,也不与 `stalled` 重复 —— 后者是缓冲驱动的等待)· `useraction`(Stats 收的用户动作,经白名单只留发生在 SDK 内部的那些)。⚠️ **`framefreeze` 仅 PC** —— 上游按 `sniffer.device` 分档装载,手机上结构性不触发;这是**平台轴**差异不是模式轴,五种接入方式在同一台设备上一致。⚠️ **原本还有第四条 `bandwidth`,查掉了** —— 上游 `TestSpeed` 默认 `openSpeed: false` 且没有人发 `real_time_speed`,`DOWNLOAD_SPEED_CHANGE` 结构性不触发,进契约就是第二个「只在注释里存在的 healthreport」。**实测吞吐的缺口因此仍然开着**(ADR-068 列的真缺两条之一)。 | builtin | 支持 | 支持 | 支持 | 支持 | 支持 |
“支持”表示该能力可在该接入面完成。“不适用”表示该接入面没有对应入口，并不代表播放器不能播放该类内容。接入条件说明能力是开箱即用、需要配置，还是由宿主业务负责。