要实现规范全屏逻辑，必须由用户手势触发requestfullscreen()，以document.fullscreenelement为唯一状态依据，统一调用document.exitfullscreen()退出，并监听fullscreenchange事件更新ui。

要用 Fullscreen API 实现原始、可靠且符合规范的全屏切换与退出逻辑，核心是紧扣浏览器原生行为：必须由用户手势触发、以 document.fullscreenElement 为唯一事实依据、统一通过 document.exitFullscreen() 退出，并正确处理 Promise 和兼容性。

确保调用发生在用户手势上下文中

requestFullscreen() 只能在 click、touchend、keydown（需有用户交互历史）等用户主动触发的回调中执行。在页面加载、setTimeout、fetch 回调里直接调用会静默失败，控制台报错 “API can only be initiated by a user gesture”。

• ✅ 正确做法：给按钮绑定 click 事件，在回调中调用目标元素的 requestFullscreen()
• ✅ 确保目标元素已挂载：调用前检查 document.body.contains(el)，避免因 DOM 未就绪导致报错
• ❌ 不要对 document 或 document.documentElement 调用 requestFullscreen() —— 现代浏览器不支持整个页面级全屏，应作用于具体容器（如 <div id="player"> 或 <code><video></video>）

  用 document.fullscreenElement 判断真实状态

  不要用布尔变量缓存状态，也不依赖事件触发次数。每次需要判断时，直接读取 document.fullscreenElement：

  • 值为 null → 当前未全屏
  • 值为某个 HTMLElement（如 <video></video>）→ 该元素正处于全屏状态
  • 注意拼写：是 fullscreenElement（全小写），不是 fullScreenElement 或 FullScreenElement
  • 旧版浏览器需兼容前缀：可封装为 document.fullscreenElement || document.webkitFullscreenElement || document.mozFullScreenElement || document.msFullscreenElement

  统一使用 document.exitFullscreen() 退出

  退出操作始终调用 document.exitFullscreen()，它返回 Promise，成功后将 document.fullscreenElement 设为 null。

  • ✅ 标准调用：document.exitFullscreen().catch(e => console.warn('Exit failed:', e))
  • ✅ 兼容写法（仅当需支持极旧版本）：document.exitFullscreen || document.webkitExitFullscreen || document.mozCancelFullScreen || document.msExitFullscreen
  • ❌ 不要尝试对原元素调用类似 el.exitFullscreen() —— 该方法不存在，只存在于 document 上

  监听状态变化并响应 UI 更新

  全屏切换是异步过程，必须监听 fullscreenchange 事件来获知最终结果，该事件只在 document 上触发。

  • 注册监听：document.addEventListener('fullscreenchange', () => { /* 检查 document.fullscreenElement 并更新按钮文字、隐藏工具栏等 */ })
  • 建议同时监听带前缀的事件（如 webkitfullscreenchange、mozfullscreenchange）以覆盖 Safari 12–14、Firefox
  • CSS 层面可用 video:fullscreen 或 #viewer:fullscreen 设置全屏专属样式，注意伪类必须作用于实际进入全屏的元素本身