调用 video.requestPictureInPicture() 需同时满足用户手势触发、视频已播放、未设 disablePictureInPicture、跨域资源配 Access-Control-Allow-Origin 且页面在前台；iOS 还需 playsinline 等适配。
直接调用 video.requestPictureInPicture() 大概率失败，不是代码写错了，而是浏览器在多个环节卡你——必须同时满足用户手势、播放状态、属性标记、跨域策略这四层校验，缺一不可。
为什么点按钮没反应，控制台也不报错？
这是最常被忽略的静默失败场景。PiP 不是“调了就进”，而是“全链路合规才进”。以下任一条件不满足，都会点击无响应、无日志、无提示：
-
video元素设置了disablePictureInPicture属性（包括 JS 动态设置） - 视频是跨域资源，且服务端未返回
Access-Control-Allow-Origin: *（Chrome 严格校验） - 视频尚未触发过
play()，哪怕只播了 1ms —— 暂停状态 + 从未播放 = 不可进 PiP - 页面不在前台标签页（部分浏览器禁止后台触发）
- 移动端 Safari 未加
playsinline和webkit-playsinline，导致默认全屏，PiP 控制项压根不出现
怎么确保 requestPictureInPicture() 调用成功？
关键不是“怎么写”，而是“在什么时机、以什么方式写”。必须同步、直接、紧贴用户手势：
- 绑定在
click或touchend事件回调里，不能包裹在setTimeout、Promise.then、requestIdleCallback中 - 必须
await，否则可能静默失败（尤其 Chrome 90+） - 调用前检查
video.readyState >= HTMLMediaElement.HAVE_METADATA，推荐监听canplay或loadedmetadata后再启用按钮 - 移动端 iOS Safari 16.4+ 才支持 JS 主动调用；16.4 之前只能靠系统控制中心唤起，JS 只能监听
enterpictureinpicture
如何正确监听和退出画中画？
别依赖按钮点击逻辑做状态判断，PiP 是独立于页面的系统级窗口，状态变化必须靠事件和全局属性捕获：
立即学习“前端免费学习笔记（深入）”；
- 监听
enterpictureinpicture和leavepictureinpicture事件，而不是只看按钮是否点了 - 退出时优先调用
video.exitPictureInPicture()（Chrome 114+ 已废弃document.exitPictureInPicture()） - 检查当前状态用
document.pictureInPictureElement，它非null表示有活跃 PiP 窗口 - 注意：退出 PiP 后视频仍继续播放，如需暂停，得在
leavepictureinpicture回调里手动调video.pause()
移动端（尤其是 iOS Safari）的特殊限制
iOS 的 PiP 行为和其他平台根本不是一个东西。JS 能做的非常有限，重点不是“怎么进”，而是“怎么适配”：
- 不支持
requestPictureInPicture()主动调用（iOS 16.4+ 仅限部分设备/系统组合，且仍需playsinline+ 用户已播放过） - 必须加
playsinline和webkit-playsinline，否则视频强制全屏，PiP 图标不会出现在控制栏 - PiP 入口在锁屏控制中心或上滑控制中心，不在页面内；JS 只能监听
enterpictureinpicture做响应（比如隐藏原视频 DOM） - 无法控制窗口尺寸、位置、是否可关闭——这些完全由系统决定，网页 CSS 对 PiP 窗口本身无效
真正难的从来不是那行 requestPictureInPicture()，而是让 video 加载、播放、属性、手势、跨域、移动端上下文全部对齐——漏掉任意一环，用户点十次按钮都像没反应一样。
