picture-in-picture 仅支持 元素，因 和 是静态容器或图像，无 requestpictureinpicture() 方法；该 api 必须由用户手势触发，且视频需已加载元数据、处于播放状态（或静音自动播放）。
目前无法通过纯 HTML 实现画中画（PiP）模式，Picture-in-Picture API 是 JavaScript 接口，必须由用户手势触发，且仅对 <video></video> 元素生效。
为什么 picture 或 img 标签不能用 PiP
<picture></picture> 是响应式图片容器，<img> 是静态图像元素，二者都不支持 requestPictureInPicture() 方法。浏览器只允许播放中的 <video></video>（含 src 或 MediaStream）调用该 API。
- 尝试对
<img>调用requestPictureInPicture()会抛出TypeError: requestPictureInPicture is not a function -
<video></video>必须已加载元数据（loadedmetadata事件后），且至少播放过一次（或设为muted并autoplay）才能成功调用 - 部分浏览器（如 Safari）要求视频有音频轨道（即使静音）才允许 PiP，否则拒绝调用
如何正确触发 requestPictureInPicture()
必须在用户显式交互（如点击、空格键）的事件处理函数中调用，不能放在 setTimeout、load 回调或自动播放完成时。
- ✅ 正确：绑定到按钮的
click事件，且该<video></video>已处于播放状态或可播放 - ❌ 错误：在
video.addEventListener('canplay', () => video.requestPictureInPicture())中直接调用 —— 缺少用户手势上下文 - 若视频未播放，先调用
video.play()（需静音：video.muted = true），再立即调用requestPictureInPicture()
const video = document.querySelector('video');
const pipBtn = document.querySelector('#pip-btn');
pipBtn.addEventListener('click', async () => {
try {
if (document.pictureInPictureElement) {
await document.exitPictureInPicture();
} else {
// 确保已加载且可播放
if (video.readyState video.addEventListener('loadedmetadata', r, { once: true }));
}
if (video.paused) {
video.muted = true;
await video.play();
}
await video.requestPictureInPicture();
}
} catch (err) {
console.error('PiP failed:', err.name); // 如 'NotAllowedError' 或 'NotFoundError'
}
});
常见失败原因和对应检查点
错误信息本身不直观，需逐项验证环境与状态。
-
NotAllowedError：最常见，说明调用不在用户手势内，或视频未满足播放前提（未play()、未静音、未加载元数据） -
NotFoundError：视频元素不存在、已被移除 DOM，或浏览器根本不支持 PiP（如旧版 Firefox 或某些 WebView） -
SecurityError：跨域视频未带crossorigin属性，或页面非 HTTPS（Chrome 要求安全上下文） - 移动端基本不支持 PiP（iOS Safari 完全禁用，Android Chrome 仅部分版本支持且需启用实验标志）
PiP 的实际可用性高度依赖浏览器版本、平台和用户设置，连 document.pictureInPictureElement 的存在都不能保证 PiP 当前可用 —— 它只表示“当前有元素在 PiP 模式”，不反映 API 是否可调用。真正麻烦的是那些静默失败的场景，比如按钮点了没反应，却没有任何错误抛出，这时候得回头检查视频的 readyState、paused、muted 和事件绑定时机。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
