ArtPlayer/docs/document/assets/plugin_document-pip.md.DmibV5MD.js

import{_ as a,o as n,c as e,ak as i,j as t}from"./chunks/framework.xxfEszSJ.js";const E=JSON.parse('{"title":"文档画中画","description":"","frontmatter":{},"headers":[],"relativePath":"plugin/document-pip.md","filePath":"plugin/document-pip.md","lastUpdated":1789497957000}'),p={name:"plugin/document-pip.md"};function l(d,s,h,r,k,c){return n(),e("div",null,s[0]||(s[0]=[i(`<h1 id="文档画中画" tabindex="-1">文档画中画 <a class="header-anchor" href="#文档画中画" aria-label="Permalink to &quot;文档画中画&quot;">​</a></h1><p><a href="./../en/plugin/document-pip.html">English</a></p><p>将整个播放器移到浏览器的 Document Picture-in-Picture 窗口，保留播放器控件。关闭窗口时将同一个播放器节点移回原位置。本页描述当前未发布的重构分支；在线示例和未固定版本的 npm/CDN 包不等于当前候选。</p><h2 id="安装和示例" tabindex="-1">安装和示例 <a class="header-anchor" href="#安装和示例" aria-label="Permalink to &quot;安装和示例&quot;">​</a></h2><div class="language-sh vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> artplayer</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> artplayer-plugin-document-pip</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br></div></div><div class="language-js vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Artplayer </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> artplayerPluginDocumentPip </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer-plugin-document-pip&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br></div></div><p>使用 script 时先加载 ArtPlayer，再加载 <code>dist/artplayer-plugin-document-pip.js</code>，全局名为 <code>artplayerPluginDocumentPip</code>。下面保留<a href="https://artplayer.org/?libs=./uncompiled/artplayer-plugin-document-pip/index.js&amp;example=document.pip" target="_blank" rel="noreferrer">在线示例</a>的原始代码。</p>`,7),t("div",{className:"run-code","data-libs":"./uncompiled/artplayer-plugin-document-pip/index.js"},"▶ Run Code",-1),i(`<div class="language-js vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// npm i artplayer-plugin-document-pip</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// import artplayerPluginDocumentPip from &#39;artplayer-plugin-document-pip&#39;;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> art</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Artplayer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  container: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;.artplayer-app&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;/assets/sample/video.mp4&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  plugins: [</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    artplayerPluginDocumentPip</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      width: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">480</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      height: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">270</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      fallbackToVideoPiP: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      placeholder: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Playing in Document Picture-in-Picture\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">art.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;document-pip&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Document Picture-in-Picture&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, state)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br><span class="line-number">11</span><br><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br><span class="line-number">15</span><br><span class="line-number">16</span><br><span class="line-number">17</span><br><span class="line-number">18</span><br><span class="line-number">19</span><br></div></div><h2 id="配置" tabindex="-1">配置 <a class="header-anchor" href="#配置" aria-label="Permalink to &quot;配置&quot;">​</a></h2><table tabindex="0"><thead><tr><th>字段</th><th>类型</th><th>默认值</th><th>含义</th></tr></thead><tbody><tr><td><code>width</code></td><td><code>number</code></td><td><code>480</code></td><td>请求的窗口宽度，由浏览器决定实际尺寸</td></tr><tr><td><code>height</code></td><td><code>number</code></td><td><code>270</code></td><td>请求的窗口高度</td></tr><tr><td><code>placeholder</code></td><td><code>string</code></td><td><code>&#39;Playing in Document Picture-in-Picture&#39;</code></td><td>原播放器位置的占位文字</td></tr><tr><td><code>fallbackToVideoPiP</code></td><td><code>boolean</code></td><td><code>true</code></td><td>未检测到 Document PiP API 时尝试设置 <code>art.pip = true</code></td></tr></tbody></table><p>插件安装名为 <code>artplayerPluginDocumentPip</code>，并添加画中画控制按钮。Document PiP 需要浏览器提供 <code>documentPictureInPicture.requestWindow</code>；能力检测为真仍可能因权限、调用环境或用户操作条件而打开失败。请在用户点击处理函数内直接调用 <code>open()</code> 或 <code>toggle()</code>，避免先等待网络等异步工作而丢失用户激活。</p><p>视频 PiP 降级也受浏览器及当前媒体能力限制。它不会移走整个播放器，不会将插件的 <code>isActive</code> 设为真，也不会发出 Document PiP 的激活事件。<code>close()</code> 管理 Document PiP 窗口；需要退出视频 PiP 时使用 <code>art.pip = false</code>。关闭降级选项不代表浏览器自动获得 Document PiP 能力。</p><h2 id="状态、方法和事件" tabindex="-1">状态、方法和事件 <a class="header-anchor" href="#状态、方法和事件" aria-label="Permalink to &quot;状态、方法和事件&quot;">​</a></h2><p>从 <code>art.plugins.artplayerPluginDocumentPip</code> 取得结果：</p><table tabindex="0"><thead><tr><th>成员</th><th>实际行为</th></tr></thead><tbody><tr><td><code>name</code></td><td>固定为 <code>artplayerPluginDocumentPip</code></td></tr><tr><td><code>isSupported</code></td><td>只读 getter，插件创建时的 Document PiP API 能力快照</td></tr><tr><td><code>isActive</code></td><td>只读 getter，当前是否持有 Document PiP 会话；不是视频 PiP 状态</td></tr><tr><td><code>open()</code></td><td>实际返回 <code>Promise&lt;void&gt;</code>；请求并移入播放器，已打开时不重复创建，请求中重复调用共享该次请求</td></tr><tr><td><code>close()</code></td><td>实际返回 <code>Promise&lt;void&gt;</code>；取消待处理请求或恢复节点并关闭窗口</td></tr><tr><td><code>toggle()</code></td><td>同步返回 <code>undefined</code>；打开，或关闭当前/正在申请的窗口</td></tr></tbody></table><p>成功激活及正常关闭时，播放器发出 <code>document-pip</code> 事件，参数分别为 <code>true</code> 和 <code>false</code>。插件同步更新原有 <code>artplayer-document-pip</code> 类并重新绑定跨文档事件，随后安排 resize；不要把此事件理解为一次媒体加载或播放成功。</p><p>正常窗口请求/还原失败会显示 notice 并写入控制台警告，<code>open()</code> 不是“返回即保证窗口打开”的成功标记。视频降级设置器抛出的错误仍可使 Promise 拒绝。关闭待处理请求后，迟到的窗口会被关闭，不再接管播放器。销毁播放器会释放窗口、控件、订阅和定时器，不再发出新的插件状态事件。插件没有单独的公开 <code>destroy()</code>。</p><p>插件尽力复制播放器所在文档的样式；无法读取的跨域样式及应用自行管理的外部 DOM 仍需在目标环境验证。Canvas、其他代理、键盘焦点和持续播放的支持也应逐一验证，不能仅凭能力字段推断。</p><h2 id="typescript-兼容类型" tabindex="-1">TypeScript 兼容类型 <a class="header-anchor" href="#typescript-兼容类型" aria-label="Permalink to &quot;TypeScript 兼容类型&quot;">​</a></h2><p>根入口和 <code>/legacy</code> 保留旧声明：工厂参数对象必填、<code>Result</code> 的状态字段可写、方法返回 <code>void</code>。JavaScript 实际允许省略配置，状态 getter 不可赋值，<code>open/close</code> 返回 Promise。旧类型保留是为了兼容已有消费者和替换函数，不表示运行时字段变成可写。</p><p>本包没有 <code>/runtime</code> 子路径。需要精确类型时，将真实工厂显式看作 <code>RuntimeFactory</code>：</p><div class="language-ts vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> documentPip </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer-plugin-document-pip&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { AsyncResult, RuntimeFactory } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer-plugin-document-pip&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> runtimeFactory</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> documentPip </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RuntimeFactory</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> installPip</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> runtimeFactory</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> installDefaultPip</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> runtimeFactory.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ width: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">480</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> closePip</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pip</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AsyncResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Promise</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pip.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">close</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br></div></div><p>命名类型为 <code>Option</code>、<code>Result</code>、<code>AsyncResult</code>、<code>Factory</code>、<code>RuntimeFactory</code>。精确视图仅用于未经替换的真实实现，不能将返回 void 的 mock 或被替换方法强转为异步实现。CommonJS 运行时支持 <code>require(package)(options)</code> 和 <code>.default(options)</code>；旧 <code>import = require</code> 类型视图使用 <code>.default</code>，需要直接调用时选择精确工厂视图。</p>`,16)]))}const u=a(p,[["render",l]]);export{E as __pageData,u as default};