- 深入了解 Document Picture-in-Picture API，并对比 Modal 的最佳使用场景
在前端开发中，我们经常会遇到这样的需求：弹出一个浮动窗口来显示一些实时信息、工具栏或视频内容。过去我们会用
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 注入 |
| 是否能被拦截 | ✅ 不会 | ✅ 不会 |
| 用户体验 | ✅ 优秀 | ✅ 更适合小工具类浮窗 |
| 使用场景 | 表单、对话框、确认弹窗等 | 数据面板、悬浮工具栏、直播小窗等 |
这里提供一个html文件示例，可以直接复制 浏览器打开，有直观的体验
<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Document Picture-in-Picture API 示例</title><style>body {font-family: Arial, sans-serif;max-width: 800px;margin: 0 auto;padding: 20px;background-color: #f5f5f5;}.container {background-color: white;border-radius: 8px;padding: 20px;box-shadow: 0 2px 10px rgba(0,0,0,0.1);}h1 {color: #333;text-align: center;}.video-container {position: relative;width: 100%;height: 300px;background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);border-radius: 8px;display: flex;align-items: center;justify-content: center;color: white;margin: 20px 0;}.controls {display: flex;gap: 10px;justify-content: center;flex-wrap: wrap;margin: 20px 0;}button {padding: 10px 20px;background-color: #4CAF50;color: white;border: none;border-radius: 4px;cursor: pointer;font-size: 16px;}button:hover {background-color: #45a049;}button:disabled {background-color: #cccccc;cursor: not-allowed;}.feature-list {background-color: #f9f9f9;border-left: 4px solid #4CAF50;padding: 15px;margin: 20px 0;}.feature-list h3 {margin-top: 0;}.feature-list ul {padding-left: 20px;}.feature-list li {margin-bottom: 10px;}.pip-window-content {width: 100%;height: 100%;background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);display: flex;flex-direction: column;align-items: center;justify-content: center;color: white;font-family: Arial, sans-serif;}.pip-title {font-size: 18px;font-weight: bold;margin-bottom: 10px;}.pip-clock {font-size: 24px;font-weight: bold;}.pip-controls {margin-top: 20px;display: flex;gap: 10px;}.pip-button {padding: 8px 16px;background-color: rgba(255, 255, 255, 0.2);border: 1px solid white;color: white;border-radius: 4px;cursor: pointer;}.status {text-align: center;padding: 10px;border-radius: 4px;margin: 10px 0;}.supported {background-color: #dff0d8;color: #3c763d;}.not-supported {background-color: #f2dede;color: #a94442;}</style>
</head>
<body><div class="container"><h1>Document Picture-in-Picture API 示例</h1><div id="support-status" class="status">检查浏览器支持情况...</div><div class="video-container"><div><div style="font-size: 24px; margin-bottom: 10px;">主窗口内容</div><div>这是一个模拟的视频播放区域</div></div></div><div class="controls"><button id="openPipButton" disabled>打开画中画窗口</button><button id="closePipButton" disabled>关闭画中画窗口</button></div><div class="feature-list"><h3>Document Picture-in-Picture API 特性：</h3><ul><li>可以在独立窗口中显示任意 HTML 内容</li><li>窗口始终置顶，不会被其他应用遮挡</li><li>可以自定义窗口内容和交互</li><li>支持动态更新窗口内容</li><li>适用于视频播放器、会议工具、聊天应用等场景</li></ul></div><div class="feature-list"><h3>使用步骤：</h3><ul><li>检查浏览器是否支持 Document Picture-in-Picture API</li><li>创建要在画中画窗口中显示的内容</li><li>调用 API 打开画中画窗口</li><li>在窗口中渲染自定义内容</li></ul></div></div><script>// 检查浏览器支持const supportStatus = document.getElementById('support-status');const openPipButton = document.getElementById('openPipButton');const closePipButton = document.getElementById('closePipButton');let pipWindow = null;if ('documentPictureInPicture' in window) {supportStatus.textContent = '✓ 您的浏览器支持 Document Picture-in-Picture API';supportStatus.className = 'status supported';openPipButton.disabled = false;} else {supportStatus.textContent = '✗ 您的浏览器不支持 Document Picture-in-Picture API（需要 Chrome 116+）';supportStatus.className = 'status not-supported';}// 打开画中画窗口openPipButton.addEventListener('click', async () => {try {// 请求打开画中画窗口pipWindow = await window.documentPictureInPicture.requestWindow({width: 400,height: 300});// 在画中画窗口中创建内容const pipDocument = pipWindow.document;// 添加基础样式const style = pipDocument.createElement('style');style.textContent = `body {margin: 0;padding: 0;font-family: Arial, sans-serif;}`;pipDocument.head.appendChild(style);// 创建内容const content = pipDocument.createElement('div');content.className = 'pip-window-content';content.innerHTML = `<div class="pip-title">Document Picture-in-Picture 示例</div><div class="pip-clock" id="pip-clock">00:00:00</div><div class="pip-controls"><button class="pip-button" id="update-content">更新时间</button><button class="pip-button" id="close-window">关闭窗口</button></div>`;pipDocument.body.appendChild(content);// 添加交互功能const clockElement = pipDocument.getElementById('pip-clock');const updateButton = pipDocument.getElementById('update-content');const closeButton = pipDocument.getElementById('close-window');// 更新时钟函数function updateClock() {const now = new Date();clockElement.textContent = now.toTimeString().slice(0, 8);}// 初始更新updateClock();// 定时更新时钟const clockInterval = setInterval(updateClock, 1000);// 更新按钮事件updateButton.addEventListener('click', updateClock);// 关闭按钮事件closeButton.addEventListener('click', () => {pipWindow.close();});// 窗口关闭事件pipWindow.addEventListener('pagehide', () => {clearInterval(clockInterval);pipWindow = null;closePipButton.disabled = true;openPipButton.disabled = false;});// 更新按钮状态openPipButton.disabled = true;closePipButton.disabled = false;// 关闭按钮事件closePipButton.onclick = () => {if (pipWindow) {pipWindow.close();}};} catch (error) {console.error('打开画中画窗口失败:', error);alert('打开画中画窗口失败: ' + error.message);}});</script>
</body>
</html>
如果你想实现：
- 不被弹窗拦截器阻止的浮窗功能；
- 永远置顶、跨标签页的小窗口；
- 快速集成、无需第三方组件的解决方案；
👉 那就大胆尝试 Document Picture-in-Picture API 吧！它或许会成为你项目中意想不到的提升利器！
