mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-10 04:36:15 -08:00
30 lines
18 KiB
JavaScript
30 lines
18 KiB
JavaScript
import{_ as e,o as a,c as n,ak as i,j as t}from"./chunks/framework.xxfEszSJ.js";const u=JSON.parse('{"title":"Document Picture-in-Picture","description":"","frontmatter":{},"headers":[],"relativePath":"en/plugin/document-pip.md","filePath":"en/plugin/document-pip.md","lastUpdated":1789497957000}'),l={name:"en/plugin/document-pip.md"};function p(r,s,d,h,o,c){return a(),n("div",null,s[0]||(s[0]=[i(`<h1 id="document-picture-in-picture" tabindex="-1">Document Picture-in-Picture <a class="header-anchor" href="#document-picture-in-picture" aria-label="Permalink to "Document Picture-in-Picture""></a></h1><p><a href="./../../plugin/document-pip.html">简体中文</a></p><p>Move the whole player, including its controls, into a browser Document Picture-in-Picture window. Closing the window restores the same player node to its original position. This page describes the unreleased refactor branch; the online example and unpinned npm/CDN packages are not the current candidate.</p><h2 id="installation-and-example" tabindex="-1">Installation and example <a class="header-anchor" href="#installation-and-example" aria-label="Permalink to "Installation and example""></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;"> 'artplayer'</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;"> 'artplayer-plugin-document-pip'</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>For script usage, load ArtPlayer before <code>dist/artplayer-plugin-document-pip.js</code>. The global is <code>artplayerPluginDocumentPip</code>. The following code preserves the original <a href="https://artplayer.org/?libs=./uncompiled/artplayer-plugin-document-pip/index.js&example=document.pip" target="_blank" rel="noreferrer">online example</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 'artplayer-plugin-document-pip';</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;">'.artplayer-app'</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;">'/assets/sample/video.mp4'</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;">'document-pip'</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;">=></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;">'Document Picture-in-Picture'</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="options" tabindex="-1">Options <a class="header-anchor" href="#options" aria-label="Permalink to "Options""></a></h2><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>width</code></td><td><code>number</code></td><td><code>480</code></td><td>Requested window width; the browser determines the actual size</td></tr><tr><td><code>height</code></td><td><code>number</code></td><td><code>270</code></td><td>Requested window height</td></tr><tr><td><code>placeholder</code></td><td><code>string</code></td><td><code>'Playing in Document Picture-in-Picture'</code></td><td>Placeholder text at the original player position</td></tr><tr><td><code>fallbackToVideoPiP</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Try setting <code>art.pip = true</code> when the Document PiP API is absent</td></tr></tbody></table><p>The plugin registers as <code>artplayerPluginDocumentPip</code> and adds a PiP control button. It detects <code>documentPictureInPicture.requestWindow</code>; a positive result does not guarantee that permissions, the calling context or user activation will allow opening. Call <code>open()</code> or <code>toggle()</code> directly from a user click handler, before awaiting unrelated work.</p><p>Video PiP fallback also depends on the browser and media. It does not move the whole player, set the plugin's <code>isActive</code> flag or emit a Document PiP activation event. <code>close()</code> manages the Document PiP window; use <code>art.pip = false</code> to exit video PiP. Disabling fallback does not add Document PiP support to the browser.</p><h2 id="state-methods-and-events" tabindex="-1">State, methods and events <a class="header-anchor" href="#state-methods-and-events" aria-label="Permalink to "State, methods and events""></a></h2><p>Access the result through <code>art.plugins.artplayerPluginDocumentPip</code>:</p><table tabindex="0"><thead><tr><th>Member</th><th>Runtime behavior</th></tr></thead><tbody><tr><td><code>name</code></td><td>Always <code>artplayerPluginDocumentPip</code></td></tr><tr><td><code>isSupported</code></td><td>Readonly getter; Document PiP API capability snapshot taken at plugin creation</td></tr><tr><td><code>isActive</code></td><td>Readonly getter; whether a Document PiP session is held, not video PiP state</td></tr><tr><td><code>open()</code></td><td>Returns <code>Promise<void></code>; requests a window and moves the player, coalesces pending requests and does nothing when already open</td></tr><tr><td><code>close()</code></td><td>Returns <code>Promise<void></code>; cancels a pending request or restores the node and closes the window</td></tr><tr><td><code>toggle()</code></td><td>Returns <code>undefined</code> synchronously; opens or closes the active/pending window</td></tr></tbody></table><p>Successful activation and normal closure emit the player's <code>document-pip</code> event with <code>true</code> and <code>false</code>, respectively. The plugin updates the existing <code>artplayer-document-pip</code> class, rebinds document events and schedules resize. This event does not signal successful media loading or playback.</p><p>Normal window request/restoration failures display a notice and console warning; awaiting <code>open()</code> alone is not proof that a window opened. An error thrown by the video PiP fallback setter can still reject its Promise. A window arriving after cancellation is closed without adopting the player. Destroying the player releases the window, control, subscriptions and timers, suppressing further plugin state events. There is no separate public plugin <code>destroy()</code>.</p><p>Styles are copied from the player's document on a best-effort basis. Inaccessible cross-origin styles and externally managed DOM need validation in your environment. Canvas, other proxies, keyboard focus and continuous playback also need their own checks; the capability flag cannot establish those results.</p><h2 id="compatible-typescript-views" tabindex="-1">Compatible TypeScript views <a class="header-anchor" href="#compatible-typescript-views" aria-label="Permalink to "Compatible TypeScript views""></a></h2><p>The root and <code>/legacy</code> declarations preserve the old required options object, writable <code>Result</code> flags and void actions. JavaScript permits omitted options, the runtime flags are readonly getters, and <code>open/close</code> return Promises. The old shape preserves consumer and replacement-function compatibility; it does not make the runtime getters writable.</p><p>This package has no <code>/runtime</code> subpath. For accurate types, explicitly view the real factory as <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;"> 'artplayer-plugin-document-pip'</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;"> 'artplayer-plugin-document-pip'</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;"><</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">> {</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>Named types are <code>Option</code>, <code>Result</code>, <code>AsyncResult</code>, <code>Factory</code> and <code>RuntimeFactory</code>. Apply the precise view only to the unmodified implementation, not a void-returning mock or replaced method. CommonJS runtime supports both <code>require(package)(options)</code> and <code>.default(options)</code>. Historical <code>import = require</code> types use <code>.default</code>; use the precise factory view when direct calling is needed.</p>`,16)]))}const g=e(l,[["render",p]]);export{u as __pageData,g as default};
|