深入探索 Document Picture-in-Picture API：打破画中画边界

由 dlovel · 发布日期 2025年8月29日 · 已更新 2025年8月29日 26 次浏览

现代Web浏览器不断引入新的API来丰富用户体验，Document Picture-in-Picture (PiP) API 就是其中一个令人兴奋的新功能。它允许开它允许开发者创建包含任意HTML内容的画中画窗口，而不仅仅是视频元素。

如果你曾经在浏览器中一边看视频一边浏览其他页面，那么你对 Video Picture-in-Picture (PiP) 一定不会陌生。它是一个极其方便的功能，让视频小窗可以悬浮在屏幕角落，从而实现多任务处理。

但如果我们想悬浮的不仅仅是 video 标签，而是一个完整的、交互式的网页应用界面呢？比如一个计算器、一个音乐控制器、一个笔记面板，或者一个视频会议的聊天窗口？

这就是 Document Picture-in-Picture API 的用武之地。它标志着画中画技术的一次巨大飞跃，从单一的媒体内容扩展到了任意文档内容。今天，我们就来深入探讨这个令人兴奋的新 API。

什么是Document Picture-in-Picture API？

Document Picture-in-Picture API 是一个新兴的 Web 标准，它允许 Web 开发者创建一个始终位于顶部的悬浮窗口，但这个窗口可以渲染任意 HTML 内容，而不仅仅是视频流。

你可以将它理解为一个迷你的、无边框的、始终置顶的浏览器窗口。它由当前的网页创建和管理，并且与创建它的页面共享同一个浏览上下文，这意味着它们可以轻松地进行双向通信。

传统的Picture-in-Picture功能只适用于video元素，但Document PiP API将这个理念提升到了全新水平。它允许将任何HTML文档内容（如表单、图表、控制面板等）放置在一个始终置顶的浮动窗口中，让用户可以在浏览其他内容的同时与之交互。

核心优势

多任务处理：用户可以同时与主页面和PiP窗口交互
灵活性：支持任何HTML内容，不仅仅是视频
系统级集成：PiP窗口独立于浏览器标签页运行
保持状态：PiP窗口与主页面共享JavaScript上下文

为什么需要它？解决什么痛点？

在 Document PiP 出现之前，开发者如果想实现类似“画中画”的 UI，通常需要自己在页面内用 position: fixed 模拟一个浮动元素。这种方式存在几个明显缺陷：

局限于标签页：模拟的浮动元素无法脱离浏览器标签页，一旦用户切换标签页或应用，它就会消失。
布局冲突：浮动元素容易与主页面本身的 UI 发生冲突（如模态框、菜单等）。
性能开销：即使主页面被隐藏，模拟的浮动元素依然在运行，消耗资源。

Document PiP API 直接解决了这些问题：

真正的系统级置顶：PiP 窗口独立于浏览器窗口，可以悬浮在其他应用之上。
纯净的容器：它是一个全新的、干净的窗口，没有主页面的 UI 干扰。
资源效率：当主页面的标签页被隐藏时，浏览器可以优化其性能，而 PiP 窗口独立运行。

如何使用？代码示例一览

目前，该 API 主要被 Chromium 内核的浏览器（如 Chrome 110+）所支持。使用前务必进行特性检测。

1. 开启 PiP 窗口

核心方法是 documentPictureInPicture.requestWindow()。它会返回一个 Promise，解析为一个 Window 对象，代表新打开的 PiP 窗口。

// 特性检测
if ('documentPictureInPicture' in window) {
  let pipWindow = null;

  const openPipBtn = document.getElementById('open-pip');
  openPipBtn.addEventListener('click', async () => {
    try {
      // 请求开启 PiP 窗口，可以配置宽度和高度
      pipWindow = await documentPictureInPicture.requestWindow({
        width: 320,
        height: 240,
      });

      // ！！！关键步骤：将主页面中的元素移动到 PiP 窗口
      const someElement = document.getElementById('pip-content');
      pipWindow.document.body.appendChild(someElement);

      // 或者，你也可以在 PiP 窗口中写入全新的 HTML
      // pipWindow.document.body.innerHTML = `
      //   <h1>我的控制器</h1>
      //   <button id="control">点击我！</button>
      // `;

      // 监听 PiP 窗口关闭事件
      pipWindow.addEventListener('pagehide', () => {
        // 可选：将元素移回主页面
        document.body.appendChild(someElement);
        pipWindow = null;
      });

    } catch (err) {
      console.error('Document PiP 失败:', err);
    }
  });
}

重要限制：出于安全考虑，你不能直接将字符串 HTML 或脚本注入 PiP 窗口。通常的做法是：

将主页面中已存在的 DOM 节点移动到 PiP 窗口中（如示例所示）。
使用 document.createElement 在 PiP 窗口的 document 中创建新元素。

2. 与 PiP 窗口通信

由于 PiP 窗口和主页面共享同一个 JavaScript 上下文，它们之间的通信非常简单直接。

主页面向 PiP 窗口发送信息：你可以直接调用 PiP 窗口里的函数或设置其全局变量。

// 在主页面中 pipWindow.someFunctionInPip('Hello from main page!');

PiP 窗口向主页面发送信息：同样，PiP 窗口也可以直接访问主页面的全局对象。

// 在 PiP 窗口中 window.opener.console.log('Hello from PiP window!');

对于更复杂的应用，建议使用 postMessage 或自定义事件（CustomEvent）来进行通信，这是一种更松散、更安全的耦合方式。

3. 样式处理

PiP 窗口是一个独立的文档环境，它不会继承主页面的样式表。你需要手动将所需的样式注入其中。

// 将主页面中的所有样式表复制到 PiP 窗口
document.querySelectorAll('link[rel="stylesheet"], style').forEach(styleElement => {
  pipWindow.document.head.appendChild(styleElement.cloneNode(true));
});

// 或者，为 PiP 窗口加载一个特定的样式文件
const link = pipWindow.document.createElement('link');
link.rel = 'stylesheet';
link.href = 'pip-styles.css';
pipWindow.document.head.appendChild(link);

安全与用户体验最佳实践

用户触发：和许多其他强大的 API 一样，requestWindow() 必须在用户手势（如 click 事件）中调用，不能凭空发起。
一个窗口限制：一个网页在同一时间只能打开一个 Document PiP 窗口。
提供关闭按钮：始终在你的 PiP UI 中提供一个清晰的关闭按钮，调用 window.close()。
优雅降级：始终检测 API 是否可用，并为之提供回退方案（例如，在页面内展开一个浮动面板）。
状态同步：牢记窗口可能被用户手动关闭（通过浏览器控件），要监听 pagehide 事件并及时更新主页面状态。

应用场景想象

视频会议：将参会者视频流、共享屏幕和聊天窗口分离，用户可以将聊天单独悬浮。
多媒体控制：将音乐播放器或视频控制台（进度条、音量、播放列表）悬浮，即使你离开了原始标签页。
工具辅助：悬浮一个计算器、翻译窗口、代码高亮工具或记事本。
直播与看板：悬浮一个实时评论流或数据仪表盘。

完整代码示例

下面是一个可直接使用的完整示例，展示了如何创建一个包含计时器和笔记功能的PiP窗口：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document PiP API 示例</title>
    <style>
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
            background-color: #f5f7fa;
            color: #333;
        }
        header {
            text-align: center;
            margin-bottom: 30px;
        }
        h1 {
            color: #2c3e50;
        }
        .container {
            display: flex;
            flex-direction: column;
            gap: 20px;
        }
        .card {
            background: white;
            border-radius: 10px;
            padding: 20px;
            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
        }
        .button-container {
            display: flex;
            gap: 10px;
            justify-content: center;
            margin-top: 20px;
        }
        button {
            padding: 12px 20px;
            background-color: #3498db;
            color: white;
            border: none;
            border-radius: 5px;
            cursor: pointer;
            font-weight: bold;
            transition: background-color 0.3s;
        }
        button:hover {
            background-color: #2980b9;
        }
        button:disabled {
            background-color: #95a5a6;
            cursor: not-allowed;
        }
        textarea {
            width: 100%;
            height: 100px;
            padding: 10px;
            border: 1px solid #ddd;
            border-radius: 5px;
            resize: vertical;
        }
        .timer {
            font-size: 24px;
            text-align: center;
            margin: 15px 0;
            font-weight: bold;
            color: #2c3e50;
        }
        .note {
            margin-top: 15px;
        }
        .feature-list {
            line-height: 1.6;
        }
        .warning {
            background-color: #ffeaa7;
            padding: 15px;
            border-radius: 5px;
            margin-top: 20px;
        }
        .code {
            font-family: 'Courier New', Courier, monospace;
            background-color: #f8f9fa;
            padding: 15px;
            border-radius: 5px;
            overflow-x: auto;
            font-size: 14px;
        }
    </style>
</head>
<body>
    <header>
        <h1>Document Picture-in-Picture API 演示</h1>
        <p>体验下一代画中画技术，将任意HTML内容悬浮在屏幕上</p>
    </header>

    <div class="container">
        <div class="card">
            <h2>功能说明</h2>
            <ul class="feature-list">
                <li>创建一个包含计时器和笔记功能的画中画窗口</li>
                <li>画中画窗口将始终保持在最前面</li>
                <li>即使切换浏览器标签或应用程序，画中画窗口仍然可见</li>
                <li>主页面和画中画窗口之间实时同步状态</li>
            </ul>
        </div>

        <div class="card">
            <h2>画中画内容预览</h2>
            <div class="timer">00:00:00</div>
            <div class="note">
                <h3>我的笔记</h3>
                <textarea id="note-content" placeholder="在此输入笔记内容..."></textarea>
            </div>
        </div>

        <div class="button-container">
            <button id="open-pip">打开画中画窗口</button>
            <button id="close-pip" disabled>关闭画中画窗口</button>
        </div>

        <div class="card warning">
            <h3>兼容性说明</h3>
            <p>Document Picture-in-Picture API 目前仅在 Chromium 105+ 浏览器中支持。请使用最新版本的 Chrome、Edge 或 Opera 浏览器体验此功能。</p>
        </div>

        <div class="card">
            <h2>实现代码</h2>
            <pre class="code">
// 检查浏览器是否支持 Document Picture-in-Picture API
if ('documentPictureInPicture' in window) {
  let pipWindow = null;
  let timerInterval = null;
  let seconds = 0;
  
  const openPipBtn = document.getElementById('open-pip');
  const closePipBtn = document.getElementById('close-pip');
  const noteContent = document.getElementById('note-content');
  const timerElement = document.querySelector('.timer');
  
  // 更新计时器显示
  function updateTimer() {
    seconds++;
    const hours = Math.floor(seconds / 3600);
    const minutes = Math.floor((seconds % 3600) / 60);
    const secs = seconds % 60;
    timerElement.textContent = 
      `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
  }
  
  // 启动计时器
  function startTimer() {
    if (!timerInterval) {
      timerInterval = setInterval(updateTimer, 1000);
    }
  }
  
  // 停止计时器
  function stopTimer() {
    if (timerInterval) {
      clearInterval(timerInterval);
      timerInterval = null;
    }
  }
  
  // 打开画中画窗口
  openPipBtn.addEventListener('click', async () => {
    try {
      // 请求开启画中画窗口
      pipWindow = await documentPictureInPicture.requestWindow({
        width: 300,
        height: 300,
      });
      
      // 复制内容到画中画窗口
      const pipContent = document.querySelector('.card:not(:first-child)').cloneNode(true);
      pipWindow.document.body.appendChild(pipContent);
      
      // 添加自定义样式
      const style = pipWindow.document.createElement('style');
      style.textContent = `
        body { 
          font-family: 'Segoe UI', sans-serif; 
          margin: 0; 
          padding: 15px; 
          background: #2c3e50;
          color: white;
        }
        .timer { 
          font-size: 20px; 
          text-align: center; 
          margin: 10px 0; 
          font-weight: bold;
          color: #3498db;
        }
        textarea {
          width: 100%;
          height: 80px;
          padding: 8px;
          border: 1px solid #34495e;
          border-radius: 4px;
          background: #34495e;
          color: white;
        }
        h3 {
          margin-top: 0;
          color: #ecf0f1;
        }
      `;
      pipWindow.document.head.appendChild(style);
      
      // 同步笔记内容
      const pipTextarea = pipWindow.document.querySelector('textarea');
      pipTextarea.value = noteContent.value;
      
      // 双向同步笔记内容
      noteContent.addEventListener('input', () => {
        if (pipWindow) {
          pipTextarea.value = noteContent.value;
        }
      });
      
      pipTextarea.addEventListener('input', () => {
        noteContent.value = pipTextarea.value;
      });
      
      // 处理画中画窗口关闭
      pipWindow.addEventListener('pagehide', () => {
        stopTimer();
        pipWindow = null;
        openPipBtn.disabled = false;
        closePipBtn.disabled = true;
      });
      
      // 更新按钮状态
      openPipBtn.disabled = true;
      closePipBtn.disabled = false;
      
      // 启动计时器
      startTimer();
      
    } catch (error) {
      console.error('开启画中画失败:', error);
    }
  });
  
  // 关闭画中画窗口
  closePipBtn.addEventListener('click', () => {
    if (pipWindow && !pipWindow.closed) {
      pipWindow.close();
    }
  });
  
  // 初始化计时器
  updateTimer();
  
} else {
  // 浏览器不支持 Document PiP API
  document.getElementById('open-pip').disabled = true;
  alert('您的浏览器不支持 Document Picture-in-Picture API。请使用 Chromium 105+ 浏览器。');
}
            </pre>
        </div>
    </div>

    <script>
        // 检查浏览器是否支持 Document Picture-in-Picture API
        if ('documentPictureInPicture' in window) {
            let pipWindow = null;
            let timerInterval = null;
            let seconds = 0;
            
            const openPipBtn = document.getElementById('open-pip');
            const closePipBtn = document.getElementById('close-pip');
            const noteContent = document.getElementById('note-content');
            const timerElement = document.querySelector('.timer');
            
            // 更新计时器显示
            function updateTimer() {
                seconds++;
                const hours = Math.floor(seconds / 3600);
                const minutes = Math.floor((seconds % 3600) / 60);
                const secs = seconds % 60;
                timerElement.textContent = 
                    `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
                
                // 如果PiP窗口打开，同时更新其中的计时器
                if (pipWindow && !pipWindow.closed) {
                    const pipTimer = pipWindow.document.querySelector('.timer');
                    if (pipTimer) {
                        pipTimer.textContent = timerElement.textContent;
                    }
                }
            }
            
            // 启动计时器
            function startTimer() {
                if (!timerInterval) {
                    timerInterval = setInterval(updateTimer, 1000);
                }
            }
            
            // 停止计时器
            function stopTimer() {
                if (timerInterval) {
                    clearInterval(timerInterval);
                    timerInterval = null;
                }
            }
            
            // 打开画中画窗口
            openPipBtn.addEventListener('click', async () => {
                try {
                    // 请求开启画中画窗口
                    pipWindow = await documentPictureInPicture.requestWindow({
                        width: 320,
                        height: 320,
                    });
                    
                    // 复制内容到画中画窗口
                    const pipContent = document.querySelector('.card:nth-child(2)').cloneNode(true);
                    pipWindow.document.body.appendChild(pipContent);
                    
                    // 添加自定义样式
                    const style = pipWindow.document.createElement('style');
                    style.textContent = `
                        body { 
                            font-family: 'Segoe UI', sans-serif; 
                            margin: 0; 
                            padding: 15px; 
                            background: #2c3e50;
                            color: white;
                        }
                        .timer { 
                            font-size: 20px; 
                            text-align: center; 
                            margin: 10px 0; 
                            font-weight: bold;
                            color: #3498db;
                        }
                        textarea {
                            width: 100%;
                            height: 80px;
                            padding: 8px;
                            border: 1px solid #34495e;
                            border-radius: 4px;
                            background: #34495e;
                            color: white;
                        }
                        h3 {
                            margin-top: 0;
                            color: #ecf0f1;
                        }
                    `;
                    pipWindow.document.head.appendChild(style);
                    
                    // 同步笔记内容
                    const pipTextarea = pipWindow.document.querySelector('textarea');
                    pipTextarea.value = noteContent.value;
                    
                    // 双向同步笔记内容
                    noteContent.addEventListener('input', () => {
                        if (pipWindow && !pipWindow.closed) {
                            pipTextarea.value = noteContent.value;
                        }
                    });
                    
                    pipTextarea.addEventListener('input', () => {
                        noteContent.value = pipTextarea.value;
                    });
                    
                    // 处理画中画窗口关闭
                    pipWindow.addEventListener('pagehide', () => {
                        stopTimer();
                        pipWindow = null;
                        openPipBtn.disabled = false;
                        closePipBtn.disabled = true;
                    });
                    
                    // 更新按钮状态
                    openPipBtn.disabled = true;
                    closePipBtn.disabled = false;
                    
                    // 启动计时器
                    startTimer();
                    
                } catch (error) {
                    console.error('开启画中画失败:', error);
                }
            });
            
            // 关闭画中画窗口
            closePipBtn.addEventListener('click', () => {
                if (pipWindow && !pipWindow.closed) {
                    pipWindow.close();
                }
            });
            
            // 初始化计时器
            updateTimer();
            
        } else {
            // 浏览器不支持 Document PiP API
            document.getElementById('open-pip').disabled = true;
            alert('您的浏览器不支持 Document Picture-in-Picture API。请使用 Chromium 105+ 浏览器。');
        }
    </script>
</body>
</html>

关键实现要点

特性检测：在使用API前检查浏览器支持情况
请求PiP窗口：使用documentPictureInPicture.requestWindow()创建画中画窗口
内容迁移：将DOM元素从主文档移动到PiP窗口
样式处理：为PiP窗口创建和添加专用样式
状态同步：实现主窗口和PiP窗口之间的双向数据同步
事件处理：监听PiP窗口关闭事件并进行清理工作

实际应用场景

视频会议的聊天和控制面板
多媒体播放器的独立控制界面
实时仪表盘和监控面板
笔记和待办事项列表
翻译工具和词典面板

注意事项

目前仅Chromium 105+版本支持此API
用户必须通过手势（如点击）触发PiP窗口的打开
PiP窗口中的内容应简洁且具有独立功能性

结语

Document Picture-in-Picture API 为 Web 应用的多任务和用户体验设计开辟了全新的可能性。它让 Web 应用能够以以前只有原生应用才能实现的方式深度集成到用户的操作系统中。

虽然目前浏览器支持还比较有限，但它无疑是一个值得关注和尝试的强大特性。现在就开始构思，如何用它来让你的 Web 应用变得更加强大和灵活吧！

Document Picture-in-Picture API为Web开发者提供了创建更丰富、更沉浸式用户体验的强大工具。随着浏览器支持的不断扩大，我们可以期待看到更多创新应用的出现。

一	二	三	四	五	六	日
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

深入探索 Document Picture-in-Picture API：打破画中画边界

什么是Document Picture-in-Picture API？

核心优势

为什么需要它？解决什么痛点？

如何使用？代码示例一览

1. 开启 PiP 窗口

2. 与 PiP 窗口通信

3. 样式处理

安全与用户体验最佳实践

应用场景想象

完整代码示例

关键实现要点

实际应用场景

注意事项

结语

进一步阅读：

您可能还喜欢...

发表评论取消回复

近期文章

统计信息

深入探索 Document Picture-in-Picture API：打破画中画边界

什么是Document Picture-in-Picture API？

核心优势

为什么需要它？解决什么痛点？

如何使用？代码示例一览

1. 开启 PiP 窗口

2. 与 PiP 窗口通信

3. 样式处理

安全与用户体验最佳实践

应用场景想象

完整代码示例

关键实现要点

实际应用场景

注意事项

结语

进一步阅读：

您可能还喜欢...

vue数字折线图

请叙述Vue与React、Angular的比较？

Cookie 和Session 的区别？

发表评论 取消回复

近期文章

统计信息

发表评论取消回复