IPTVnator 播放器全屏跨集切换保持机制shared player controls 的全屏所有权与 remount 生存设计【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator导读本篇技术指南以 IPTVnator 的.changes/playback-fullscreen-survives-episode-switch.md修复项为核心讲解内置播放器在默认共享控件shared player controls下如何做到切换剧集、自动连播下一集、切换直播频道、切换备选电影源时保持全屏不退出并剖析其背后的 Fullscreen API 生命周期、宿主全屏元素fullscreenSurface/fullscreenTarget与引擎 remount 机制的配合原理。读完本文你将掌握一套可复用的全屏跨内容切换不中断前端播放器设计方案并能定位到 IPTVnator 仓库中对应的实现、契约文档与测试用例。一、修复目标切换不再把用户弹回页面.changes/playback-fullscreen-survives-episode-switch.mdtype: fixarea: playback用寥寥数句描述了本次行为变更在默认的共享播放器控件下内置播放器现在能够在以下场景中保持全屏切换到另一集、下一集自动开始播放、切换直播频道、切换备选电影源——而此前每一次切换都会退回页面dropped back to the page。传统 vendor-controls 退出选项legacy vendor-controls opt-out则保持其原有行为。拆解这句话可以提炼出本次修复覆盖的四类播放内容切换即源码注释中统称的application switch场景触发方式修复前修复后共享控件手动切换剧集剧集导航previous/next episode退出全屏保持全屏自动连播下一集当前集播放结束ended后自动推进退出全屏保持全屏切换直播频道频道列表换台channel zap退出全屏保持全屏切换备选电影源VOD 多源切换alternative source退出全屏保持全屏该修复在共享控件与旧版 vendor 控件之间刻意制造了行为分叉选择退出共享控件opt-out的用户仍沿用引擎自身的全屏逻辑切换时依旧退出全屏。这一已知差异是有意为之的设计决策详见后文。二、问题根源Fullscreen API 的元素离开文档即退出语义要理解修复思路必须先看清为什么切换会无条件丢全屏。在浏览器 Fullscreen API 中document.fullscreenElement指向当前全屏的元素一旦该元素被移除出文档detach浏览器会立即退出全屏。而 IPTVnator 的播放器宿主做了如下两件事按播放应用重挂载引擎。WebPlayerViewComponent的模板用for (application of renderedApplications(); track application.token)遍历渲染引擎组件见 web-player-view.component.html并以application.token作为 track 键——每一集、每一次换台、每一次备选源切换都是一个新 token旧引擎组件随之销毁、新引擎组件挂载。引擎元素因此不断重建。HTML5 的video、Video.js 的.video-js、ArtPlayer 的容器、Embedded MPV 的画布都会随 token 变化被替换。于是灾难链条形成toggleFullscreen()把引擎自己的元素送入全屏 → 切换内容时该元素被销毁 → 元素离开文档 → 浏览器强制退出全屏 → 用户眼睁睁看着播放器弹回页面。这正是 player-controls-contract.md 中Known differences vs. vendor chrome一节所描述的历史行为。三、修复核心宿主级全屏元素fullscreenSurface/fullscreenTarget3.1 全屏所有权从引擎元素上移到宿主元素修复的关键一招是改变全屏的 DOM 所有权不再让引擎自身的播放壳元素进全屏而是让WebPlayerViewComponent的宿主根元素进全屏。该宿主元素在一次挂载期间跨所有播放应用存续——第 1 集的全屏在第 2 集引擎挂载时依然存在因为第 2 集的引擎只是宿主元素内部的内容替换宿主元素本身从未离开文档。实现上web-player-view.component.ts 用 Angular DI 将宿主元素注入为fullscreenSurface/** * DOM fullscreen owner handed to every rendered player. Applications are * remounted per token (for ... track application.token below), and * the Fullscreen API exits the moment its element leaves the document, * so a fullscreen owned by the player shell would end with every * episode, channel, or alternative-source switch. This host element * spans all applications of one mount: fullscreen entered on episode 1 * is still in place when episode 2s engine mounts, and the fresh * controls pick it up through ControlsFullscreen.sync(). It is also * the stage the fullscreen channel panel tracks, so the panel sits inside * the fullscreen element and survives the same remounts. */ readonly fullscreenSurface: HTMLElement inject(ElementRefHTMLElement) .nativeElement;随后模板把该元素作为fullscreenTarget传给每一个引擎组件web-player-view.component.htmlfor (application of renderedApplications(); track application.token) { ... [fullscreenTarget]fullscreenSurface ... }HTML5、Video.js、ArtPlayer 与 Embedded MPV 四个引擎组件均接收同一个fullscreenTarget模板中第 8、36、65、94 行分别对应四者。3.2ControlsFullscreen全屏状态机的实现细节共享控件组件内的全屏行为由ControlsFullscreen助手类统一封装完整实现见 controls-fullscreen.tssync(): void { const target this.target(); this.isFullscreen.set( Boolean( target typeof document ! undefined document.fullscreenElement target ) ); } canFullscreen(): boolean { const target this.target(); return ( typeof document ! undefined Boolean(target?.requestFullscreen) Boolean(document.exitFullscreen) ); } async toggle(): Promisevoid { const target this.target(); if (!target || !this.canFullscreen()) { return; } try { if (document.fullscreenElement target) { await document.exitFullscreen(); } else { await target.requestFullscreen(); } } catch { return; } }关键设计点sync()是全屏状态的事实来源。它以document.fullscreenElement target为准计算isFullscreen信号不依赖组件内部记忆。ControlsFullscreen构造时挂载了fullscreenchange监听器每次浏览器全屏状态变化都会回调sync()。重挂载后的状态恢复新引擎挂载后全新创建的共享控件会调用sync()重新对齐状态——由于document.fullscreenElement仍指向存活的宿主元素控件立刻得知当前已在全屏中从而以全屏状态渲染、并沿用全屏下的 UI 布局如全屏媒体标题。toggle()的幂等性先判断目标是否已是全屏元素是则退出、否则进入canFullscreen()同时校验requestFullscreen与exitFullscreen是否存在保证在非全屏能力的运行环境如部分嵌入式 WebView下安全降级。尽力而为的异常处理requestFullscreen可能因缺少用户激活user activation被浏览器拒绝例如自动连播场景try/catch静默吞掉不会污染播放流程。补充contract 文档明确记录共享控件没有全屏委托代理fullscreen delegate或原生全屏 IPC 通道全屏一律通过标准 DOMrequestFullscreen()/document.exitFullscreen()完成——这让修复在 PWA 与 Electron 渲染进程中天然一致。3.3playerSurface与fullscreenTarget的分工fullscreenTarget只管谁进全屏而播放器表面的指针/点击/光标交互仍归引擎壳元素playerSurface。二者的职责分离意味着全屏的视觉容器是宿主元素保证跨切换存活但交互目标始终是当前引擎的表面保证控制条、进度条、双击全屏等操作命中正确的播放器。这一点在 player-controls-contract.md 的全屏小节有明确阐述。四、四类切换场景的完整链路把上述机制串联起来可以画出一次剧集切换的完整时间线用户在剧集 A 全屏播放中点全屏按钮 →ControlsFullscreen.toggle()对fullscreenTarget宿主元素调用requestFullscreen()document.fullscreenElement指向宿主元素。用户触发下一集或 A 播放结束自动连播→WebPlayerViewComponent生成新的application.token。for ... track application.token销毁旧引擎组件、挂载新引擎组件新引擎被渲染在宿主元素内部宿主元素始终留在文档中。新引擎的共享控件初始化时调用ControlsFullscreen.sync()读到document.fullscreenElement 宿主元素立即以已全屏状态接管。用户停留在全屏界面中无缝观看下一集。其余三类场景自动连播、换台、备选源完全复用同一路径因为它们都只是application.token变化触发的引擎 remount。五、修复连带发现channel与vjsOptions必须改为信号契约文档还记录了一个由本修复暴露的隐藏依赖WebPlayerViewComponent.channel与vjsOptions是信号signal。原因在于 Electron 环境下流的实际地址是在 stream-header IPC promise 内部、即挂载该播放应用的那一趟变更检测之后才交给引擎的而视图又处于 OnPush 宿主PortalInlinePlayerComponent之下。此前切换会退出全屏全屏退出引发的舞台尺寸变化恰好会顺带弄脏子树、触发重渲染掩盖了这个缺陷修复后引擎在仍然生效的全屏内部被重挂载没有这个意外触发器因此这两个字段必须以信号形式驱动渲染否则新内容无法被正确推送到新引擎。这是全屏保持修复带来的一个经典连锁修复案例也再次印证了修复表象问题要先修复其依赖的不变量。六、有意保留的差异vendor-controls 退出选项的行为WebPlayerViewComponent把fullscreenTarget传给所有引擎但只有当共享控件处于启用状态时才生效。若用户在 Settings → Playback 中关闭共享控件opt-out 回传统 vendor 控件则HTML5 原生控件将原生video送入全屏Video.js 将.video-js容器送入全屏ArtPlayer 将其容器送入全屏。这些元素本身就是按 token 重挂载的引擎元素因此在每一次切换时都会被替换浏览器随即退出全屏——与共享控件路径形成鲜明对比。契约文档在 Known differences vs. vendor chrome (deliberate, opt-out retains them) 一节将其列为有意保留的已知差异并补充了技术理由自动连播等切换属于无用户激活no user activation的流程浏览器不允许对重挂载后的 vendor 引擎元素重新requestFullscreen()因此 vendor 路径无法在不破坏浏览器安全模型的前提下实现全屏保持。换言之这一分叉是共享控件方案可行、vendor 方案不可行的必然结果而非功能回退。七、联动机制全屏媒体标题与全屏频道面板全屏跨切换保持的价值不止于不弹回页面它还是两项全屏专属能力的运行前提全屏媒体标题Fullscreen media title共享控件接受可选的mediaTitle输入PlayerMediaTitle { primary, secondary? }仅在全屏且控件可见时于播放器顶部渲染标题与S01E03这类副标题并随底部控制条一起自动隐藏。窗口模式下页面 chrome 已经标明了内容因此标题保持隐藏。宿主侧由WebPlayerViewComponent从解析后的播放信息推导单行标题PortalInlinePlayerComponent则由seriesTitle加集元数据构建剧集的两行形式。全屏频道面板Fullscreen channel panelFullscreenChannelPanelComponent作为引擎的兄弟节点被WebPlayerViewComponent渲染在同一个fullscreenSurface即fullscreenTarget上——正是因为它挂在存活的宿主元素内部才能在换台导致的引擎 remount 中幸存。面板通过可选注入的FULLSCREEN_CHANNEL_PANEL令牌获得宿主提供的模板与上下文{ searchTerm, close }没有提供者的 VOD 详情页、剧集播放页不渲染任何内容。也就是说全屏所有权上移这一个设计同时支撑了切换不断全屏全屏标题持续更新全屏内换台面板不闪断三件事属于一石多鸟的架构收敛。八、验证与测试如何确认修复有效仓库围绕该机制提供了多层验证契约级文档player-controls-contract.md 作为播放器控件契约的权威参考完整记录了fullscreenTarget/fullscreenSurface/ControlsFullscreen.sync()的语义以及 vendor opt-out 的已知差异是核对行为是否符合预期的一手资料。单元测试controls-fullscreen.spec.ts与 controls-fullscreen.ts 同目录覆盖sync()对已全屏/非全屏状态的识别与toggle()的进出切换web-player-view.component.shared-controls.spec.ts与各引擎的*.shared-controls.spec.ts如 html-video-player.component.shared-controls.spec.ts、vjs-player.component.shared-controls.spec.ts、art-player.component.shared-controls.spec.ts、embedded-mpv-player.component.shared-controls.spec.ts则分别验证各引擎在共享/退出模式下全屏目标与行为是否正确。契约文档的验收标准文档要求一个宿主在一次挂载内只接收一个不可变的全屏目标重挂载的播放器在活跃全屏内部启动时即处于全屏状态vendor 退出路径保留引擎全屏并接受切换时退出——这三条分别对应实现中的fullscreenTarget绑定、sync()重对齐、以及 opt-out 分叉。九、给播放器开发者的可复用结论从 IPTVnator 的这次修复中可以提炼出三条通用的播放器全屏设计准则不要让会随内容重建的元素拥有全屏。凡是按内容 token 重挂载的引擎壳元素都不适合作为 Fullscreen API 的目标全屏所有权应上移到跨内容存续的宿主容器。用document.fullscreenElement作为唯一事实来源。在每次挂载时通过sync()重新对齐状态而不是依赖组件内部缓存才能让在新内容里接续旧全屏自然成立。尊重浏览器的用户激活约束。自动连播、自动切源等无激活流程无法重新申请全屏这正是宿主级全屏方案一次进入、全程存活相较每次切换重新申请方案的根本优势——后者在浏览器安全模型下根本不可行。如果要在自己的播放器项目中复现这套机制只需三个要素一个跨内容存续的宿主元素fullscreenSurface、一个向所有引擎组件下发该元素的输入绑定fullscreenTarget、以及一个以document.fullscreenElement为基准、可在挂载时重对齐的ControlsFullscreen助手——三者齐备全屏即可在剧集切换、自动连播、换台与备选源切换中始终如一地保持下去。【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
IPTVnator 播放器全屏跨集切换保持机制：shared player controls 的全屏所有权与 remount 生存设计
IPTVnator 播放器全屏跨集切换保持机制shared player controls 的全屏所有权与 remount 生存设计【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator导读本篇技术指南以 IPTVnator 的.changes/playback-fullscreen-survives-episode-switch.md修复项为核心讲解内置播放器在默认共享控件shared player controls下如何做到切换剧集、自动连播下一集、切换直播频道、切换备选电影源时保持全屏不退出并剖析其背后的 Fullscreen API 生命周期、宿主全屏元素fullscreenSurface/fullscreenTarget与引擎 remount 机制的配合原理。读完本文你将掌握一套可复用的全屏跨内容切换不中断前端播放器设计方案并能定位到 IPTVnator 仓库中对应的实现、契约文档与测试用例。一、修复目标切换不再把用户弹回页面.changes/playback-fullscreen-survives-episode-switch.mdtype: fixarea: playback用寥寥数句描述了本次行为变更在默认的共享播放器控件下内置播放器现在能够在以下场景中保持全屏切换到另一集、下一集自动开始播放、切换直播频道、切换备选电影源——而此前每一次切换都会退回页面dropped back to the page。传统 vendor-controls 退出选项legacy vendor-controls opt-out则保持其原有行为。拆解这句话可以提炼出本次修复覆盖的四类播放内容切换即源码注释中统称的application switch场景触发方式修复前修复后共享控件手动切换剧集剧集导航previous/next episode退出全屏保持全屏自动连播下一集当前集播放结束ended后自动推进退出全屏保持全屏切换直播频道频道列表换台channel zap退出全屏保持全屏切换备选电影源VOD 多源切换alternative source退出全屏保持全屏该修复在共享控件与旧版 vendor 控件之间刻意制造了行为分叉选择退出共享控件opt-out的用户仍沿用引擎自身的全屏逻辑切换时依旧退出全屏。这一已知差异是有意为之的设计决策详见后文。二、问题根源Fullscreen API 的元素离开文档即退出语义要理解修复思路必须先看清为什么切换会无条件丢全屏。在浏览器 Fullscreen API 中document.fullscreenElement指向当前全屏的元素一旦该元素被移除出文档detach浏览器会立即退出全屏。而 IPTVnator 的播放器宿主做了如下两件事按播放应用重挂载引擎。WebPlayerViewComponent的模板用for (application of renderedApplications(); track application.token)遍历渲染引擎组件见 web-player-view.component.html并以application.token作为 track 键——每一集、每一次换台、每一次备选源切换都是一个新 token旧引擎组件随之销毁、新引擎组件挂载。引擎元素因此不断重建。HTML5 的video、Video.js 的.video-js、ArtPlayer 的容器、Embedded MPV 的画布都会随 token 变化被替换。于是灾难链条形成toggleFullscreen()把引擎自己的元素送入全屏 → 切换内容时该元素被销毁 → 元素离开文档 → 浏览器强制退出全屏 → 用户眼睁睁看着播放器弹回页面。这正是 player-controls-contract.md 中Known differences vs. vendor chrome一节所描述的历史行为。三、修复核心宿主级全屏元素fullscreenSurface/fullscreenTarget3.1 全屏所有权从引擎元素上移到宿主元素修复的关键一招是改变全屏的 DOM 所有权不再让引擎自身的播放壳元素进全屏而是让WebPlayerViewComponent的宿主根元素进全屏。该宿主元素在一次挂载期间跨所有播放应用存续——第 1 集的全屏在第 2 集引擎挂载时依然存在因为第 2 集的引擎只是宿主元素内部的内容替换宿主元素本身从未离开文档。实现上web-player-view.component.ts 用 Angular DI 将宿主元素注入为fullscreenSurface/** * DOM fullscreen owner handed to every rendered player. Applications are * remounted per token (for ... track application.token below), and * the Fullscreen API exits the moment its element leaves the document, * so a fullscreen owned by the player shell would end with every * episode, channel, or alternative-source switch. This host element * spans all applications of one mount: fullscreen entered on episode 1 * is still in place when episode 2s engine mounts, and the fresh * controls pick it up through ControlsFullscreen.sync(). It is also * the stage the fullscreen channel panel tracks, so the panel sits inside * the fullscreen element and survives the same remounts. */ readonly fullscreenSurface: HTMLElement inject(ElementRefHTMLElement) .nativeElement;随后模板把该元素作为fullscreenTarget传给每一个引擎组件web-player-view.component.htmlfor (application of renderedApplications(); track application.token) { ... [fullscreenTarget]fullscreenSurface ... }HTML5、Video.js、ArtPlayer 与 Embedded MPV 四个引擎组件均接收同一个fullscreenTarget模板中第 8、36、65、94 行分别对应四者。3.2ControlsFullscreen全屏状态机的实现细节共享控件组件内的全屏行为由ControlsFullscreen助手类统一封装完整实现见 controls-fullscreen.tssync(): void { const target this.target(); this.isFullscreen.set( Boolean( target typeof document ! undefined document.fullscreenElement target ) ); } canFullscreen(): boolean { const target this.target(); return ( typeof document ! undefined Boolean(target?.requestFullscreen) Boolean(document.exitFullscreen) ); } async toggle(): Promisevoid { const target this.target(); if (!target || !this.canFullscreen()) { return; } try { if (document.fullscreenElement target) { await document.exitFullscreen(); } else { await target.requestFullscreen(); } } catch { return; } }关键设计点sync()是全屏状态的事实来源。它以document.fullscreenElement target为准计算isFullscreen信号不依赖组件内部记忆。ControlsFullscreen构造时挂载了fullscreenchange监听器每次浏览器全屏状态变化都会回调sync()。重挂载后的状态恢复新引擎挂载后全新创建的共享控件会调用sync()重新对齐状态——由于document.fullscreenElement仍指向存活的宿主元素控件立刻得知当前已在全屏中从而以全屏状态渲染、并沿用全屏下的 UI 布局如全屏媒体标题。toggle()的幂等性先判断目标是否已是全屏元素是则退出、否则进入canFullscreen()同时校验requestFullscreen与exitFullscreen是否存在保证在非全屏能力的运行环境如部分嵌入式 WebView下安全降级。尽力而为的异常处理requestFullscreen可能因缺少用户激活user activation被浏览器拒绝例如自动连播场景try/catch静默吞掉不会污染播放流程。补充contract 文档明确记录共享控件没有全屏委托代理fullscreen delegate或原生全屏 IPC 通道全屏一律通过标准 DOMrequestFullscreen()/document.exitFullscreen()完成——这让修复在 PWA 与 Electron 渲染进程中天然一致。3.3playerSurface与fullscreenTarget的分工fullscreenTarget只管谁进全屏而播放器表面的指针/点击/光标交互仍归引擎壳元素playerSurface。二者的职责分离意味着全屏的视觉容器是宿主元素保证跨切换存活但交互目标始终是当前引擎的表面保证控制条、进度条、双击全屏等操作命中正确的播放器。这一点在 player-controls-contract.md 的全屏小节有明确阐述。四、四类切换场景的完整链路把上述机制串联起来可以画出一次剧集切换的完整时间线用户在剧集 A 全屏播放中点全屏按钮 →ControlsFullscreen.toggle()对fullscreenTarget宿主元素调用requestFullscreen()document.fullscreenElement指向宿主元素。用户触发下一集或 A 播放结束自动连播→WebPlayerViewComponent生成新的application.token。for ... track application.token销毁旧引擎组件、挂载新引擎组件新引擎被渲染在宿主元素内部宿主元素始终留在文档中。新引擎的共享控件初始化时调用ControlsFullscreen.sync()读到document.fullscreenElement 宿主元素立即以已全屏状态接管。用户停留在全屏界面中无缝观看下一集。其余三类场景自动连播、换台、备选源完全复用同一路径因为它们都只是application.token变化触发的引擎 remount。五、修复连带发现channel与vjsOptions必须改为信号契约文档还记录了一个由本修复暴露的隐藏依赖WebPlayerViewComponent.channel与vjsOptions是信号signal。原因在于 Electron 环境下流的实际地址是在 stream-header IPC promise 内部、即挂载该播放应用的那一趟变更检测之后才交给引擎的而视图又处于 OnPush 宿主PortalInlinePlayerComponent之下。此前切换会退出全屏全屏退出引发的舞台尺寸变化恰好会顺带弄脏子树、触发重渲染掩盖了这个缺陷修复后引擎在仍然生效的全屏内部被重挂载没有这个意外触发器因此这两个字段必须以信号形式驱动渲染否则新内容无法被正确推送到新引擎。这是全屏保持修复带来的一个经典连锁修复案例也再次印证了修复表象问题要先修复其依赖的不变量。六、有意保留的差异vendor-controls 退出选项的行为WebPlayerViewComponent把fullscreenTarget传给所有引擎但只有当共享控件处于启用状态时才生效。若用户在 Settings → Playback 中关闭共享控件opt-out 回传统 vendor 控件则HTML5 原生控件将原生video送入全屏Video.js 将.video-js容器送入全屏ArtPlayer 将其容器送入全屏。这些元素本身就是按 token 重挂载的引擎元素因此在每一次切换时都会被替换浏览器随即退出全屏——与共享控件路径形成鲜明对比。契约文档在 Known differences vs. vendor chrome (deliberate, opt-out retains them) 一节将其列为有意保留的已知差异并补充了技术理由自动连播等切换属于无用户激活no user activation的流程浏览器不允许对重挂载后的 vendor 引擎元素重新requestFullscreen()因此 vendor 路径无法在不破坏浏览器安全模型的前提下实现全屏保持。换言之这一分叉是共享控件方案可行、vendor 方案不可行的必然结果而非功能回退。七、联动机制全屏媒体标题与全屏频道面板全屏跨切换保持的价值不止于不弹回页面它还是两项全屏专属能力的运行前提全屏媒体标题Fullscreen media title共享控件接受可选的mediaTitle输入PlayerMediaTitle { primary, secondary? }仅在全屏且控件可见时于播放器顶部渲染标题与S01E03这类副标题并随底部控制条一起自动隐藏。窗口模式下页面 chrome 已经标明了内容因此标题保持隐藏。宿主侧由WebPlayerViewComponent从解析后的播放信息推导单行标题PortalInlinePlayerComponent则由seriesTitle加集元数据构建剧集的两行形式。全屏频道面板Fullscreen channel panelFullscreenChannelPanelComponent作为引擎的兄弟节点被WebPlayerViewComponent渲染在同一个fullscreenSurface即fullscreenTarget上——正是因为它挂在存活的宿主元素内部才能在换台导致的引擎 remount 中幸存。面板通过可选注入的FULLSCREEN_CHANNEL_PANEL令牌获得宿主提供的模板与上下文{ searchTerm, close }没有提供者的 VOD 详情页、剧集播放页不渲染任何内容。也就是说全屏所有权上移这一个设计同时支撑了切换不断全屏全屏标题持续更新全屏内换台面板不闪断三件事属于一石多鸟的架构收敛。八、验证与测试如何确认修复有效仓库围绕该机制提供了多层验证契约级文档player-controls-contract.md 作为播放器控件契约的权威参考完整记录了fullscreenTarget/fullscreenSurface/ControlsFullscreen.sync()的语义以及 vendor opt-out 的已知差异是核对行为是否符合预期的一手资料。单元测试controls-fullscreen.spec.ts与 controls-fullscreen.ts 同目录覆盖sync()对已全屏/非全屏状态的识别与toggle()的进出切换web-player-view.component.shared-controls.spec.ts与各引擎的*.shared-controls.spec.ts如 html-video-player.component.shared-controls.spec.ts、vjs-player.component.shared-controls.spec.ts、art-player.component.shared-controls.spec.ts、embedded-mpv-player.component.shared-controls.spec.ts则分别验证各引擎在共享/退出模式下全屏目标与行为是否正确。契约文档的验收标准文档要求一个宿主在一次挂载内只接收一个不可变的全屏目标重挂载的播放器在活跃全屏内部启动时即处于全屏状态vendor 退出路径保留引擎全屏并接受切换时退出——这三条分别对应实现中的fullscreenTarget绑定、sync()重对齐、以及 opt-out 分叉。九、给播放器开发者的可复用结论从 IPTVnator 的这次修复中可以提炼出三条通用的播放器全屏设计准则不要让会随内容重建的元素拥有全屏。凡是按内容 token 重挂载的引擎壳元素都不适合作为 Fullscreen API 的目标全屏所有权应上移到跨内容存续的宿主容器。用document.fullscreenElement作为唯一事实来源。在每次挂载时通过sync()重新对齐状态而不是依赖组件内部缓存才能让在新内容里接续旧全屏自然成立。尊重浏览器的用户激活约束。自动连播、自动切源等无激活流程无法重新申请全屏这正是宿主级全屏方案一次进入、全程存活相较每次切换重新申请方案的根本优势——后者在浏览器安全模型下根本不可行。如果要在自己的播放器项目中复现这套机制只需三个要素一个跨内容存续的宿主元素fullscreenSurface、一个向所有引擎组件下发该元素的输入绑定fullscreenTarget、以及一个以document.fullscreenElement为基准、可在挂载时重对齐的ControlsFullscreen助手——三者齐备全屏即可在剧集切换、自动连播、换台与备选源切换中始终如一地保持下去。【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
