必须同时设置 playsinline 和 webkit-playsinline 属性,且在 HTML 中硬编码;需配合 controls 或用户手势触发 requestFullscreen();autoplay 必须搭配 muted 才能生效。

video 标签必须加 webkit-playsinline 和 playsinline
iOS Safari 默认禁止 在非全屏模式下内联播放(尤其在微信、企业微信等 WebView 中更严格),不加这两个属性,点击全屏按钮可能无响应或直接黑屏。注意:webkit-playsinline 是旧版 Safari 专用,playsinline 是 HTML5 标准属性,二者需同时存在才稳定生效。
常见错误写法: 单独写,或漏掉 webkit- 前缀;也有人误写成 playinline(少一个 s)导致失效。
-
webkit-playsinline必须作为属性存在,不能靠 JS 动态添加(iOS Safari 不识别运行时注入) - 若用 Vue/React 等框架,确保该属性在初始 render 时就存在于 DOM 元素上
- 部分 iOS 版本(如 iOS 16.4+)对
playsinline的校验更严,建议两个都写且拼写准确
必须设置 controls 或手动绑定全屏事件
iOS Safari 要求视频有用户手势触发(比如点击)才能进入全屏,且仅当 含 controls 属性,或你用 JS 显式调用 requestFullscreen() 并在用户事件回调中执行,否则会静默失败。
错误现象:点击自定义全屏按钮没反应,控制台无报错,但 video.webkitSupportsFullscreen 返回 true —— 这说明权限没问题,只是触发时机不对。
立即学习“前端免费学习笔记(深入)”;
- 最简方案:加上
controls属性,让系统原生控件接管全屏逻辑 - 如需自定义 UI,必须在
click/touchend回调里调用videoEl.requestFullscreen()(注意不是webkitEnterFullscreen,后者已废弃) - 避免在
autoplay后立即调用全屏,iOS 不允许无用户交互的全屏请求
避免使用 webkit-playsinline="false" 或动态移除该属性
有些项目为了“兼容安卓”而做运行时判断,JS 里根据 UA 移除 webkit-playsinline,结果在 iOS 上彻底失去内联能力,导致视频强制跳转全屏且无法退出 —— 实际上,这个属性只影响「是否允许内联播放」,不影响「能否全屏」;它被移除后,iOS 反而更难控制行为。
更隐蔽的问题:某些构建工具(如 Webpack + html-loader)会自动过滤未知属性,把 webkit-playsinline 当作非法属性删掉,需检查最终生成的 HTML 是否还存在该字符串。
- 始终在 HTML 源码中硬编码
webkit-playsinline和playsinline - 不要依赖 JS 动态增删,也不要基于 UA 做条件渲染
- 用 Safari 开发者工具远程调试真机,检查元素属性是否真实存在
autoplay + muted 是绕过静音限制的前提
即使设置了全屏相关属性,如果视频带声音且未静音,iOS Safari 仍可能阻止自动播放,进而影响后续全屏逻辑(例如:视频没加载完成,requestFullscreen() 调用会失败)。
典型报错不会直接提示,但 video.readyState 长期为 0 或 video.paused 始终为 true,就是 autoplay 被拦截了。
- 必须同时满足:
autoplay+muted+playsinline+webkit-playsinline - 若需有声播放,只能靠用户点击后调用
video.muted = false再play(),但此时再调全屏依然要走用户手势链 - 不要用
preload="auto"强制预加载,iOS 对此不敏感,反而增加首帧延迟
requestFullscreen() 的 Promise 返回做了更严格的上下文校验。










