17370845950

video元素调用requestFullscreen()失败的主因是未在用户手势事件中同步调用，且需满足muted、可播放等浏览器策略限制；应绑定按钮click事件并兼容各厂商前缀，监听document的fullscreenchange事件处理状态变化。

video 元素调用 requestFullscreen() 失败的常见原因

直接在 video 元素上调用 requestFullscreen() 很可能报错：TypeError: Element.requestFullscreen is not a function 或静默失败。这不是浏览器不支持，而是因为：该方法必须由用户手势（如 click、touchend）触发，且不能在异步回调（如 setTimeout、Promise.then）中调用。

• requestFullscreen() 是受策略限制的 API，现代浏览器（Chrome 71+、Firefox 64+、Safari 12.1+）均要求调用栈中存在可信的用户交互事件
• 即使 video 元素已加载完成、可播放，也不能在 loadeddata 或 canplay 回调里调用它
• 部分浏览器（如 Safari）还要求 video 必须处于「可播放状态」——即至少调用过一次 play()（哪怕被暂停），否则全屏按钮可能被禁用

正确绑定全屏按钮的 DOM 操作方式

推荐用独立按钮（而非 video 自带 controls），显式绑定 click 事件，并在事件处理器中调用 video.requestFullscreen()。

全屏播放

• 不要用 video.controls = true 后依赖原生全屏按钮——它的行为不可控，且无法监听是否进入/退出全屏
• 移动端需注意：video 全屏通常由系统接管（如 iOS Safari 强制横屏），requestFullscreen() 可能被忽略；此时建议改用 webkitEnterFullscreen()（仅 Safari 移动端）
• 若视频未静音，Chrome 会拒绝全屏（报 NotAllowedError），务必加 muted 属性或先调用 video.muted = true

监听全屏状态变化与退出逻辑

不能只管进入，还要响应退出（比如用户按 ESC、点击返回）。浏览器通过 fullscreenchange 事件通知状态切换，但事件触发对象是 document，不是 video。

• document.fullscreenElement 返回当前全屏的元素，若为 null 表示未全屏
• 退出时不会自动暂停视频，需手动判断并调用 video.pause()（如果业务需要）
• 不要在 fullscreenchange 中再次调用 requestFullscreen()，极易造成循环或被浏览器拦截

CSS 适配与隐藏原生 controls 的必要性

全屏后，video 元素默认会拉伸填满屏幕，但原生 controls 在不同浏览器中位置、样式不可控，容易遮挡或错位。必须用 CSS 隐藏它，并自定义控制栏。

video::-webkit-media-controls {
  display: none !important;
}
video::part(controls-overlay) {
  display: none;
}
/* Firefox 需要额外规则 */
video:not([controls]) {
  /* 确保 controls 属性未启用 */
}

• 仅靠 controls="false" 不足以隐藏所有浏览器的原生控件（尤其是 Safari）
• 全屏状态下，video 的宽高比可能失真，建议用 object-fit: contain 或 cover 控制缩放
• 某些安卓 WebView 对 requestFullscreen() 支持不稳定，可 fallback 到调用 document.documentElement.requestFullscreen()（但会全屏整个页面，非仅 video）

全屏逻辑看似简单，真正卡住人的往往是「调用时机不可信」和「跨浏览器的隐式限制」——比如 Safari 要求先 play 再 request，Chrome 要求 muted，Firefox 对伪元素隐藏 controls 更敏感。写完记得在真机上测，模拟器经常骗人。