x15904151985/ArtPlayer
1
0 Fork 0
mirror of https://github.com/zhw2590582/ArtPlayer.git synced 2026-10-18 02:21:20 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs(core): [SITE-04] clarify playback and source transitions

Browse Source
This commit is contained in:
Harvey Zhao committed 2026-09-16 08:59:21 +08:00
1 parent e8b48cbaed
commit 54e5cbf49c
92 files changed
+5597 -3016
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/document/advanced/property.html
+25 -7
View File
@@ -9,11 +9,11 @@
<link rel="preload stylesheet" href="/document/assets/style.BFaiTuR6.css" as="style">
<link rel="preload stylesheet" href="/document/vp-icons.css" as="style">
<script type="module" src="/document/assets/app.CghJeLiW.js"></script>
<script type="module" src="/document/assets/app.Dr65-s5r.js"></script>
<link rel="preload" href="/document/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/document/assets/chunks/theme.gKBuAxio.js">
<link rel="modulepreload" href="/document/assets/chunks/theme.CxZMOHgO.js">
<link rel="modulepreload" href="/document/assets/chunks/framework.xxfEszSJ.js">
<link rel="modulepreload" href="/document/assets/advanced_property.md.CMGtDSgL.lean.js">
<link rel="modulepreload" href="/document/assets/advanced_property.md.D9P6BOJ7.lean.js">
<script src="/document/main.js"></script>
<link rel="stylesheet" href="/document/style.css">
<link rel="shortcut icon" href="/document/favicon.ico">
@@ -32,7 +32,25 @@
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">art.loading.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">toggle</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;"> dispose</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> art.destroy.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bind</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(art);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> retained</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> void</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> dispose</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [instances, identifier, retained];</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><h2 id="play" tabindex="-1"><code>play</code> <a class="header-anchor" href="#play" aria-label="Permalink to &quot;`play`&quot;">​</a></h2><ul><li>Type: <code>Function</code></li></ul><p>播放视频</p><div className="run-code">▶ Run Code</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;">var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> 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:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [instances, identifier, retained];</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><h2 id="playback-contract" tabindex="-1">播放、进度与切源契约 <a class="header-anchor" href="#playback-contract" aria-label="Permalink to &quot;播放、进度与切源契约 {#playback-contract}&quot;">​</a></h2><h3 id="playback-results" tabindex="-1">方法返回与媒体状态 <a class="header-anchor" href="#playback-results" aria-label="Permalink to &quot;方法返回与媒体状态 {#playback-results}&quot;">​</a></h3><p>play() 返回 Promise，等待当前媒体的 play() 结果；原生拒绝仍向调用者传播。成功后才显示播放提示、派发自定义 play，再根据 mutex 暂停其他实例。切源或销毁使原请求过期时，调用者仍收到媒体结果，但过期请求不再更新提示、派发 play 或暂停其他实例。自定义监听器等后续逻辑抛错也可能使 Promise 拒绝，不能把所有拒绝都解释成解码失败。</p><p>pause() 同步调用媒体 pause()，随后显示暂停提示、派发自定义 pause，并返回媒体方法的结果；通常原生返回 undefined，代理可能不同。toggle() 根据调用时的 playing 选择并直接返回 play() 或 pause() 的结果，不保证每次都是 Promise。根 Player.toggle 保留历史 void 声明；根入口导出的 PlaybackControls 是无运行时对象的类型视图，可用于原生媒体的准确返回类型。runtime 入口还按媒体泛型保留代理返回值。</p><p>这三个方法捕获所属实例，抽取后调用仍操作原实例。自定义 play/pause 事件与 video:play/video:pause 不同：原生事件由浏览器派发，时间顺序不能仅从方法调用推断。playing 优先使用代理提供的 boolean playing，否则要求 currentTime &gt; 0、paused 为 false、ended 为 false 且 readyState &gt; 2；它不是简单的 !paused，时间零或缓冲期间可能为 false。</p><h3 id="playback-values" tabindex="-1">时间、音量与缓冲数值 <a class="header-anchor" href="#playback-values" aria-label="Permalink to &quot;时间、音量与缓冲数值 {#playback-values}&quot;">​</a></h3><table tabindex="0"><thead><tr><th>接口</th><th>实际行为</th></tr></thead><tbody><tr><td>currentTime</td><td>读取媒体时间，假值回退 0；写入先 parseFloat，再限制到 0 与 art.duration 之间，NaN 输入不写入。runtime 接受 number/string，根声明保留 number</td></tr><tr><td>duration</td><td>读取媒体时长，Infinity 和假值返回 0；直播的无限时长因此不作为可 seek 的有限终点</td></tr><tr><td>seek</td><td>只写属性；通过 currentTime 写入后显示进度提示并同步派发 seek(实际时间, 原始输入)，不是等待原生 seeked 的 Promise</td></tr><tr><td>forward / backward</td><td>只写属性，分别把 currentTime + 秒数或 currentTime - 秒数转给 seek；请传数字，旧 JS 的加法与减法强制转换并不相同</td></tr><tr><td>volume</td><td>写入限制到 [0, 1]，提示使用媒体接受后的值；只有非零音量写入 storage 的 volume 键，零不会覆盖上次非零值，也不会自动更改 muted</td></tr><tr><td>muted</td><td>写入媒体后同步派发 muted，重复赋相同值也会派发；传 boolean，原生字段的强制转换不改变事件携带的原始输入</td></tr><tr><td>playbackRate</td><td>真值且不同于当前值时写入媒体并提示；假值恢复为 1，相同值不再写入。浏览器不支持的速率仍可抛错，配置菜单不是浏览器能力保证</td></tr><tr><td>loadedTime</td><td>返回最后一个 buffered 区间的结束时间，无区间时为 0；不是所有区间长度之和，也不保证中间连续</td></tr><tr><td>loaded</td><td>loadedTime 除以原始媒体 duration；没有裁剪或无效值修正</td></tr><tr><td>played</td><td>currentTime 除以 art.duration；是当前位置比例，不是累计观看时长或原生 played 区间</td></tr></tbody></table><p>loaded/played 在未就绪、零时长或特殊代理状态下可能是 NaN/Infinity，显示百分比前检查 Number.isFinite；不要据此推断可播放性。seek、forward、backward、switch 和 quality 没有 getter，读取都是 undefined；根声明保留历史读取类型，runtime 如实描述只写行为。currentTime 直接写入不会同步派发自定义 seek，原生媒体仍会自行派发事件。Line truncated
<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;"> LegacyArtplayer </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:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { PlaybackControls } </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>
<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;">({ container: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;#player&#39;</span><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:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> nativeCommands</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">player</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LegacyArtplayer</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;"> PlaybackControls</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> player;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></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;"> togglePlayback</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;"> art.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">toggle</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// May reject when the branch requests play.</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></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;"> changeSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</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;"> art.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">switchUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(url);</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Completion includes cancellation; inspect art.url and media state as needed.</span></span>
<span class="line"><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;"> progress</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Number.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">isFinite</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(art.played) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> art.played </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">art.currentTime </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;12.5&#39;</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;"> unreadable</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> art.seek;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [nativeCommands, togglePlayback, changeSource, progress, unreadable];</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="play" tabindex="-1"><code>play</code> <a class="header-anchor" href="#play" aria-label="Permalink to &quot;`play`&quot;">​</a></h2><ul><li>Type: <code>Function</code></li></ul><p>播放视频</p><div className="run-code">▶ Run Code</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;">var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> 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;"> muted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -140,7 +158,7 @@
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> setTimeout</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 highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> art.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">switchUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;/assets/sample/video.mp4?t=0&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3000</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><span class="line-number">11</span><br></div></div><div class="warning custom-block"><p class="custom-block-title">提示</p><p><code>art.switch</code> 和 <code>art.switchUrl</code> 的功能是一样的，只是 <code>art.switchUrl</code> 方法会返回 <code>Promise</code>，当 <code>resolve</code> 时表示新地址是可以播放，<code>reject</code> 时表示新地址加载错误</p></div><h2 id="switchquality" tabindex="-1"><code>switchQuality</code> <a class="header-anchor" href="#switchquality" aria-label="Permalink to &quot;`switchQuality`&quot;">​</a></h2><ul><li>Type: <code>Function</code></li><li>Parameter: <code>String</code></li></ul><p>设置视频画质地址，和 <code>art.switchUrl</code> 类似，但会带上之前的播放进度</p><div className="run-code">▶ Run Code</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;">var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> 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;">});</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></div></div><div class="warning custom-block"><p class="custom-block-title">提示</p><p><code>art.switch</code> 与 <code>art.switchUrl</code> 使用同一切换流程，但只有方法返回可观察的 Promise。正常完成、被替代、销毁、相同地址或空地址都可能 resolve；内部自动恢复播放失败也不等同于切源失败。请处理 reject，并结合当前源与媒体状态判断结果，详见<a href="#source-transitions">地址切换契约</a>。</p></div><h2 id="switchquality" tabindex="-1"><code>switchQuality</code> <a class="header-anchor" href="#switchquality" aria-label="Permalink to &quot;`switchQuality`&quot;">​</a></h2><ul><li>Type: <code>Function</code></li><li>Parameter: <code>String</code></li></ul><p>设置视频画质地址，和 <code>art.switchUrl</code> 类似，但会带上之前的播放进度</p><div className="run-code">▶ Run Code</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;">var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> 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;">});</span></span>
@@ -484,8 +502,8 @@
<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;ready&#39;</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;"> art.subtitleOffset </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</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><span class="line-number">11</span><br></div></div></div></div></main><footer class="VPDocFooter" data-v-ef3a4dda data-v-07d71ff1><!--[--><!--]--><div class="edit-info" data-v-07d71ff1><div class="edit-link" data-v-07d71ff1><a class="VPLink link vp-external-link-icon no-icon edit-link-button" href="https://github.com/zhw2590582/ArtPlayer/tree/master/packages/artplayer-vitepress/docs/advanced/property.md" target="_blank" rel="noreferrer" data-v-07d71ff1><!--[--><span class="vpi-square-pen edit-link-icon" data-v-07d71ff1></span> Edit this page on GitHub<!--]--></a></div><div class="last-updated" data-v-07d71ff1><p class="VPLastUpdated" data-v-07d71ff1 data-v-e95db471>Last updated: <time datetime="2026-09-16T00:27:47.000Z" data-v-e95db471></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-07d71ff1><span class="visually-hidden" id="doc-footer-aria-label" data-v-07d71ff1>Pager</span><div class="pager" data-v-07d71ff1><a class="VPLink link pager-link prev" href="/document/component/setting.html" data-v-07d71ff1><!--[--><span class="desc" data-v-07d71ff1>Previous page</span><span class="title" data-v-07d71ff1>设置面板</span><!--]--></a></div><div class="pager" data-v-07d71ff1><a class="VPLink link pager-link next" href="/document/advanced/built-in.html" data-v-07d71ff1><!--[--><span class="desc" data-v-07d71ff1>Next page</span><span class="title" data-v-07d71ff1>高级属性</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"advanced_built-in.md\":\"C21J11LW\",\"advanced_class.md\":\"D-_T2vMZ\",\"advanced_event.md\":\"7BJRbghf\",\"advanced_global.md\":\"7lzYspte\",\"advanced_plugin.md\":\"CMpg85CT\",\"advanced_property.md\":\"CMGtDSgL\",\"component_contextmenu.md\":\"q3CUq7tf\",\"component_controls.md\":\"rXlEfqlM\",\"component_layers.md\":\"ng2y5lRx\",\"component_setting.md\":\"DzSNRgF2\",\"en_advanced_built-in.md\":\"CEhu35vH\",\"en_advanced_class.md\":\"DgtAHptq\",\"en_advanced_event.md\":\"BOHBlG_Y\",\"en_advanced_global.md\":\"OawZ0vlZ\",\"en_advanced_plugin.md\":\"dG7U736p\",\"en_advanced_property.md\":\"Dirol4Du\",\"en_component_contextmenu.md\":\"m0FODHh_\",\"en_component_controls.md\":\"CDH42Jtc\",\"en_component_layers.md\":\"DnWSTBIg\",\"en_component_setting.md\":\"DFfOVhnI\",\"en_index.md\":\"BBeGRjus\",\"en_plugin_ads.md\":\"BWhlqED9\",\"en_plugin_ambilight.md\":\"BIiOdZed\",\"en_plugin_asr.md\":\"DRBadoM6\",\"en_plugin_audio-track.md\":\"D4sy3hjB\",\"en_plugin_auto-thumbnail.md\":\"B4xf1kbN\",\"en_plugin_chapter.md\":\"Cj9k0GUZ\",\"en_plugin_chromecast.md\":\"f3zGiPeh\",\"en_plugin_danmuku-mask.md\":\"BlOM0Hxl\",\"en_plugin_danmuku.md\":\"CoPuwRfR\",\"en_plugin_dash-control.md\":\"By5hBqnJ\",\"en_plugin_document-pip.md\":\"Dk7dXmtu\",\"en_plugin_hls-control.md\":\"DI6n1NXK\",\"en_plugin_jassub.md\":\"B3qYHOri\",\"en_plugin_multiple-subtitles.md\":\"D13skM4m\",\"en_plugin_vast.md\":\"DY-xXj0Z\",\"en_plugin_vtt-thumbnail.md\":\"Y25-LZK8\",\"en_proxy_canvas.md\":\"DEZ3Qm1R\",\"en_proxy_mediabunny.md\":\"6_ZAU5hs\",\"en_start_i18n.md\":\"DxgNQ6qb\",\"en_start_option.md\":\"DcpaFLzR\",\"en_tool_iframe.md\":\"vqKTz6Jn\",\"en_tool_thumbnail.md\":\"CYSRU7kz\",\"index.md\":\"CvYUO2aO\",\"plugin_ads.md\":\"CSyEjgn0\",\"plugin_ambilight.md\":\"ChmjnhB2\",\"plugin_asr.md\":\"B1LNTxu0\",\"plugin_audio-track.md\":\"xXnVbPG8\",\"plugin_auto-thumbnail.md\":\"uVTSXyks\",\"plugin_chapter.md\":\"B_wxldhK\",\"plugin_chromecast.md\":\"COBfYOhI\",\"plugin_danmuku-mask.md\":\"DuAZXCsK\",\"plugin_danmuku.md\":\"CknGHRRA\",\"plugin_dash-control.md\":\"DGIVabzn\",\"plugin_document-pip.md\":\"DmibV5MD\",\"plugin_hls-control.md\":\"_mbfRiWn\",\"plugin_jassub.md\":\"plPiOu52\",\"plugin_multiple-subtitles.md\":\"B7ssJkhA\",\"plugin_vast.md\":\"DXoWKK9-\",\"plugin_vtt-thumbnail.md\":\"SpQ1vygQ\",\"proxy_canvas.md\":\"DZ3KjhXs\",\"proxy_mediabunny.md\":\"8OVtZiO-\",\"start_i18n.md\":\"D_Yw7TSy\",\"start_option.md\":\"CuBDvz6i\",\"tool_iframe.md\":\"gaYYO6Ds\",\"tool_thumbnail.md\":\"Bpybkc36\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Artplayer.js\",\"description\":\"ArtPlayer.js is a modern and full featured HTML5 video player\",\"base\":\"/document/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":\"dark\",\"themeConfig\":{\"siteTitle\":\"Artplayer.js\",\"logo\":\"/logo.png\",\"nav\":[{\"text\":\"中文版\",\"link\":\"/\"},{\"text\":\"English Docs\",\"link\":\"/en/\",\"activeMatch\":\"/en/\"},{\"text\":\"Online Editor\",\"link\":\"https://artplayer.org\"},{\"text\":\"🤖LLMs\",\"link\":\"https://artplayer.org/llms.txt\"},{\"text\":\"6.0.0 (unreleased)\",\"items\":[{\"text\":\"Changelog\",\"link\":\"https://github.com/zhw2590582/ArtPlayer/blob/master/CHANGELOG.md\"},{\"text\":\"Donation\",\"link\":\"https://github.com/zhw2590582/ArtPlayer#donations\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/zhw2590582/ArtPlayer\"}],\"sidebar\":{\"/\":[{\"text\":\"开始\",\"collapsible\":true,\"items\":[{\"text\":\"安装使用\",\"link\":\"/\"},{\"text\":\"基础选项\",\"link\":\"/start/option\"},{\"text\":\"语言设置\",\"link\":\"/start/i18n\"}]},{\"text\":\"组件\",\"collapsible\":true,\"items\":[{\"text\":\"业务层\",\"link\":\"/component/layers\"},{\"text\":\"控制器\",\"link\":\"/component/controls\"},{\"text\":\"右键菜单\",\"link\":\"/component/contextmenu\"},{\"text\":\"设置面板\",\"link\":\"/component/setting\"}]},{\"text\":\"高级\",\"collapsible\":true,\"items\":[{\"text\":\"实例属性\",\"link\":\"/advanced/property\"},{\"text\":\"高级属性\",\"link\":\"/advanced/built-in\"},{\"text\":\"静态属性\",\"link\":\"/advanced/class\"},{\"text\":\"全局属性\",\"link\":\"/advanced/global\"},{\"text\":\"实例事件\",\"link\":\"/advanced/event\"},{\"text\":\"编写插件\",\"link\":\"/advanced/plugin\"}]},{\"text\":\"插件\",\"collapsible\":true,\"items\":[{\"text\":\"🎉 弹幕库\",\"link\":\"/plugin/danmuku\"},{\"text\":\"弹幕遮罩\",\"link\":\"/plugin/danmuku-mask\"},{\"text\":\"视频广告\",\"link\":\"/plugin/ads\"},{\"text\":\"HLS 控制\",\"link\":\"/plugin/hls-control\"},{\"text\":\"DASH 控制\",\"link\":\"/plugin/dash-control\"},{\"text\":\"VTT 缩略图\",\"link\":\"/plugin/vtt-thumbnail\"},{\"text\":\"自动缩略图\",\"link\":\"/plugin/auto-thumbnail\"},{\"text\":\"多重字幕\",\"link\":\"/plugin/multiple-subtitles\"},{\"text\":\"ASS 字幕 - JASSUB\",\"link\":\"/pLine truncated
<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></div></div></div></div></main><footer class="VPDocFooter" data-v-ef3a4dda data-v-07d71ff1><!--[--><!--]--><div class="edit-info" data-v-07d71ff1><div class="edit-link" data-v-07d71ff1><a class="VPLink link vp-external-link-icon no-icon edit-link-button" href="https://github.com/zhw2590582/ArtPlayer/tree/master/packages/artplayer-vitepress/docs/advanced/property.md" target="_blank" rel="noreferrer" data-v-07d71ff1><!--[--><span class="vpi-square-pen edit-link-icon" data-v-07d71ff1></span> Edit this page on GitHub<!--]--></a></div><div class="last-updated" data-v-07d71ff1><p class="VPLastUpdated" data-v-07d71ff1 data-v-e95db471>Last updated: <time datetime="2026-09-16T00:47:41.000Z" data-v-e95db471></time></p></div></div><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-07d71ff1><span class="visually-hidden" id="doc-footer-aria-label" data-v-07d71ff1>Pager</span><div class="pager" data-v-07d71ff1><a class="VPLink link pager-link prev" href="/document/component/setting.html" data-v-07d71ff1><!--[--><span class="desc" data-v-07d71ff1>Previous page</span><span class="title" data-v-07d71ff1>设置面板</span><!--]--></a></div><div class="pager" data-v-07d71ff1><a class="VPLink link pager-link next" href="/document/advanced/built-in.html" data-v-07d71ff1><!--[--><span class="desc" data-v-07d71ff1>Next page</span><span class="title" data-v-07d71ff1>高级属性</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"advanced_built-in.md\":\"C21J11LW\",\"advanced_class.md\":\"D2pZ5HR2\",\"advanced_event.md\":\"7BJRbghf\",\"advanced_global.md\":\"7lzYspte\",\"advanced_plugin.md\":\"CMpg85CT\",\"advanced_property.md\":\"D9P6BOJ7\",\"component_contextmenu.md\":\"q3CUq7tf\",\"component_controls.md\":\"rXlEfqlM\",\"component_layers.md\":\"ng2y5lRx\",\"component_setting.md\":\"DzSNRgF2\",\"en_advanced_built-in.md\":\"CEhu35vH\",\"en_advanced_class.md\":\"t5pe4-Hy\",\"en_advanced_event.md\":\"BOHBlG_Y\",\"en_advanced_global.md\":\"OawZ0vlZ\",\"en_advanced_plugin.md\":\"dG7U736p\",\"en_advanced_property.md\":\"D_SVryb6\",\"en_component_contextmenu.md\":\"m0FODHh_\",\"en_component_controls.md\":\"CDH42Jtc\",\"en_component_layers.md\":\"DnWSTBIg\",\"en_component_setting.md\":\"DFfOVhnI\",\"en_index.md\":\"BBeGRjus\",\"en_plugin_ads.md\":\"BWhlqED9\",\"en_plugin_ambilight.md\":\"BIiOdZed\",\"en_plugin_asr.md\":\"DRBadoM6\",\"en_plugin_audio-track.md\":\"D4sy3hjB\",\"en_plugin_auto-thumbnail.md\":\"B4xf1kbN\",\"en_plugin_chapter.md\":\"Cj9k0GUZ\",\"en_plugin_chromecast.md\":\"f3zGiPeh\",\"en_plugin_danmuku-mask.md\":\"BlOM0Hxl\",\"en_plugin_danmuku.md\":\"CoPuwRfR\",\"en_plugin_dash-control.md\":\"By5hBqnJ\",\"en_plugin_document-pip.md\":\"Dk7dXmtu\",\"en_plugin_hls-control.md\":\"DI6n1NXK\",\"en_plugin_jassub.md\":\"B3qYHOri\",\"en_plugin_multiple-subtitles.md\":\"D13skM4m\",\"en_plugin_vast.md\":\"DY-xXj0Z\",\"en_plugin_vtt-thumbnail.md\":\"Y25-LZK8\",\"en_proxy_canvas.md\":\"DEZ3Qm1R\",\"en_proxy_mediabunny.md\":\"6_ZAU5hs\",\"en_start_i18n.md\":\"DxgNQ6qb\",\"en_start_option.md\":\"DcpaFLzR\",\"en_tool_iframe.md\":\"vqKTz6Jn\",\"en_tool_thumbnail.md\":\"CYSRU7kz\",\"index.md\":\"CvYUO2aO\",\"plugin_ads.md\":\"CSyEjgn0\",\"plugin_ambilight.md\":\"ChmjnhB2\",\"plugin_asr.md\":\"B1LNTxu0\",\"plugin_audio-track.md\":\"xXnVbPG8\",\"plugin_auto-thumbnail.md\":\"uVTSXyks\",\"plugin_chapter.md\":\"B_wxldhK\",\"plugin_chromecast.md\":\"COBfYOhI\",\"plugin_danmuku-mask.md\":\"DuAZXCsK\",\"plugin_danmuku.md\":\"CknGHRRA\",\"plugin_dash-control.md\":\"DGIVabzn\",\"plugin_document-pip.md\":\"DmibV5MD\",\"plugin_hls-control.md\":\"_mbfRiWn\",\"plugin_jassub.md\":\"plPiOu52\",\"plugin_multiple-subtitles.md\":\"B7ssJkhA\",\"plugin_vast.md\":\"DXoWKK9-\",\"plugin_vtt-thumbnail.md\":\"SpQ1vygQ\",\"proxy_canvas.md\":\"DZ3KjhXs\",\"proxy_mediabunny.md\":\"8OVtZiO-\",\"start_i18n.md\":\"D_Yw7TSy\",\"start_option.md\":\"CuBDvz6i\",\"tool_iframe.md\":\"gaYYO6Ds\",\"tool_thumbnail.md\":\"Bpybkc36\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Artplayer.js\",\"description\":\"ArtPlayer.js is a modern and full featured HTML5 video player\",\"base\":\"/document/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":\"dark\",\"themeConfig\":{\"siteTitle\":\"Artplayer.js\",\"logo\":\"/logo.png\",\"nav\":[{\"text\":\"中文版\",\"link\":\"/\"},{\"text\":\"English Docs\",\"link\":\"/en/\",\"activeMatch\":\"/en/\"},{\"text\":\"Online Editor\",\"link\":\"https://artplayer.org\"},{\"text\":\"🤖LLMs\",\"link\":\"https://artplayer.org/llms.txt\"},{\"text\":\"6.0.0 (unreleased)\",\"items\":[{\"text\":\"Changelog\",\"link\":\"https://github.com/zhw2590582/ArtPlayer/blob/master/CHANGELOG.md\"},{\"text\":\"Donation\",\"link\":\"https://github.com/zhw2590582/ArtPlayer#donations\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/zhw2590582/ArtPlayer\"}],\"sidebar\":{\"/\":[{\"text\":\"开始\",\"collapsible\":true,\"items\":[{\"text\":\"安装使用\",\"link\":\"/\"},{\"text\":\"基础选项\",\"link\":\"/start/option\"},{\"text\":\"语言设置\",\"link\":\"/start/i18n\"}]},{\"text\":\"组件\",\"collapsible\":true,\"items\":[{\"text\":\"业务层\",\"link\":\"/component/layers\"},{\"text\":\"控制器\",\"link\":\"/component/controls\"},{\"text\":\"右键菜单\",\"link\":\"/component/contextmenu\"},{\"text\":\"设置面板\",\"link\":\"/component/setting\"}]},{\"text\":\"高级\",\"collapsible\":true,\"items\":[{\"text\":\"实例属性\",\"link\":\"/advanced/property\"},{\"text\":\"高级属性\",\"link\":\"/advanced/built-in\"},{\"text\":\"静态属性\",\"link\":\"/advanced/class\"},{\"text\":\"全局属性\",\"link\":\"/advanced/global\"},{\"text\":\"实例事件\",\"link\":\"/advanced/event\"},{\"text\":\"编写插件\",\"link\":\"/advanced/plugin\"}]},{\"text\":\"插件\",\"collapsible\":true,\"items\":[{\"text\":\"🎉 弹幕库\",\"link\":\"/plugin/danmuku\"},{\"text\":\"弹幕遮罩\",\"link\":\"/plugin/danmuku-mask\"},{\"text\":\"视频广告\",\"link\":\"/plugin/ads\"},{\"text\":\"HLS 控制\",\"link\":\"/plugin/hls-control\"},{\"text\":\"DASH 控制\",\"link\":\"/plugin/dash-control\"},{\"text\":\"VTT 缩略图\",\"link\":\"/plugin/vtt-thumbnail\"},{\"text\":\"自动缩略图\",\"link\":\"/plugin/auto-thumbnail\"},{\"text\":\"多重字幕\",\"link\":\"/plugin/multiple-subtitles\"},{\"text\":\"ASS 字幕 - JASSUB\",\"link\":\"/pLine truncated
</body>
</html>