HTML实现视频画中画（Picture-in-Picture）【最新】

直接调用 video.requestPictureInPicture() 大概率会翻车，这不是因为你代码写错了，而是触发时机没卡对——浏览器要的是“视频正在播放”加上“用户用手点出来的”，缺一不可。

先说几个核心判断。这个问题之所以烦人，是因为它跟权限、兼容性都没太大关系，纯粹是调用姿势不够“标准”。你绑个 click 或者 touchend，确保 video.readyState >= 2，并且在 play() 成功之后再发起请求，基本就能搞定。

video.requestPictureInPicture() 报 NotAllowedError 怎么办

这是最常碰到的错误，典型的报错信息是 NotAllowedError: play() can only be initiated by a user gesture 或者 requestPictureInPicture() can only be called with a user gesture。说白了一个意思：你调早了，或者不是用户亲手点的。

要避开这个坑，需要记牢几个硬性条件：

• 视频元素必须已经加载了元数据（video.readyState >= 2），并且至少播放过一帧（video.play() 必须成功执行过）
• 绝对不能放在页面初始化、自动播放或者定时器回调里调用；必须绑定在 click、touchend 等用户明确发起的事件中
• 移动端 Safari 还有额外的门槛： 标签上得带 playsinline 属性，不然就算你点了按钮，也会悄无声息地失败
• 如果视频是静音自动播放（比如背景视频），要确保之前已经调过 play() 并且 resolve 了，否则 PiP 请求会被直接拒掉

如何安全地切换画中画状态（进/出）

切换状态这事儿，不能凭想象，得靠 document.pictureInPictureElement 这个“官宣”来判断。它返回的是当前正在 PiP 模式下的 video 元素；如果是 null，说明还没进画中画。

• 进入之前先查一下：if (!document.pictureInPictureElement) await video.requestPictureInPicture()
• 退出的时候统一用 document.exitPictureInPicture()，千万别对着 video 调 exitPictureInPicture()——这个方法不存在，会直接报错
• 退出之后要记得更新 UI，比如按钮的文案。更好的做法是监听 lea vepictureinpicture 事件，比轮询靠谱得多
• 注意：浏览器同一时间只能有一个 PiP 窗口。如果你连续多次调 requestPictureInPicture()，它不会打开多个，但可能会先触发 lea vepictureinpicture 事件，再触发 enterpictureinpicture

怎么检测浏览器是否支持画中画

别只查 video.requestPictureInPicture 这个属性是否存在——在旧版 Chrome 里它虽然存在，但不可用。必须优先使用标准的能力检测 API。

• 用 'pictureInPictureEnabled' in document 来判断整体支持性（Chrome 71+、Edge 79+、Firefox 71+、Safari 14.1+）
• 再加一层运行时校验：if (document.pictureInPictureEnabled && video.src)，避免空 src 导致后续调用失败
• 移动端要格外小心：Android Chrome 是支持的，但大部分安卓 WebView 和 iOS Safari（除了最新版本）要么不支持，要么只限特定场景（比如全屏之后）
• 不支持的时候，建议直接禁用按钮：pipBtn.disabled = true，再配上一段提示文案，而不是把按钮隐藏起来——这对无障碍更友好

监听 enterpictureinpicture / lea vepictureinpicture 为什么没反应

事件监听必须在 video 元素上注册，而且不能晚于 PiP 状态变化。常见翻车原因是：监听器挂载得太晚、video 被重新创建了、或者用错了事件名（比如漏了 enter 前缀）。

• 确保监听逻辑写在获取 video 之后，并且在用户可能触发 PiP 之前就已经绑定好了
• 事件名是 enterpictureinpicture 和 lea vepictureinpicture，全小写，没有连字符，也不是驼峰写法
• PiP 独立于页面生命周期，用户退出 PiP 后可能切到其他标签页，此时 lea vepictureinpicture 依然会触发，但页面可能已经不可见了——最好别在里面做 DOM 操作，除非先检查 document.visibilityState === 'visible'
• 调试时可以用控制台快速验证：document.pictureInPictureElement 看当前状态，video.matches(':picture-in-picture') 看某个 video 是否正处在 PiP 中

必须警惕的是：PiP 状态和视频的播放状态是解耦的。视频暂停之后 PiP 窗口依然存在，用户拖动 PiP 窗口大小也不会触发任何 JS 事件——这些交互全都由浏览器原生控制，前端根本插不上手。如果你想做自定义控制，比如拖拽缩放，那就得换 WebRTC 或者 Canvas 合成方案了，原生 PiP 管不了那么宽。