默认情况下，浏览器全屏 API 仅将 元素本身全屏，导致外部自定义控件被排除在外；解决方法是将视频及其所有控件包裹在一个容器 中，并对该容器调用全屏 API，从而确保控件随视频一同进入全屏。

默认情况下，浏览器全屏 api 仅将 `

` 中，并对该容器调用全屏 api，从而确保控件随视频一同进入全屏。

在构建自定义 HTML5 视频播放器时，一个常见痛点是：当用户点击全屏按钮后，仅

根本原因在于：video.requestFullscreen() 只会让该

✅ 正确实现步骤

1. 封装容器（HTML 层面）

将

中（例如 id="vid_container"），确保 DOM 结构语义清晰且可操作：

<div id="vid_container">
  <video id="video" class="video w-100" playsinline><source src="https://test.loro.ec/www/t/test.loro.ec/images/articles_blocks/608.mp4" type="video/mp4"></source></video><div class="controls position-relative" style="top: -50px; margin-left: 8px;">
    <!-- 控件结构保持不变 -->
    <div class="row">
      <div class="col-1">
        <button class="controls__button toggleButton btn" id="toggleButton" title="Toggle Play" onclick="togglePlay()">►</button>
      </div>
      <div class="progress col-5 p-0" id="progressId">
        <div class="progress__filled" style="background: rebeccapurple;"></div>
      </div>
      <div class="col-4">
        <i class="bi bi-volume-up"></i>
        <input class="form-range" style="width: 80%;" type="range" id="volume-bar" title="volume" min="0" max="1" step="0.1" value="1">
</div>
      <div class="col-1">
        <button class="btn" onclick="toggleFullScreen()"><i class="bi bi-arrows-fullscreen"></i></button>
      </div>
    </div>
  </div>
</div>

? 注意：添加 playsinline 属性有助于在 iOS Safari 中避免自动跳转至原生播放器界面。

2. 更新 JavaScript 全屏逻辑

不再对 video 调用全屏，而是获取并操作容器元素 #vid_container：

const container_vid = document.getElementById("vid_container");
const video = document.querySelector(".video");
// ...其余变量声明保持不变

function toggleFullScreen() {
  if (!document.fullscreenElement && !document.webkitFullscreenElement && 
      !document.mozFullScreenElement && !document.msFullscreenElement) {
    // 进入全屏
    if (container_vid.requestFullscreen) {
      container_vid.requestFullscreen();
    } else if (container_vid.webkitRequestFullscreen) {
      container_vid.webkitRequestFullscreen();
    } else if (container_vid.mozRequestFullScreen) {
      container_vid.mozRequestFullScreen();
    } else if (container_vid.msRequestFullscreen) {
      container_vid.msRequestFullscreen();
    }
  } else {
    // 退出全屏
    if (document.exitFullscreen) {
      document.exitFullscreen();
    } else if (document.webkitExitFullscreen) {
      document.webkitExitFullscreen();
    } else if (document.mozCancelFullScreen) {
      document.mozCancelFullScreen();
    } else if (document.msExitFullscreen) {
      document.msExitFullscreen();
    }
  }
}

✅ 推荐使用现代标准 document.exitFullscreen() 替代已废弃的 cancelFullScreen() 等旧方法，并统一监听 fullscreenchange 事件优化状态响应（见下方增强建议）。

3. （可选）增强体验：监听全屏状态变化

为动态调整 UI（如图标、样式），建议监听全局 fullscreenchange 事件：

document.addEventListener('fullscreenchange', () => {
  const isFullscreen = !!document.fullscreenElement;
  // 可据此切换按钮图标（如 ? → ?）、显示/隐藏辅助提示等
  console.log('Fullscreen state:', isFullscreen ? 'ON' : 'OFF');
});

⚠️ 注意事项

• CSS 兼容性：全屏时容器内元素可能受浏览器默认样式影响（如 Chrome 全屏下
• 移动端适配：iOS Safari 对 requestFullscreen() 支持有限，需确保触发行为由用户手势（如 onclick）发起；playsinline 是必需属性。
• 无障碍支持：为按钮添加 aria-label（如 aria-label="Toggle fullscreen"），提升可访问性。
• 不要混用 video.controls：若同时启用原生控件（

通过将视频与控件封装为统一全屏单元，你不仅能彻底解决控件消失问题，还能获得更可控、更一致的全屏交互体验——这是构建专业级自定义播放器的关键一步。