【JavaScript】深入解析 Picture-in-Picture API：构建画中画功能的详细指南

托尼比卡丘

已于 2025-02-18 13:38:40 修改

阅读量1k

点赞数 11

分类专栏： JavaScript相关文章标签： javascript 开发语言 ecmascript

于 2025-02-18 09:23:43 首次发布

本文链接：https://blog.csdn.net/weixin_44070058/article/details/145696882

版权

JavaScript相关专栏收录该内容

17 篇文章

订阅专栏

引言

在现代网页开发中，提升用户体验是每个开发者的核心目标之一。Picture-in-Picture（画中画，简称 PiP） 是一种允许用户将视频或其他内容以小窗口形式悬浮在其他应用之上的技术。这一功能在视频播放、实时通讯等场景中尤为实用。本文将基于 PIP 官方示例代码进行详细分析，并探讨如何利用 PiP API 提升网页应用的交互性。

在这里插入图片描述

一、PiP API 简介

Picture-in-Picture API 是 Web API 的一部分，旨在为网页内容提供画中画功能。通过该 API，开发者可以轻松地将指定的 DOM 元素（如视频播放器、图像或自定义内容）转换为独立的浮动窗口，用户可以自由移动和调整其大小，而不影响主网页的浏览。

主要特点：

跨平台支持：现代主流浏览器（如 Chrome、Firefox、Edge）均已支持 PiP 功能。
灵活性高：不仅限于视频内容，任何可渲染的 DOM 元素均可作为 PiP 窗口的内容。
用户控制：用户可以自由移动、调整大小或关闭 PiP 窗口。

在这里插入图片描述

二、示例代码解析

以下是对提供的示例代码的详细解析：

1. HTML 结构

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document Picture-in-Picture API 示例</title>
    <style>
        #pipContent {
            width: 600px;
            height: 300px;
            background: pink;
            font-size: 20px;
        }
    </style>
</head>
<body>
    <div id="container">
        <div id="pipContent">这是一个将要放入画中画的 div 元素！</div>
        <button id="clickBtn">切换画中画</button>
    </div>
    ...
</body>
</html>

#pipContent：这是将要放入 PiP 窗口的 DOM 元素，示例中为一个带有粉色背景的 div。
#clickBtn：一个按钮，用于触发 PiP 功能的切换。

2. JavaScript 功能实现

// 检查是否支持 PiP 功能
if ('documentPictureInPicture' in window) {
    console.log("🚀 浏览器支持 PiP 功能！");
} else {
    console.warn("⚠️ 当前浏览器不支持 PiP 功能，更新浏览器或者换台电脑吧！");
}

// 请求 PiP 窗口
document.getElementById("clickBtn").addEventListener("click", async function () {
    const pipContent = document.getElementById("pipContent");

    // 请求创建一个 PiP 窗口
    const pipWindow = await window.documentPictureInPicture.requestWindow({
        width: 200,  // 设置窗口的宽度
        height: 300  // 设置窗口的高度
    });

    // 将原始元素克隆并添加到 PiP 窗口中
    pipWindow.document.body.appendChild(pipContent.cloneNode(true));

    // 设置 PiP 样式同步
    [...document.styleSheets].forEach((styleSheet) => {
        try {
            const cssRules = [...styleSheet.cssRules].map((rule) => rule.cssText).join('');
            const style = document.createElement('style');
            style.textContent = cssRules;
            pipWindow.document.head.appendChild(style);
        } catch (e) {
            const link = document.createElement('link');
            link.rel = 'stylesheet';
            link.type = styleSheet.type;
            link.media = styleSheet.media;
            link.href = styleSheet.href ?? '';
            pipWindow.document.head.appendChild(link);
        }
    });

    // 监听进入和退出 PiP 模式的事件
    pipWindow.addEventListener("pagehide", (event) => {
        console.log("已退出 PIP 窗口");
    });

    pipWindow.addEventListener('focus', () => {
        console.log("PiP 窗口进入了焦点状态");
    });

    pipWindow.addEventListener('blur', () => {
        console.log("PiP 窗口失去了焦点");
    });
});

2.1 浏览器兼容性检查

if ('documentPictureInPicture' in window) {
    console.log("🚀 浏览器支持 PiP 功能！");
} else {
    console.warn("⚠️ 当前浏览器不支持 PiP 功能，更新浏览器或者换台电脑吧！");
}

功能检测：通过检查 window 对象中是否存在 documentPictureInPicture 属性来确定浏览器是否支持 PiP 功能。
用户提示：如果不支持，建议用户更新浏览器或更换设备。

2.2 触发 PiP 窗口

document.getElementById("clickBtn").addEventListener("click", async function () {
    const pipContent = document.getElementById("pipContent");
    const pipWindow = await window.documentPictureInPicture.requestWindow({
        width: 200,
        height: 300
    });
    ...
});

事件监听：为按钮 #clickBtn 添加点击事件监听器。
异步请求：使用 await 等待 PiP 窗口的创建请求完成。
窗口尺寸：通过 width 和 height 参数设置 PiP 窗口的尺寸。

2.3 元素克隆与样式同步

pipWindow.document.body.appendChild(pipContent.cloneNode(true));

[...document.styleSheets].forEach((styleSheet) => {
    try {
        const cssRules = [...styleSheet.cssRules].map((rule) => rule.cssText).join('');
        const style = document.createElement('style');
        style.textContent = cssRules;
        pipWindow.document.head.appendChild(style);
    } catch (e) {
        const link = document.createElement('link');
        link.rel = 'stylesheet';
        link.type = styleSheet.type;
        link.media = styleSheet.media;
        link.href = styleSheet.href ?? '';
        pipWindow.document.head.appendChild(link);
    }
});

元素克隆：将 #pipContent 元素克隆并添加到 PiP 窗口的 body 中，确保内容的一致性。
样式同步：遍历当前文档的所有样式表，将 CSS 规则注入到 PiP 窗口的 head 中，以保持样式的一致性。
- 异常处理：如果无法直接访问 cssRules，则尝试通过 link 标签引入外部样式表。

2.4 事件监听

pipWindow.addEventListener("pagehide", (event) => {
    console.log("已退出 PIP 窗口");
});

pipWindow.addEventListener('focus', () => {
    console.log("PiP 窗口进入了焦点状态");
});

pipWindow.addEventListener('blur', () => {
    console.log("PiP 窗口失去了焦点");
});

退出事件：监听 pagehide 事件，当 PiP 窗口被关闭时触发。
焦点事件：监听 focus 和 blur 事件，监控 PiP 窗口的焦点状态，方便进行相应的逻辑处理。

3. 关闭 PiP 窗口

// pipWindow.close();  // 可以手动调用关闭窗口

手动关闭：开发者可以在需要时调用 pipWindow.close() 方法来关闭 PiP 窗口。

三、实际应用场景

1. 视频播放器

最常见的应用场景是将视频播放器置于 PiP 窗口中，允许用户在进行其他操作时继续观看视频。例如，在线教育平台、直播平台等。

2. 实时通讯应用

在视频通话或语音通话中，用户可以将通话窗口置于 PiP 状态，方便在通话的同时进行其他操作，如浏览网页、查阅资料等。

3. 通知提醒

将重要的通知信息置于 PiP 窗口中，确保用户不会错过关键信息。例如，新闻提醒、股票行情更新等。

4. 辅助功能

在某些辅助功能场景中，PiP 窗口可以用于显示辅助信息，如字幕、翻译内容等，提升用户的阅读体验。

四、注意事项与最佳实践

1. 浏览器兼容性

虽然现代主流浏览器已支持 PiP 功能，但不同浏览器的实现细节可能有所不同。建议在开发过程中进行充分的测试，确保在不同浏览器中的表现一致。

2. 用户体验

用户控制：提供明确的用户控制选项，如开启/关闭 PiP 窗口、调整窗口大小等。
视觉提示：在 PiP 窗口中提供视觉提示，如关闭按钮、拖拽区域等，提升用户体验。
性能优化：避免在 PiP 窗口中加载过多资源，确保窗口的响应速度和流畅度。

3. 安全性

内容安全：确保 PiP 窗口中加载的内容是安全的，避免引入 XSS 攻击等安全漏洞。
隐私保护：在 PiP 窗口中处理用户隐私信息时，遵循相关的隐私保护法规和标准。

4. 移动设备支持

PiP 功能在移动设备上同样适用，但需要考虑屏幕尺寸和交互方式的差异。建议针对移动设备进行专门的优化，如调整窗口尺寸、简化交互方式等。

五、总结

Picture-in-Picture API 为网页开发者提供了一种强大的工具，可以显著提升用户体验。通过本文的详细解析，相信大家对 PiP API 的功能和使用方法有了更深入的了解。在实际应用中，开发者应充分考虑用户需求和场景特点，合理运用 PiP 功能，创造出更加丰富和便捷的网页体验。

希望本文对您有所帮助，如果您有任何疑问或建议，欢迎在评论区留言交流！

完整代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document Picture-in-Picture API 示例</title>
  <style>
    #pipContent {
      width: 600px;
      height: 300px;
      background: pink;
      font-size: 20px;
    }
  </style>
</head>
<body>
  <div id="container">
    <div id="pipContent">这是一个将要放入画中画的 div 元素！</div>
    <button id="clickBtn">切换画中画</button>
  </div>

  <script>
    // 检查是否支持 PiP 功能
    if ('documentPictureInPicture' in window) {
      console.log("🚀 浏览器支持 PiP 功能！");
    } else {
      console.warn("⚠️ 当前浏览器不支持 PiP 功能，更新浏览器或者换台电脑吧！");
    }

    // 请求 PiP 窗口
    document.getElementById("clickBtn").addEventListener("click", async function () {
      const pipContent = document.getElementById("pipContent");

      try {
        // 请求创建一个 PiP 窗口
        const pipWindow = await window.documentPictureInPicture.requestWindow({
          width: 200,  // 设置窗口的宽度
          height: 300  // 设置窗口的高度
        });

        // 将原始元素克隆并添加到 PiP 窗口中
        pipWindow.document.body.appendChild(pipContent.cloneNode(true));

        // 设置 PiP 样式同步
        [...document.styleSheets].forEach((styleSheet) => {
          try {
            const cssRules = [...styleSheet.cssRules].map(rule => rule.cssText).join('');
            const style = document.createElement('style');
            style.textContent = cssRules;
            pipWindow.document.head.appendChild(style);
          } catch (e) {
            const link = document.createElement('link');
            link.rel = 'stylesheet';
            link.type = styleSheet.type;
            link.media = styleSheet.media;
            link.href = styleSheet.href ?? '';
            pipWindow.document.head.appendChild(link);
          }
        });

        // 监听进入和退出 PiP 模式的事件
        pipWindow.addEventListener("pagehide", () => {
          console.log("已退出 PIP 窗口");
        });

        pipWindow.addEventListener('focus', () => {
          console.log("PiP 窗口进入了焦点状态");
        });

        pipWindow.addEventListener('blur', () => {
          console.log("PiP 窗口失去了焦点");
        });
      } catch (error) {
        console.error("请求 PiP 窗口时出错:", error);
      }
    });

    // 关闭 PiP 窗口
    // pipWindow.close();  // 可以手动调用关闭窗口
  </script>
</body>
</html>