HTML5视频全屏播放设置教程

HTML5视频在移动端（尤其是iOS Safari）实现全屏播放远非简单添加`allowfullscreen`属性即可，而需严格满足五大条件：同时声明`allowfullscreen`与旧版Safari必需的`webkitallowfullscreen`属性；确保视频格式为H.264+AAC编码的MP4、尺寸不小于320×240；避免父容器使用`transform`、`fixed`定位、`overflow: hidden`等干扰全屏渲染的CSS；全屏调用必须由用户手势（如click）直接触发，严禁置于异步逻辑中；并谨慎处理`playsinline`属性——它虽支持微信内自动播放，却会彻底禁用iOS原生全屏入口。任一环节疏漏都可能导致按钮无响应、白屏或静默失败，唯有五点齐备，才能真正打通跨浏览器、跨平台的全屏体验。

video 标签没加 webkitallowfullscreen 和 allowfullscreen 属性

HTML5 在 Chrome、Safari、Edge 等浏览器中默认禁用全屏，必须显式声明允许。只写 allowfullscreen 不够——老版 Safari（iOS 10 / macOS 10.12 之前）还依赖 webkitallowfullscreen。

正确写法示例：

• allowfullscreen 是标准属性，现代浏览器都认
• webkitallowfullscreen 是 Safari/WebKit 旧版本的兼容补丁，不加可能导致 iOS Safari 点击全屏按钮无响应
• 如果用了 iframe 嵌套视频（比如 YouTube），则需在 iframe 上加 allow="fullscreen"

父容器或 CSS 强制限制了全屏行为

即使 属性齐全，若它被包裹在 position: fixed、transform、overflow: hidden 或设置了 z-index 的容器里，全屏后可能被裁剪、错位甚至触发白屏。

常见问题场景：

• Modal 弹窗内嵌视频：弹窗本身有 transform: scale() 或 will-change: transform，会干扰全屏渲染层
• 使用了 CSS Grid/Flex 布局且子项设了 align-self: center 等，全屏时布局重算异常
• 全局 CSS 重置了 video 的 display（如设为 inline），而全屏需要 block 行为

临时排查方法：全屏后右键检查元素，看是否被某个父级 overflow: hidden 截断，或是否有 transform 层叠上下文干扰。

JavaScript 调用 requestFullscreen() 失败报错 “Document not focused”

浏览器强制要求：全屏 API 必须由用户手势（如 click、touchend）直接触发，不能放在异步回调（setTimeout、Promise.then）、定时器或自动播放逻辑里。

典型错误写法：

video.addEventListener('canplay', () => {
  setTimeout(() => video.requestFullscreen(), 100); // ❌ 非直接手势，被拒绝
});

正确做法：

• 绑定到明确的用户操作上，例如自定义全屏按钮的 click 事件
• 确保调用前视频已加载就绪（readyState >= 3），否则部分浏览器会静默失败
• 捕获异常并提示用户（如 document.fullscreenElement 为 null 且无报错时，可能是策略拦截）

移动端（尤其是 iOS Safari）全屏仍不生效

iOS Safari 对 全屏有额外限制：仅当视频满足以下全部条件时，才允许原生全屏控件出现：

• 未设置 playsinline 属性（加了它就会强制行内播放，禁用全屏按钮）
• 视频格式为 H.264 编码 + AAC 音频（MP4 容器），WebM 在 iOS 不支持全屏
• 视频尺寸大于等于 320×240 像素（太小的视频会被忽略全屏能力）
• 页面未启用 viewport 的 user-scalable=no（会间接禁用某些手势响应）

注意：playsinline 是双刃剑——它让视频在微信、QQ 内置浏览器里能自动播放，但代价是彻底关掉 iOS 原生全屏入口。如需兼顾，得用 UA 检测 + 动态移除该属性。

全屏不是万能开关，尤其在移动端，每个系统都在悄悄加自己的规则。最稳的方式，是把 allowfullscreen、webkitallowfullscreen、格式、尺寸、触发时机这五点全对齐，缺一不可。

今天关于《HTML5视频全屏播放设置教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！