picture-in-picture api 并非支持所有 video 元素，仅用户手势触发、非静音受限、且 readystate≥1 的视频可调用 requestpictureinpicture()；需正确处理 promise 拒绝、监听 leavepictureinpicture 事件恢复状态，并兼顾 safari 等兼容性限制。
Picture-in-Picture API 是否支持所有 HTML <video></video> 元素
不是。只有满足特定条件的 <video></video> 才能调用 requestPictureInPicture()：必须是用户手势（如 click 或 touchend）触发；不能处于静音且 muted 属性为 false 且未获用户媒体授权时自动播放；需已加载元数据（readyState >= 1）。常见错误是直接在 autoplay 启动后立即调用，结果抛出 NotAllowedError: Permission denied。
实操建议：
- 监听
canplay或loadeddata事件后再绑定按钮点击逻辑 - 确保视频有
controls或显式设置muted="true"（若需自动播放） - 避免在
DOMContentLoaded里直接调用 —— 此时视频大概率未就绪
如何正确调用 requestPictureInPicture() 并处理失败
调用本身很简单，但错误处理不可省略。该方法返回 Promise，拒绝时可能因权限、状态或浏览器不支持而失败。
实操建议：
- 始终用
try/catch或.catch()捕获拒绝原因 - 检查
document.pictureInPictureElement判断当前是否已在画中画模式 - 对
NotFoundError（视频未附加到 DOM）、SecurityError（跨域资源未加crossorigin属性）等做区分提示
示例片段：
button.addEventListener('click', async () => {
try {
await video.requestPictureInPicture();
} catch (err) {
if (err.name === 'NotAllowedError') {
console.warn('需用户手势触发');
} else if (err.name === 'NotFoundError') {
console.warn('video 元素未挂载到页面');
}
}
});
退出画中画后如何恢复 UI 状态
用户点击关闭按钮、按 ESC 或调用 document.exitPictureInPicture() 时，会触发 leavepictureinpicture 事件，但不会自动恢复播放或焦点 —— 这点容易被忽略。
实操建议：
- 监听
video.addEventListener('leavepictureinpicture', ...)，而非只依赖全局document事件 - 退出后手动聚焦回原视频或控制按钮，提升可访问性
- 若视频曾被暂停，退出时通常仍为暂停状态，需根据业务逻辑决定是否自动
play() - 注意：Safari 目前不支持
leavepictureinpicture事件，需轮询document.pictureInPictureElement变化
兼容性与降级方案的关键检查点
document.pictureInPictureEnabled 仅表示 API 可用，不代表当前上下文允许调用；iOS Safari 完全不支持，Android Chrome 71+、Desktop Edge 79+、Firefox 71+ 支持有限制。
实操建议：
- 用
'pictureInPictureElement' in document替代过时的pictureInPictureEnabled - 按钮 UI 应动态显示/隐藏：
video.disablePictureInPicture属性为true时强制禁用（如某些嵌入式 iframe 视频） - 降级方案别只写“不支持”，可提供最小化弹窗控件（含播放/暂停/音量），模拟画中画体验
- 服务端检测 UA 不可靠，必须客户端运行时判断
画中画不是开关式功能，它的生命周期、状态同步和异常分支比表面看起来更琐碎。尤其在移动端混合 WebView 场景下，pictureInPictureElement 可能突然变为 null 而无事件通知 —— 这时候轮询加防抖是实际项目里绕不开的一环。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
