如何通过 Picture-in-Picture API 实现视频 DOM 的异步画中画悬浮播放-js教程-PHP中文网

picture-in-picture（pip）api支持网页视频以悬浮窗播放，需满足可播放条件、用户手势触发及正确调用requestpictureinpicture()；需监听enter/leavepictureinpicture事件同步ui，并检测浏览器兼容性进行降级处理。

如何通过 picture-in-picture api 实现视频 dom 的异步画中画悬浮播放

Picture-in-Picture（PiP）API 允许网页视频脱离主页面、以独立悬浮窗口形式播放，且支持异步触发与 DOM 元素解耦。关键在于：视频元素必须满足可播放条件（如已加载元数据、用户手势触发、未静音或已获用户许可），且需主动调用 video.requestPictureInPicture() 并正确处理 Promise。

前提条件与 DOM 准备

确保 <video></video> 元素具备以下属性：

设置 controls 或至少有可交互的播放按钮（PiP 触发需用户手势）
若初始静音，需显式设置 muted="true"；否则首次进入 PiP 可能失败（Chrome 要求自动播放策略合规）
推荐添加 playsinline（iOS Safari 兼容）和 webkit-playsinline
避免在 loadstart 阶段立即调用 PiP —— 应等待 loadedmetadata 或 canplay 事件

异步触发 PiP 的标准流程

不依赖点击事件绑定，而是封装为可复用的异步函数，配合状态检查：

async function enterPictureInPicture(videoEl) {
  if (!document.pictureInPictureElement && videoEl.readyState >= videoEl.HAVE_METADATA) {
    try {
      await videoEl.requestPictureInPicture();
      console.log('已进入画中画');
    } catch (err) {
      console.warn('进入画中画失败：', err.name);
      // 常见错误：NotAllowedError（无用户手势）、SecurityError（跨域媒体）、NotSupportedError（浏览器不支持）
    }
  }
}

调用示例（如响应按钮点击或 URL 参数）：

document.getElementById('pip-btn').addEventListener('click', () => {
  enterPictureInPicture(myVideo);
});

监听与同步播放状态

PiP 窗口是独立上下文，但原视频 DOM 仍可控制播放/暂停，且会实时同步。建议监听以下事件保持 UI 一致性：

enterpictureinpicture：PiP 启动成功，可隐藏主界面控件
leavepictureinpicture：退出 PiP，恢复主界面显示
playing/pause：主视频状态变更时，PiP 内容自动跟随（无需额外操作）

例如：

myVideo.addEventListener('enterpictureinpicture', () => {
  document.body.classList.add('pip-active');
});
myVideo.addEventListener('leavepictureinpicture', () => {
  document.body.classList.remove('pip-active');
});

兼容性与降级处理

目前仅 Chromium 内核（Chrome ≥70）、Edge ≥79、Safari ≥14.1 原生支持；Firefox 尚未实现（截至 2024）。检测方式：

if ('pictureInPictureElement' in document && 'requestPictureInPicture' in HTMLVideoElement.prototype) {
  // 支持 PiP
} else {
  // 提供备用方案：弹出新窗口播放、或提示“请使用 Chrome/Safari”

注意：移动端（Android Chrome、iOS Safari）PiP 行为略有差异 —— iOS 需视频已播放过一次才允许再次进入 PiP，建议首次播放后缓存状态以便后续调用。