video.requestPictureInPicture() 失败主因是未满足用户手势触发+视频已播放的硬性条件，须绑定click等事件、确保readyState≥2且play()已成功执行，并用document.pictureInPictureElement精准判断状态。
直接调用 video.requestPictureInPicture() 大概率失败，不是代码写错了，而是没满足浏览器的硬性触发条件——必须视频正在播放 + 用户点击等手势触发。
video.requestPictureInPicture() 报 NotAllowedError 怎么办
这是最常遇到的错误，典型报错是 NotAllowedError: play() can only be initiated by a user gesture 或 NotAllowedError: requestPictureInPicture() can only be called with a user gesture。根本原因不是权限或兼容性问题，而是调用时机不对。
- 视频元素必须已加载元数据（
video.readyState >= 2），且至少播放过一帧（video.play()成功执行过） - 不能在页面加载完成、自动播放、定时器回调里调用；必须绑定在
click、touchend等明确由用户发起的事件中 - 移动端 Safari 还要求
<video>标签带playsinline属性，否则即使点按钮也会静默失败 - 如果视频是静音自动播放（如背景视频），需确保已调用过
play()并 resolve，否则 PiP 请求会被拒绝
如何安全地切换画中画状态（进/出）
不能只靠按钮点击逻辑判断状态，必须以 document.pictureInPictureElement 为准。它返回当前处于 PiP 模式的 video 元素，为 null 表示未激活。
- 进入前检查：
if (!document.pictureInPictureElement) await video.requestPictureInPicture() - 退出时统一用
document.exitPictureInPicture()，不要对 video 调用exitPictureInPicture()（该方法不存在） - 退出后记得重置 UI，比如按钮文字：监听
leavepictureinpicture事件比轮询更可靠 - 注意：浏览器限制同一时间只能有一个 PiP 窗口，多次调用
requestPictureInPicture()不会打开多个，但可能触发leavepictureinpicture再enterpictureinpicture
怎么检测浏览器是否支持画中画
别只查 video.requestPictureInPicture 是否存在——它在旧版 Chrome 中存在但不可用。应优先使用标准能力检测 API。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 用
'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 / leavepictureinpicture 为什么没反应
事件监听必须在 video 元素上注册，且不能晚于 PiP 状态变化。常见失效原因是：监听器挂载太晚、video 被重新创建、或用了错误的事件名（比如漏掉 enter 前缀）。
- 确保监听写在 video 获取之后，且在用户可能触发 PiP 之前就绑定好
- 事件名是
enterpictureinpicture和leavepictureinpicture，全小写，无连字符，无驼峰 - PiP 是独立于页面生命周期的视图，退出 PiP 后用户可能切到其他标签页，此时
leavepictureinpicture仍会触发，但页面可能已不可见——别在里面做 DOM 操作，除非先 checkdocument.visibilityState === 'visible' - 调试时可用控制台快速验证：
document.pictureInPictureElement查当前状态，video.matches(':picture-in-picture')查该 video 是否正处在 PiP 中
真正容易被忽略的是：PiP 状态和 video 的播放状态解耦。视频暂停后 PiP 窗口仍存在，用户拖动 PiP 窗口大小也不会触发任何 JS 事件——这些交互完全由浏览器原生控制，前端无法干预。想做自定义控制（如拖拽缩放），得换 WebRTC 或 Canvas 合成方案，不再是原生 PiP。
