基于 Document Picture-in-Picture API 实现视频小窗与主页面同步控制

介绍利用 Document Picture-in-Picture API 实现视频画中画功能的方法。通过创建独立小窗口并同步主页面状态，支持在浏览其他内容时持续播放。提供完整的前端代码示例，涵盖窗口创建、DOM 迁移及播放状态（时间、音量、暂停）的双向同步逻辑，适用于自定义播放器开发。

ApiHolic发布于 2026/4/9更新于 2026/5/2318 浏览

前端实现视频画中画功能 - 完整代码与同步控制

在视频播放场景中，用户往往需要在观看内容的同时处理其他任务。传统的画中画（Picture-in-Picture）仅支持视频轨道，而新的 Document Picture-in-Picture API 允许将整个文档内容移入独立的小窗口，并保留自定义控件和交互能力。

本文通过一个完整的案例，演示如何创建一个小窗模式，实现主页面与小窗之间的视频状态同步（播放、暂停、音量、进度），提升多任务场景下的用户体验。

为什么要使用 Document PiP API

随着 Chrome 116+ 对 Document Picture-in-Picture API 的支持，我们不再局限于仅将 <video> 元素移出。新 API 的优势在于：

完整 HTML 支持：小窗内可包含按钮、进度条等任意交互元素。
无缝集成：与原始页面共享 JavaScript 上下文，便于通信。
尺寸灵活：可自定义小窗的宽高。
双向通信：主页面与小窗实时同步状态。

相比传统方案，它特别适用于视频会议、在线课程及需要高度定制控制的播放器场景。

完整代码案例

以下示例包含 HTML 结构、CSS 样式及核心 JavaScript 逻辑。请确保本地有一个测试视频文件（如 1.mp4），或修改 src 属性指向有效资源。

CSS 样式

*{
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}
body {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    line-height: 1.6;
    color: #333;
    background: linear-gradient(135deg, #1a2a6c, #b21f1f, #1a2a6c);
    padding: 20px;
    min-height: 100vh;
}
.container {
    max-width: 1200px;
    margin: 0 auto;
    background-color: (, , , );
    : ;
    :    (, , , );
    : hidden;
}
 {
    : (to right, , );
    : white;
    :  ;
    : center;
}
 {
    : ;
    : ;
    :    (, , , );
}
 {
    : ;
    : ;
    : ;
    :  auto;
}
 {
    : flex;
    : ;
    : ;
}
 {
    : ;
    : ;
    : ;
    : hidden;
    :    (, , , );
}
 {
    : relative;
    : ; 
    : ;
}
 {
    : absolute;
    : ;
    : ;
    : ;
    : ;
    : block;
}
 {
    : flex;
    : ;
    : ;
    : ;
}
 {
    : ;
    : white;
    : none;
    :  ;
    : ;
    : pointer;
    : ;
    : all  ease;
    : flex;
    : center;
    : ;
}
 {
    : ;
    : (-);
    :    (, , , );
}
 {
    : ;
    : not-allowed;
    : none;
    : none;
}
 {
    : ;
    : white;
    : ;
    : ;
    :    (, , , );
}
 {
    : ;
    : ;
    : ;
    :  solid ;
}
 {
    :  ;
}
 {
    : flex;
    : flex-start;
    : ;
}
 {
    : ;
    : white;
    : ;
    : ;
    : ;
    : flex;
    : center;
    : center;
    : ;
    : ;
}
 {
    : fixed;
    : ;
    : ;
    : ;
    : ;
    : black;
    : ;
    : hidden;
    :    (, , , );
    : ;
    : none;
}
  {
    : ;
    : ;
    : cover;
}
 {
    : absolute;
    : ;
    : ;
    : ;
    : flex;
    : center;
    : ;
    : ;
    : opacity ;
}
  {
    : ;
}
 {
    : ;
    : ;
    : ;
    : ;
    : monospace;
}
 {
    : ;
    : ;
    : ;
    : ;
    :  solid ;
}
 {
    : flex;
    : ;
    : ;
    : wrap;
}
 {
    : flex;
    : center;
    : ;
}
 { : ; }
 { : ; }
(max-width: ) {
     {
        : column;
    }
}

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>视频小窗模式演示</title> <link href="css/pip.css" rel="stylesheet" type="text/css"/> </head> <body> <div class="container"> <header> <h1>视频小窗模式演示</h1> <p class="subtitle">使用 Document Picture-in-Picture API 实现在其他内容上浮动播放视频</p> </header> <div class="content"> <div class="video-section"> <div class="video-container"> <video id="mainVideo" src="1.mp4" controls playsinline></video> </div> <div class="video-controls"> <button id="pipButton" title="开启小窗模式"> <svg width="20" height="20" fill="currentColor" viewBox="0 0 16 16"> <path d="M0 3.5A1.5 1.5 0 0 1 1.5 2h13A1.5 1.5 0 0 1 16 3.5v9a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 0 12.5v-9zM1.5 3a.5.5 0 0 0-.5.5v9a.5.5 0 0 0 .5.5h13a.5.5 0 0 0 .5-.5v-9a.5.5 0 0 0-.5-.5h-13z"/> <path d="M8 8.5a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 .5.5v3a.5.5 0 0 1-.5.5h-5a.5.5 0 0 1-.5-.5v-3z"/> </svg> 开启小窗模式 </button> <button id="fullscreenButton"> <svg width="20" height="20" fill="currentColor" viewBox="0 0 16 16"> <path d="M1.5 1a.5.5 0 0 0-.5.5v4a.5.5 0 0 1-1 0v-4A1.5 1.5 0 0 1 1.5 0h4a.5.5 0 0 1 0 1h-4zM10 .5a.5.5 0 0 1 .5-.5h4A1.5 1.5 0 0 1 16 1.5v4a.5.5 0 0 1-1 0v-4a.5.5 0 0 0-.5-.5h-4a.5.5 0 0 1-.5-.5zM.5 10a.5.5 0 0 1 .5.5v4a.5.5 0 0 0 .5.5h4a.5.5 0 0 1 0 1h-4A1.5 1.5 0 0 1 0 14.5v-4a.5.5 0 0 1 .5-.5zm15 0a.5.5 0 0 1 .5.5v4a1.5 1.5 0 0 1-1.5 1.5h-4a.5.5 0 0 1 0-1h4a.5.5 0 0 0 .5-.5v-4a.5.5 0 0 1 .5-.5z"/> </svg> 全屏 </button> </div> </div> <div class="info-section"> <h2>Document Picture-in-Picture API</h2> <div class="feature-list"> <div class="feature"> <div class="feature-icon">1</div> <div> <h3>任意 HTML 内容</h3> <p>可以在小窗中显示视频控件、字幕等任意 HTML 元素</p> </div> </div> <div class="feature"> <div class="feature-icon">2</div> <div> <h3>保持播放状态</h3> <p>进入小窗模式时视频持续播放，不中断观看体验</p> </div> </div> <div class="feature"> <div class="feature-icon">3</div> <div> <h3>双向同步</h3> <p>主页面和小窗中的视频状态实时同步</p> </div> </div> <div class="feature"> <div class="feature-icon">4</div> <div> <h3>自由调整</h3> <p>用户可以调整小窗位置和大小，适应不同需求</p> </div> </div> </div> <div class="status"> <p>当前状态：<span id="statusText">等待操作</span></p> <p>小窗状态：<span id="pipStatus">未激活</span></p> </div> <div class="browser-support"> <h3>浏览器支持情况</h3> <div class="support-list"> <div class="browser"> <svg width="24" height="24" fill="#4285F4" viewBox="0 0 24 24"><path d="M12 15.6l-3.9 2.3 1-4.3-3.2-2.9 4.3-.4L12 6.5l1.8 4.1 4.3.4-3.2 2.9 1 4.3z"/></svg> <span class="supported">Chrome 108+</span> </div> <div class="browser"> <svg width="24" height="24" fill="#FF9500" viewBox="0 0 24 24"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M17.2 3H6.8l-5.2 9 5.2 9h10.4l5.2-9-5.2-9zm-1.15 16h-8.1l-4.04-7 4.04-7h8.09l4.04 7-4.03 7z"/></svg> <span class="unsupported">Firefox</span> </div> <div class="browser"> <svg width="24" height="24" fill="#0078D7" viewBox="0 0 24 24"><path d="M0 0v24h24V0H0zm22 22H2V2h20v20z"/><path d="M12 12l-4 4 1.4 1.4 2.6-2.6 2.6 2.6 1.4-1.4z"/></svg> <span class="unsupported">Edge</span> </div> <div class="browser"> <svg width="24" height="24" fill="#000000" viewBox="0 0 24 24"><path d="M18.7 4.3c-1.2-1.2-2.9-1.9-4.7-1.9H5C3.3 2.4 2 3.7 2 5.4v13.1c0 1.8 1.5 3.2 3.3 3.2H19c1.8 0 3.2-1.4 3.2-3.2V9c0-1.8-.7-3.5-1.9-4.7h-.6zM19 20.5H5.3c-.9 0-1.7-.7-1.7-1.7V5.4c0-.9.8-1.7 1.7-1.7h9c.9 0 1.7.7 1.7 1.7v3.9h3.9c.9 0 1.7.8 1.7 1.7v7.9c0 .9-.7 1.7-1.6 1.7z"/></svg> <span class="unsupported">Safari</span> </div> </div> </div> </div> </div> </div>  <div id="pipContainer" class="pip-window"> <video id="pipVideo" src="1.mp4" controls></video> <div class="pip-controls"> <button id="closePipButton" title="关闭小窗">关闭</button> </div> </div> <script src="app.js"></script> </body> </html>

// 页面元素引用 const mainVideo = document.getElementById('mainVideo'); const pipVideo = document.getElementById('pipVideo'); const pipButton = document.getElementById('pipButton'); const fullscreenButton = document.getElementById('fullscreenButton'); const closePipButton = document.getElementById('closePipButton'); const pipContainer = document.getElementById('pipContainer'); const statusText = document.getElementById('statusText'); const pipStatus = document.getElementById('pipStatus'); // 检查浏览器支持情况 const isPipSupported = 'documentPictureInPicture' in window; // 初始化页面 function init() { updateStatus(isPipSupported ? "Document Picture-in-Picture API 可用" : "您的浏览器不支持 Document Picture-in-Picture API"); // 设置按钮状态 pipButton.disabled = !isPipSupported; // 添加事件监听器 pipButton.addEventListener('click', togglePictureInPicture); fullscreenButton.addEventListener('click', toggleFullscreen); closePipButton.addEventListener('click', closePictureInPicture); // 初始化视频源 pipVideo.src = mainVideo.src; mainVideo.muted = true; pipVideo.muted = true; } // 更新状态显示 function updateStatus(message) { statusText.textContent = message; } // 更新 PIP 状态显示 function updatePipStatus(message) { pipStatus.textContent = message; } // 切换小窗模式 async function togglePictureInPicture() { if (!isPipSupported) return; // 如果小窗已打开，则关闭 if (window.documentPictureInPicture.window) { await closePictureInPicture(); return; } try { // 打开小窗 const pipWindow = await window.documentPictureInPicture.requestWindow({ width: 400, height: 300, }); // 设置小窗标题 pipWindow.document.title = "视频小窗播放"; // 添加样式 const style = document.createElement('style'); style.textContent = ` body { margin: 0; background: black; height: 100vh; overflow: hidden; } video { width: 100%; height: 100%; object-fit: contain; } `; pipWindow.document.head.appendChild(style); // 添加视频元素到小窗 pipWindow.document.body.appendChild(pipVideo); // 同步播放状态 pipVideo.currentTime = mainVideo.currentTime; if (!mainVideo.paused) { await pipVideo.play(); } else { pipVideo.pause(); } // 处理小窗关闭事件 pipWindow.addEventListener('pagehide', () => { // 将视频元素移回主文档 pipContainer.appendChild(pipVideo); pipContainer.style.display = 'none'; updatePipStatus("已关闭"); }); // 显示小窗容器（用于样式） pipContainer.style.display = 'block'; updateStatus("小窗模式已激活"); updatePipStatus("运行中"); // 同步播放状态 mainVideo.addEventListener('timeupdate', syncVideoTime); pipVideo.addEventListener('timeupdate', syncVideoTime); // 同步播放/暂停状态 mainVideo.addEventListener('play', () => pipVideo.play()); mainVideo.addEventListener('pause', () => pipVideo.pause()); pipVideo.addEventListener('play', () => mainVideo.play()); pipVideo.addEventListener('pause', () => mainVideo.pause()); // 同步音量 mainVideo.addEventListener('volumechange', syncVolume); pipVideo.addEventListener('volumechange', syncVolume); } catch (error) { updateStatus(`错误：${error.message}`); console.error(error); } } // 同步视频播放时间 function syncVideoTime() { // 避免循环同步 if (Math.abs(mainVideo.currentTime - pipVideo.currentTime) > 0.5) { if (this === mainVideo) { pipVideo.currentTime = mainVideo.currentTime; } else { mainVideo.currentTime = pipVideo.currentTime; } } } // 同步音量 function syncVolume() { if (this === mainVideo) { pipVideo.volume = mainVideo.volume; pipVideo.muted = mainVideo.muted; } else { mainVideo.volume = pipVideo.volume; mainVideo.muted = pipVideo.muted; } } // 关闭小窗模式 async function closePictureInPicture() { if (window.documentPictureInPicture.window) { window.documentPictureInPicture.window.close(); } // 移除事件监听器 mainVideo.removeEventListener('timeupdate', syncVideoTime); pipVideo.removeEventListener('timeupdate', syncVideoTime); mainVideo.removeEventListener('volumechange', syncVolume); pipVideo.removeEventListener('volumechange', syncVolume); // 将视频移回原始位置 pipContainer.appendChild(pipVideo); pipContainer.style.display = 'none'; updateStatus("小窗模式已关闭"); updatePipStatus("未激活"); } // 切换全屏模式 function toggleFullscreen() { if (!document.fullscreenElement) { if (mainVideo.requestFullscreen) { mainVideo.requestFullscreen(); } else if (mainVideo.webkitRequestFullscreen) { mainVideo.webkitRequestFullscreen(); } else if (mainVideo.msRequestFullscreen) { mainVideo.msRequestFullscreen(); } } else { if (document.exitFullscreen) { document.exitFullscreen(); } else if (document.webkitExitFullscreen) { document.webkitExitFullscreen(); } else if (document.msExitFullscreen) { document.msExitFullscreen(); } } } // 初始化应用 document.addEventListener('DOMContentLoaded', init);

基于 Document Picture-in-Picture API 实现视频小窗与主页面同步控制

前端实现视频画中画功能 - 完整代码与同步控制

为什么要使用 Document PiP API

完整代码案例

CSS 样式

HTML 结构

JavaScript 逻辑

案例核心原理与流程

代码流程

状态同步机制

结语

更多推荐文章

相关免费在线工具

基于 Document Picture-in-Picture API 实现视频小窗与主页面同步控制

前端实现视频画中画功能 - 完整代码与同步控制

为什么要使用 Document PiP API

完整代码案例

CSS 样式

HTML 结构

JavaScript 逻辑

案例核心原理与流程

代码流程

状态同步机制

结语

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具