video 元素必须显式启用 pictureInPictureEnabled
默认情况下，<video> 元素的画中画功能是禁用的，即使浏览器支持（Chrome 70+、Edge 79+、Safari 14.1+），也必须手动开启。不设置这个属性，调用 requestPictureInPicture() 会直接抛出 NotAllowedError。
实操建议：
- 在 HTML 中添加
pictureinpicture属性（布尔属性，有即启用）：<video controls pictureinpicture> - 或在 JS 中动态启用：
videoEl.pictureInPictureEnabled = true（注意：该属性只读，只能通过 HTML 属性或document.createElement('video')后立即设为true来生效；运行时设无效） - 移动端 Safari 需额外满足：视频必须有
playsinline+webkit-playsinline，且不能处于静音状态（muted会导致 iOS 拒绝进入 PiP）
触发 requestPictureInPicture() 必须是用户手势驱动
浏览器强制要求画中画切换必须由用户真实交互（如 click、touchend）触发，否则会拒绝并报错 NotAllowedError: Document not active or user gesture not detected。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
- 在
setTimeout、loadedmetadata回调、自动播放完成时直接调用 —— 必败 - 绑定到
mouseenter或focus这类非激活型事件 —— 不算有效手势
正确做法：
- 只在
click或touchend的事件处理器中调用：videoEl.requestPictureInPicture() - 如果需要“播放后自动进 PiP”，可先监听
play事件，再在后续用户点击按钮时执行（不能跳过用户点击） - 避免在 Promise 链中异步调用（例如
video.play().then(() => btn.click())不算用户手势）
监听 enterpictureinpicture 和 leavepictureinpicture 事件做状态同步
PiP 状态变化不会自动更新 DOM 或元素属性，需手动响应事件来维护 UI 一致性（比如切换按钮图标、暂停主页面视频等）。
使用场景与注意事项：
-
enterpictureinpicture触发时，原<video>仍保持播放状态，但视觉上已脱离文档流；此时适合暂停主界面视频（避免声音重复）或隐藏控制栏 -
leavepictureinpicture触发时，PiP 窗口已关闭，但视频可能仍在后台缓冲；应恢复 UI，并考虑是否重新聚焦主 video 元素 - Safari 在退出 PiP 后可能触发
pause事件，而 Chrome 不一定，不要依赖此行为做逻辑分支 - 事件监听必须在
video元素上注册，且需在元素插入 DOM 后、用户触发前完成绑定
兼容性兜底：检测 document.pictureInPictureElement 和 API 存在性
不是所有环境都支持 PiP：Firefox 桌面版至今（v128）仅支持实验性 flag，Android WebView 支持不稳定，旧版 Edge 完全不支持。硬调用会报 TypeError: videoEl.requestPictureInPicture is not a function。
安全调用方式：
- 先检查 API 是否可用：
if ('requestPictureInPicture' in videoEl) - 再检查当前是否有 PiP 窗口：
if (document.pictureInPictureElement === videoEl)可用于判断是否已在 PiP 中 - 对不支持的环境，降级显示「仅桌面 Chrome/Edge/Safari 可用」提示，或提供截图+音频下载等替代方案
- 注意：Safari 的
document.pictureInPictureElement在 PiP 期间返回null（bug 行为），需结合videoEl.webkitPresentationMode === 'picture-in-picture'判断
画中画看似简单，但跨浏览器的手势约束、iOS 静音限制、事件时机差异，让实际集成比 video.play() 复杂得多。最常被忽略的是：Safari 要求非静音 + playsinline + 用户点击三者同时满足，缺一不可。
