HTML中使用Picture-in-Picture API将视频以画中画模式悬浮的方法

画中画必须通过JavaScript的requestPictureInPicture()在用户手势中触发，且video需预先设置allowpictureinpicture属性；移动端Safari还需playsinline；调用前须确保视频就绪并处理跨域与静音兼容性。

不能直接用 HTML 标签属性“开启”画中画，allowpictureinpicture 只是允许调用的前提，真正触发必须靠 JavaScript 的 requestPictureInPicture()，且只能在用户手势中执行。

video 元素必须显式启用 picture-in-picture 功能

allowpictureinpicture 是必需的布尔属性，不加就直接报 NotAllowedError。它不是可选优化项，而是浏览器强制的开关。

• 写法只能是 <video allowpictureinpicture>（无值）或 <video allowpictureinpicture="">，不能写成 allowpictureinpicture="true"
• 动态设置无效：运行时改 videoEl.allowPictureInPicture = true 不起作用；必须在 DOM 初始化时就存在该属性
• 移动端 Safari 还额外要求 playsinline 和 webkit-playsinline，否则即使属性齐全也进不了 PiP

requestPictureInPicture() 必须由用户手势触发

几乎所有失败都卡在这一步：浏览器会静默拒绝非用户直接触发的调用，错误通常是 NotAllowedError: Document not active or user gesture not detected。

• ✅ 正确场景：绑定在 click、touchend 事件处理器里，且该 handler 是用户真实点击按钮/视频控件触发的
• ❌ 错误场景：在 setTimeout、loadedmetadata 回调、play() 的 Promise resolve 后、fetch 完成后调用 —— 这些都不算“用户手势上下文”
• ⚠️ 注意：mouseenter、focus、input 等事件也不被认可；只有明确的激活型交互才有效

调用前必须确保 video 已就绪且可播放

视频未加载元数据就调用，会抛 NotFoundError 或 NotAllowedError；Safari 尤其严格，静音状态也可能被拦截。

立即学习“前端免费学习笔记（深入）”；

• 监听 canplay 或 loadeddata 事件后再绑定按钮逻辑，比监听 DOMContentLoaded 更可靠
• 若需自动播放，务必加 muted="true"（Chrome 要求），但 iOS Safari 反而要求**不能静音**才能进 PiP，得按平台分支处理
• 跨域视频（如 CDN 上的 MP4）需带 crossorigin="anonymous"，否则可能触发 SecurityError

如何安全地进入和退出画中画

不能只依赖用户点关闭按钮，主动控制和状态同步才是关键。尤其要注意 document.exitPictureInPicture() 的调用时机和错误处理。

• 进入前先检查：if (!document.pictureInPictureElement)，避免重复调用导致 Promise 拒绝
• 退出时用 document.exitPictureInPicture()，它返回 Promise；失败可能是 NotFoundError（当前没 PiP 窗口）
• 监听 enterpictureinpicture 和 leavepictureinpicture 事件来切换 UI 状态（比如按钮文字、暂停主页面音频等）
• 注意：PiP 退出后，video 仍继续播放，是否暂停得手动控制，这点常被忽略