在前端开发中，我们经常会遇到这样的需求：弹出一个浮动窗口来显示一些实时信息、工具栏或视频内容。过去我们会用 window.open()，后来越来越多的开发者倾向于使用 Modal。但现在，一个更现代的 API 出现了——Document Picture-in-Picture API，它能带来一种完全不同的浮窗体验。

为什么我们需要新的解决方案？

传统的 window.open() 虽然简单易用，但限制非常多：

❌ 容易被浏览器拦截（尤其是在移动端）
❌ 用户体验差（新窗口可能被挡住）
❌ 样式控制受限（几乎无法用 CSS 美化）
❌ 无法保证窗口始终置顶

Modal（模态框）虽然解决了很多问题，但它始终依附于当前页面 DOM，一旦用户切换了标签页、最小化了窗口，就无法再查看。

Document Picture-in-Picture API 是什么？

这是浏览器提供的原生 API，它允许你创建一个独立的、始终置顶的小窗口，并加载自定义 HTML 内容。它和视频画中画（Video PiP）类似，但不是只能放视频，而是可以放任何 HTML 页面内容！

✅ 从技术上说，它本质上是一个轻量、独立的浏览器子窗口，但有专门的样式控制权。

🆚 Modal 和 Document PiP 的对比分析

对比维度	Modal（模态框）	Document PiP（文档浮窗）
是否属于当前页面	✅ 是	❌ 否，独立页面
是否总在顶层显示	❌ 需控制 z-index	✅ 浏览器层面置顶
是否能脱离标签页	❌ 否	✅ 是，切标签页依然保留显示
样式与内容控制	✅ 可通过 React/Vue 完整控制	✅ 需通过 HTML 字符串或 JS 注入
是否能被拦截	✅ 不会	✅ 不会
用户体验	✅ 优秀	✅ 更适合小工具类浮窗
使用场景	表单、对话框、确认弹窗等	数据面板、悬浮工具栏、直播小窗等

🛠 快速上手指南

检查浏览器是否支持

由于这个现代API的兼容性并没有那么完美

在代码中需要检查浏览器是否支持

const isSupported = "documentPictureInPicture"inwindow;

创建一个浮窗

asyncfunctionopenPipWindow() {if (!("documentPictureInPicture"inwindow)) return;const pipWindow = await documentPictureInPicture.requestWindow({width: 400,height: 300});// 设置窗口内容（你可以用框架进一步封装）pipWindow.document.body.innerHTML = \`<div style="padding: 20px; background: #f0f0f0;"><h2>🎉 自定义浮窗</h2><p>这是对 window.open 的完美替代</p></div>\`;
}

📌 注意： 当前只能通过字符串方式注入内容，暂不支持直接挂载 Vue/React 组件，但可以用 iframe 或构建工具封装。

视频弹窗？请用 Video PiP！

<videoid="myVideo"controls><sourcesrc="video.mp4"type="video/mp4">
</video>
<buttononclick="togglePiP()">📺 画中画</button><script>
asyncfunctiontogglePiP() {const video = document.getElementById('myVideo');if (!document.pictureInPictureElement) {await video.requestPictureInPicture(); // 开启画中画} else {awaitdocument.exitPictureInPicture(); // 退出}
}
</script>

📊 典型场景推荐

实时仪表盘

显示用户活跃、订单数量、监控指标等 —— 适合后台管理端、BI 系统等。

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>
`;

套电落地页聊天窗

用于落地页收集线索、在线客服、AI 助手浮窗，让用户切换页面时仍能继续对话。

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>
`;

实用技巧 & 最佳实践

🚨 错误处理

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

📐 响应式尺寸建议

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

不知道你是否有这样的疑问：

❓为什么不直接用 Modal？还能用 JSX 或组件，性能也更好？

这是一个非常好的问题。确实，在页面内部使用 Modal 组件（例如 antd、Element Plus 等）更适合处理输入、表单、提示等页面交互内容，代码复用度也高。但：

Modal 只能在当前页面中显示，标签页切换或窗口最小化后就不可见；
Document PiP 则是 浏览器级别的浮窗，可以独立存在、随时可见，特别适合那些希望“常驻桌面”的场景。

所以，选择哪个更好？

👨‍💻 推荐使用 Modal： 表单交互、流程控制、确认提示等。
🖥️ 推荐使用 Document PiP： 实时数据窗口、悬浮工具、小地图、直播窗等。

总结

为不同场景选择最合适的浮窗方案

场景	推荐方案
表单输入	✅ Modal
实时监控窗口	✅ Document PiP
简单的确认提示	✅ Modal
常驻小工具栏	✅ Document PiP
视频画中画	✅ Video PiP API