真正符合Web标准的画中画仅支持pictureInPictureEnabled+requestPictureInPicture()机制，需满足文档激活、用户手势触发、video就绪且无CORS限制等条件。
HTML 画中画（Picture-in-Picture）就是小窗播放，但「小窗播放」这个词更宽泛，容易和悬浮窗、自定义浮动 div 混淆。真正符合 Web 标准、能跨标签页/应用持续播放、由浏览器原生支持的，只有 pictureInPictureEnabled + requestPictureInPicture() 这一套机制。
如何判断浏览器是否真正支持 HTML 画中画
不能只看有没有 requestPictureInPicture 方法，还要确认当前上下文满足条件：
-
document.pictureInPictureEnabled必须为true（部分浏览器禁用 PiP 时会返回false） - 触发必须是用户手势（如
click、touchend），不能在setTimeout或load回调里直接调用 -
video元素必须已加载元数据（readyState >= 1），且未设置disablePictureInPicture属性 - 视频源不能是
blob:或受 CORS 限制且未带crossorigin的资源（否则requestPictureInPicture()会静默失败）
requestPictureInPicture() 失败的常见错误信息
这些错误不会弹框提示，全靠 .catch() 捕获：
-
"Failed to execute 'requestPictureInPicture' on 'HTMLVideoElement': Document is not active."→ 页面被切到后台或 iframe 失焦 -
"Failed to execute 'requestPictureInPicture' on 'HTMLVideoElement': The document is not in focus."→ 当前 tab 没有获得焦点（比如从另一个窗口点击触发） -
"NotAllowedError: play() can only be initiated by a user gesture."→ 视频还没播过，没建立媒体播放许可（可先调一次video.play().catch(() => {})唤醒）
为什么加了 pictureInPicture:true 配置却没按钮
这是第三方播放器 SDK（比如 Polyv、Hls.js 封装层）的配置项，和原生 HTML5 PiP 无关。它只是控制是否渲染一个“小窗按钮”，实际点击后仍要调用原生 video.requestPictureInPicture()。常见陷阱：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- SDK 内部没做
readyState判断，用户点太快导致调用失败 - 播放器用了
video克隆或代理元素，但事件绑定在非真实video上 - 某些安卓 WebView（如旧版腾讯 X5）不支持 PiP，但 SDK 仍显示按钮，点下去无响应
- Chrome Android 要求页面启用
display-capture权限才允许 PiP，否则静默拒绝
移动端真机调试 PiP 的关键点
桌面端 Chrome/Firefox 支持良好，但移动端差异大：
- iOS Safari：PiP 只在全屏播放时右上角出现小窗按钮，不支持 JS 主动调用
requestPictureInPicture() - Android Chrome：需开启系统级「悬浮窗权限」，否则 PiP 窗口无法脱离浏览器浮起
- 微信内置浏览器（X5 内核）：默认禁用 PiP，
pictureInPictureEnabled永远是false，别白费劲 - 鸿蒙 ArkTS 应用：要用
@ohos.PiPWindow模块，不是 HTML5 API，得走create()+startPiP()流程
PiP 行为高度依赖浏览器实现和系统策略，同一段代码在 Chrome Desktop、Chrome Android、Safari iOS、微信里表现可能完全不同。最稳妥的做法是：先检查 document.pictureInPictureEnabled，再监听 enterpictureinpicture 和 leavepictureinpicture 事件做 UI 同步，失败时降级为页面内缩放播放，而不是强行兜底。
