document picture-in-picture（document pip）是chrome 113+桌面版支持的实验性api，允许任意html内容在独立置顶窗口中显示，需手动开启flag，不依赖video元素，与video pip本质不同。
Document Picture-in-Picture（简称 Document PiP）不是 video.requestPictureInPicture()，而是让任意 HTML 内容（比如一个 div、实时图表、聊天窗口）真正“飞出浏览器”，在桌面级独立窗口中持续显示 —— 但它目前仅 Chrome 113+ 桌面版支持，且需手动开启实验性标志，移动端和 Safari/Edge 完全不支持。
Document PiP 和 Video PiP 根本不是一回事
很多人混淆两者：Video PiP 只能作用于 <video></video> 元素，而 Document PiP 是全新 API，目标是渲染一个完整 Document（即自定义 HTML 文档），由浏览器创建独立窗口托管。它不依赖视频元素，也不受 playsInline 或用户手势限制（但仍需用户触发）。
-
document.pictureInPictureElement只反映 Video PiP 状态，对 Document PiP 完全无感知 - Document PiP 的核心是
document.adoptNode()+window.createDocumentPictureInPictureWindow()（注意：该方法尚未标准化，当前实际可用的是document.pictureInPictureWindow的实验性写法） - Chrome 中必须启用
chrome://flags/#enable-document-picture-in-picture，否则调用直接报NotSupportedError - 无法通过 CSS 选择器如
::picture-in-picture控制其样式 —— 窗口内容完全由你传入的 DOM 决定，但窗口边框、标题栏、缩放按钮等系统 UI 不可定制
怎么用 document.pictureInPictureWindow 创建自定义 PiP 窗口
目前唯一稳定可用的方式是调用 document.pictureInPictureWindow（返回 Promise），并传入一个已挂载的 HTMLElement。注意：这个元素会被从原 DOM 移走，成为新窗口的根节点。
- 必须确保元素已插入文档（
document.body.appendChild(el)），否则抛NotFoundError - 不能传
iframe或含跨域资源的内容，会触发SecurityError - 窗口默认尺寸为 600×400，可通过
pipWindow.resizeTo(w, h)调整，但最小宽度约 320px（低于则被截断） - 退出时调用
pipWindow.close()，它会自动将元素移回原位置（如果原父节点还存在）
示例代码：
const el = document.querySelector('#pipContent');
const btn = document.querySelector('#pipBtn');
btn.addEventListener('click', async () => {
try {
const pipWindow = await document.pictureInPictureWindow;
pipWindow.document.body.appendChild(el); // 注意：不是 document.body！
} catch (err) {
console.warn('Document PiP 不可用:', err.name);
// 降级到 fixed + transform 伪小窗
}
});
为什么你的 Document PiP 调用静默失败
常见失败不是报错，而是根本没反应 —— 这通常是因为环境不满足最低要求：
- Chrome 版本低于 113，或未启用
chrome://flags/#enable-document-picture-in-picture - 页面非 HTTPS（本地
localhost除外），或处于 iframe 沙箱中（缺少allow-pip权限） - 元素含有
canvas的toDataURL()调用、WebGL 上下文或MediaStream，这些在 PiP 窗口中被禁用 - 监听了
leavepictureinpicture事件，但 Document PiP 并不触发该事件 —— 它只发beforeunload和unload（在pipWindow.document上）
别把 Document PiP 当通用小窗方案用
它目前只是 Chrome 实验性功能，连 Firefox 和 Safari 都没实现路线图；微信、抖音 WebView 更不可能支持。如果你要解决「小窗播放」问题，Document PiP 不是答案 —— 它连视频播放控制都不内建，所有交互（暂停、进度、音量）都得你自己用 postMessage + 自定义 UI 实现。真正落地的小窗逻辑，还是得靠 fixed + transform + z-index + 手势识别的自定义方案，Document PiP 目前只适合做 Chrome 桌面端的演示型工具（比如实时翻译浮窗、会议纪要摘要）。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
