告别传统弹窗！探索 Document Picture-in-Picture API 的现代浮窗方案

在前端开发中，浮窗交互是一个常见的需求，无论是实时数据展示、在线客服，还是视频画中画播放，我们都需要一个优雅的解决方案。过去，开发者通常使用 window.open() 或 Modal（模态框），但它们各有局限：

• window.open() 容易被浏览器拦截，且用户体验较差。
• Modal 只能在当前页面显示，切换标签页后即消失。

现在，浏览器提供了一个更先进的 API——Document Picture-in-Picture (PiP) API，它允许我们创建独立置顶、跨标签页显示的浮窗，适用于实时监控、悬浮工具栏、直播小窗等场景。

本文将带你深入了解 Document PiP API，并与传统 Modal 方案进行对比，帮助你选择最适合的浮窗方案！

1. 为什么需要 Document PiP API？

传统浮窗方案存在以下问题：

而 Document PiP API 的优势在于：
✅ 独立窗口，不受当前页面影响
✅ 浏览器级置顶，不会被遮挡
✅ 支持任意 HTML 内容（不只是视频）
✅ 不会被弹窗拦截器阻止

2. Document PiP API vs. Modal vs. Video PiP

3. 快速上手 Document PiP API

（1）检查浏览器支持

const isSupported = "documentPictureInPicture" in window;
if (!isSupported) {
  console.log("当前浏览器不支持 Document PiP API");
}

（2）创建浮窗

async function openPipWindow() {
  if (!("documentPictureInPicture" in window)) return;

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: 400,  // 宽度
    height: 300, // 高度
  });

  // 设置浮窗内容（支持 HTML 字符串）
  pipWindow.document.body.innerHTML = `
    <div style="padding: 20px; background: #f0f0f0;">
      <h2>🎉 自定义浮窗</h2>
      <p>这是对 window.open 的完美替代！</p>
    </div>
  `;
}

（3）关闭浮窗

pipWindow.close();  // 手动关闭

4. 典型应用场景

（1）实时数据仪表盘

const pipWindow = await documentPictureInPicture.requestWindow();
pipWindow.document.body.innerHTML = `
  <div style="background: #1a1a1a; color: white; padding: 20px;">
    <h3>📈 实时指标</h3>
    <div>当前在线：245</div>
    <div>异常警告：2</div>
  </div>
`;

（2）在线客服浮窗

const chatWindow = await documentPictureInPicture.requestWindow();
chatWindow.document.body.innerHTML = `
  <div style="padding: 10px; font-family: sans-serif;">
    <h4>🧑‍💼 在线客服</h4>
    <div style="height: 200px; overflow-y: auto; border: 1px solid #ccc;">
      欢迎咨询，我们在线！
    </div>
    <input type="text" placeholder="输入您的问题..." style="width: 100%; margin-top: 10px;">
  </div>
`;

（3）视频画中画（Video PiP）

如果只需要视频浮窗，可以使用更简单的 Video PiP API：

<video id="myVideo" controls>
  <source src="video.mp4" type="video/mp4">
</video>
<button onclick="togglePiP()">📺 画中画</button>

<script>
  async function togglePiP() {
    const video = document.getElementById("myVideo");
    if (!document.pictureInPictureElement) {
      await video.requestPictureInPicture(); // 开启画中画
    } else {
      await document.exitPictureInPicture(); // 退出画中画
    }
  }
</script>

5. 最佳实践 & 注意事项

（1）错误处理

try {
  const pipWindow = await documentPictureInPicture.requestWindow();
} catch (error) {
  if (error.name === "NotAllowedError") {
    console.log("用户拒绝了浮窗权限");
  }
}

（2）响应式尺寸调整

const pipWindow = await documentPictureInPicture.requestWindow({
  width: Math.min(400, window.innerWidth * 0.8),
  height: Math.min(300, window.innerHeight * 0.8),
});

（3）动态更新浮窗内容

// 在浮窗内运行脚本
pipWindow.document.body.innerHTML = `
  <div id="content">Hello World!</div>
  <script>
    setInterval(() => {
      document.getElementById("content").textContent = new Date().toLocaleTimeString();
    }, 1000);
  <\/script>
`;

6. 总结：如何选择合适的浮窗方案？

Document PiP API 特别适合需要跨标签页显示、浏览器级置顶的场景，如：

• 实时监控仪表盘
• 在线客服聊天窗
• 悬浮工具面板

如果你的项目需要更灵活的浮窗交互，不妨尝试这个现代 API！ 🚀

🔗 MDN 文档：Document Picture-in-Picture API