@realsee/five 6.8.0-alpha.25 → 6.8.0-alpha.27

package/docs/documents/api.html

@@ -92,7 +92,7 @@
 </table>
 <h2 id="initialization-configuration-" class="tsd-anchor-link">Initialization Configuration (<code>FiveInitArgs</code>)<a href="#initialization-configuration-" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>Configuration object passed to the <code>Five</code> constructor.</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** External WebGLRenderer. If provided, internal renderer creation is skipped. */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Width/Height of the viewport relative to container (0-1). */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: { </span><span class="hl-6">left</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">bottom</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">width</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">height</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> };</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Canvas background color. Default: 0x181A1C */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Canvas background alpha (0-1). Default: 1 */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Enable antialiasing. Default: false */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Auto-play rendering loop. Default: true */</span><br/><span class="hl-1">  </span><span class="hl-6">play</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Enable on-demand rendering to save battery. Default: true */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Max FPS limit. false = unlimited. Default: false */</span><br/><span class="hl-1">  </span><span class="hl-6">maxFps</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">false</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Mode transition duration in ms. Default: 800 */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Initial plugins to load. */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Dynamic image configuration for optimization. */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Dynamic texture configuration for optimization. */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** External WebGLRenderer. If provided, internal renderer creation is skipped. */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Width/Height of the viewport relative to container (0-1). */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: { </span><span class="hl-6">left</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">bottom</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">width</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-6">height</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> };</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Canvas background color. Default: 0x181A1C */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Canvas background alpha (0-1). Default: 1 */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Enable antialiasing. Default: false */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Auto-play rendering loop. Default: true */</span><br/><span class="hl-1">  </span><span class="hl-6">play</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Enable on-demand rendering to save battery. Default: true */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Max FPS limit. false = unlimited. Default: false */</span><br/><span class="hl-1">  </span><span class="hl-6">maxFps</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">false</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Mode transition duration in ms. Default: 1000 */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Initial plugins to load. */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Dynamic image configuration for optimization. */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">/** Dynamic texture configuration for optimization. */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="core-methods" class="tsd-anchor-link">Core Methods<a href="#core-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -199,22 +199,47 @@
 <tr>
 <td style="text-align:left"><code>gesture.tap</code></td>
 <td style="text-align:left">Triggered on tap/click. Replaces <code>wantsTapGesture</code>.</td>
-<td style="text-align:left"><code>{ pointers, event, ... }</code></td>
+<td style="text-align:left"><code>GestureEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>gesture.dbltap</code></td>
+<td style="text-align:left">Triggered on double tap/click.</td>
+<td style="text-align:left"><code>GestureEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>gesture.pan</code></td>
 <td style="text-align:left">Triggered on pan/drag.</td>
-<td style="text-align:left"><code>{ pointers, ... }</code></td>
+<td style="text-align:left"><code>GestureEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>gesture.pinch</code></td>
 <td style="text-align:left">Triggered on pinch/zoom.</td>
-<td style="text-align:left"><code>{ scale, ... }</code></td>
+<td style="text-align:left"><code>GestureEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>gesture.press</code></td>
 <td style="text-align:left">Triggered on long press.</td>
-<td style="text-align:left"><code>{ pointers, ... }</code></td>
+<td style="text-align:left"><code>GestureEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>gesture.mousewheel</code></td>
+<td style="text-align:left">Triggered on mouse wheel scroll.</td>
+<td style="text-align:left"><code>GestureEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>gesture.mousemove</code></td>
+<td style="text-align:left">Triggered on mouse move.</td>
+<td style="text-align:left"><code>GestureEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>gesture.momentum</code></td>
+<td style="text-align:left">Triggered on inertia movement after pan.</td>
+<td style="text-align:left"><code>GestureEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>gesture.fire</code></td>
+<td style="text-align:left">Triggered when any gesture event fires.</td>
+<td style="text-align:left"><code>GestureEvent</code></td>
 </tr>
 </tbody>
 </table>
@@ -261,6 +286,11 @@
 <td style="text-align:left"><code>WorksEvent</code></td>
 </tr>
 <tr>
+<td style="text-align:left"><code>works.ready</code></td>
+<td style="text-align:left">Triggered when work data is loaded and controller is ready.</td>
+<td style="text-align:left"><code>WorksEvent</code></td>
+</tr>
+<tr>
 <td style="text-align:left"><code>models.load</code></td>
 <td style="text-align:left">Triggered when models are loaded.</td>
 <td style="text-align:left"><code>ModelSceneEvent</code></td>
@@ -268,12 +298,17 @@
 <tr>
 <td style="text-align:left"><code>model.tileLoad</code></td>
 <td style="text-align:left">Triggered when a 3D tile is loaded.</td>
-<td style="text-align:left"><code>Tile</code></td>
+<td style="text-align:left"><code>ModelTileEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>model.tileUnload</code></td>
 <td style="text-align:left">Triggered when a 3D tile is unloaded.</td>
-<td style="text-align:left"><code>Tile</code></td>
+<td style="text-align:left"><code>ModelTileEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>pano.prepare</code></td>
+<td style="text-align:left">Triggered before switching to a new pano. <code>ExtendableEvent</code>, supports <code>waitUntil</code>.</td>
+<td style="text-align:left"><code>PanoPrepareEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>pano.arrived</code></td>
@@ -281,9 +316,19 @@
 <td style="text-align:left"><code>PanoEvent</code></td>
 </tr>
 <tr>
+<td style="text-align:left"><code>pano.moving</code></td>
+<td style="text-align:left">Triggered during pano transition animation.</td>
+<td style="text-align:left"><code>PanoEvent</code></td>
+</tr>
+<tr>
+<td style="text-align:left"><code>pano.error</code></td>
+<td style="text-align:left">Triggered when pano loading or movement fails.</td>
+<td style="text-align:left"><code>PanoEvent</code></td>
+</tr>
+<tr>
 <td style="text-align:left"><code>pano.texture.progress</code></td>
 <td style="text-align:left">Triggered when panorama texture loading progresses.</td>
-<td style="text-align:left"><code>{ progress, panoIndex }</code></td>
+<td style="text-align:left"><code>PanoTextureEvent</code></td>
 </tr>
 <tr>
 <td style="text-align:left"><code>render</code></td>
@@ -291,6 +336,11 @@
 <td style="text-align:left"><code>RenderEvent</code></td>
 </tr>
 <tr>
+<td style="text-align:left"><code>render.prepare</code></td>
+<td style="text-align:left">Triggered before each render frame.</td>
+<td style="text-align:left"><code>RenderEvent</code></td>
+</tr>
+<tr>
 <td style="text-align:left"><code>error</code></td>
 <td style="text-align:left">Triggered on internal errors.</td>
 <td style="text-align:left"><code>Error</code></td>

package/docs/documents/features_event.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/event | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/event</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="events-事件系统" class="tsd-anchor-link">Events (事件系统)<a href="#events-事件系统" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
 <ul>
 <li><strong>Summary</strong>: Five 提供了一套基于发布/订阅模式的事件系统，用于监听用户交互、状态变更、数据加载及渲染生命周期。</li>
-<li><strong>Schema</strong>: <code>on</code> / <code>once</code> / <code>off</code> 接口定义。</li>
-<li><strong>Concepts</strong>: Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.</li>
-<li><strong>Examples</strong>: 监听全景移动、手势交互及状态变更。</li>
+<li><strong>Schema</strong>: <code>on</code> / <code>once</code> / <code>off</code> 接口定义；<code>BaseEvent</code> / <code>BaseExtendableEvent</code> 事件对象。</li>
+<li><strong>Concepts</strong>: Event 对象（<code>preventDefault</code> / <code>waitUntil</code>）、Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.</li>
+<li><strong>Examples</strong>: 监听全景移动、手势交互及状态变更；使用 <code>preventDefault</code> 拦截默认行为；使用 <code>waitUntil</code> 延迟点位切换。</li>
 </ul>
 <h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <blockquote>
@@ -35,6 +35,41 @@
 <li><strong>name</strong>: (可选) 若不传，则清空所有事件；若传，则取消指定类型的事件。</li>
 <li><strong>callback</strong>: (可选) 若传，则仅取消该特定的回调函数；若不传，则取消该类型下的所有回调。</li>
 </ul>
+<h2 id="event-对象" class="tsd-anchor-link">Event 对象<a href="#event-对象" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<blockquote>
+<p><strong>Definition</strong>: <a href="../../five/utils/event.d.ts">BaseEvent / BaseExtendableEvent</a></p>
+</blockquote>
+<p>Five 中所有事件回调的参数都是一个 Event 对象，分为两种基础类型：</p>
+<h3 id="baseevent" class="tsd-anchor-link">BaseEvent<a href="#baseevent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>所有事件的基础接口，包含以下属性和方法：</p>
+<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">BaseEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 事件类型名称 */</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 事件触发时的时间戳 */</span><br/><span class="hl-1">  </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 阻止事件的默认行为 */</span><br/><span class="hl-1">  </span><span class="hl-5">preventDefault</span><span class="hl-1">(): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否已调用过 preventDefault */</span><br/><span class="hl-1">  </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="baseextendableevent" class="tsd-anchor-link">BaseExtendableEvent<a href="#baseextendableevent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>继承自 <code>BaseEvent</code>，额外提供 <code>waitUntil</code> 方法，用于在事件处理中插入异步等待逻辑：</p>
+<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">BaseExtendableEvent</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">BaseEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">waitUntil</span><span class="hl-1">(</span><span class="hl-6">f</span><span class="hl-1">: </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-7">any</span><span class="hl-1">&gt;): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<p>目前 <code>pano.prepare</code> 事件使用 <code>BaseExtendableEvent</code>（对应 <code>PanoPrepareEvent</code>），其余事件均基于 <code>BaseEvent</code>。</p>
+<h3 id="preventdefault" class="tsd-anchor-link">preventDefault<a href="#preventdefault" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>调用 <code>event.preventDefault()</code> 可以阻止事件的默认行为。Five 内部会在触发事件后检查 <code>event.defaultPrevented</code>，若为 <code>true</code> 则跳过后续的默认处理逻辑。</p>
+<p>比如：</p>
+<ul>
+<li><code>gesture.tap</code>：阻止默认的点位跳转或相机弹跳动画。</li>
+<li><code>intersect.update</code>：阻止默认的交互高亮行为。</li>
+</ul>
+<pre><code class="typescript"><span class="hl-8">// 示例：阻止点击时的默认点位跳转</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-5">shouldBlockNavigation</span><span class="hl-1">()) {</span><br/><span class="hl-1">    </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><span class="hl-1">    </span><span class="hl-8">// 执行自定义逻辑</span><br/><span class="hl-1">    </span><span class="hl-5">showCustomMenu</span><span class="hl-1">(</span><span class="hl-6">event</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 示例：阻止拖拽时的默认相机旋转</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.pan&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-8">// 用拖拽手势实现自定义交互（如绘制标注）</span><br/><span class="hl-1">  </span><span class="hl-5">drawAnnotation</span><span class="hl-1">(</span><span class="hl-6">event</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="waituntil" class="tsd-anchor-link">waitUntil<a href="#waituntil" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p><code>waitUntil(promise)</code> 仅在 <code>ExtendableEvent</code> 上可用。调用后，Five 会等待传入的 Promise 完成后再继续后续流程。可多次调用，所有 Promise 会被并行等待。</p>
+<p>目前仅 <code>pano.prepare</code> 事件支持 <code>waitUntil</code>。</p>
+<pre><code class="typescript"><span class="hl-8">// 示例：在切换点位前预加载资源</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.prepare&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">// 等待自定义资源加载完成后再继续点位切换</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">waitUntil</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-5">loadCustomResources</span><span class="hl-1">(</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">pano</span><span class="hl-1">)</span><br/><span class="hl-1">  );</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 可以多次调用，所有 Promise 会被并行等待</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">waitUntil</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-5">preloadTextures</span><span class="hl-1">(</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">pano</span><span class="hl-1">)</span><br/><span class="hl-1">  );</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 示例：通过 waitUntil reject 来取消走点</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.prepare&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">waitUntil</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-5">showConfirmDialog</span><span class="hl-1">(</span><span class="hl-9">&quot;是否前往该点位？&quot;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">confirmed</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">confirmed</span><span class="hl-1">) {</span><br/><span class="hl-1">        </span><span class="hl-10">throw</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Error</span><span class="hl-1">(</span><span class="hl-9">&quot;用户取消走点&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">      }</span><br/><span class="hl-1">    })</span><br/><span class="hl-1">  );</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<blockquote>
+<p><strong>注意</strong>: <code>preventDefault</code> 和 <code>waitUntil</code> 必须在事件回调的同步执行阶段调用，不能放在 <code>await</code> 之后。</p>
+</blockquote>
 <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>Five 的事件系统将事件主要分为以下几类：</p>
 <h3 id="gesture-events-交互手势" class="tsd-anchor-link">Gesture Events (交互手势)<a href="#gesture-events-交互手势" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -51,6 +86,7 @@
 <h3 id="pano-events-全景导航" class="tsd-anchor-link">Pano Events (全景导航)<a href="#pano-events-全景导航" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>监听全景图的点位切换过程。</p>
 <ul>
+<li><code>pano.prepare</code>: 准备切换到新点位。这是一个 <code>ExtendableEvent</code>，支持通过 <code>waitUntil(promise)</code> 延迟后续加载流程（如预加载资源），以及通过 <code>preventDefault()</code> 取消本次走点。</li>
 <li><code>pano.arrived</code>: 成功到达新点位（移动动画结束）。</li>
 <li><code>pano.moving</code>: 正在移动到新点位（动画进行中）。</li>
 <li><code>pano.willChange</code>: 即将发生点位变更（旧版兼容）。</li>
@@ -80,7 +116,7 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>监听点击事件并打印日志。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 监听点击事件</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">pose</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;User tapped at:&quot;</span><span class="hl-1">, </span><span class="hl-6">pose</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 监听点位变更完成</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.arrived&quot;</span><span class="hl-1">, (</span><span class="hl-6">index</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Arrived at pano index:&quot;</span><span class="hl-1">, </span><span class="hl-6">index</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 监听点击事件</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;User tapped at:&quot;</span><span class="hl-1">, </span><span class="hl-6">event</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 监听点位变更完成</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.arrived&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Arrived at pano:&quot;</span><span class="hl-1">, </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">pano</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法-advanced-usage" class="tsd-anchor-link">进阶用法 (Advanced Usage)<a href="#进阶用法-advanced-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -98,7 +134,7 @@
 <li><a href="features_five.html">five.md</a>: Five 核心类说明。</li>
 </ul>
 <hr>
-<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">events</span><span class="hl-1">, </span><span class="hl-2">interaction</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">, </span><span class="hl-2">gesture</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">]</span>
+<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">events</span><span class="hl-1">, </span><span class="hl-2">interaction</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">, </span><span class="hl-2">gesture</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">, </span><span class="hl-2">preventDefault</span><span class="hl-1">, </span><span class="hl-2">waitUntil</span><span class="hl-1">]</span>
 </code><button type="button">Copy</button></pre>
 
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#events-事件系统"><span>Events (事件系统)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#on"><span>on</span></a></li><li><a href="#once"><span>once</span></a></li><li><a href="#off"><span>off</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#gesture-events-交互手势"><span>Gesture <wbr/>Events (交互手势)</span></a></li><li><a href="#pano-events-全景导航"><span>Pano <wbr/>Events (全景导航)</span></a></li><li><a href="#state-events-状态变更"><span>State <wbr/>Events (状态变更)</span></a></li><li><a href="#model-work-events-数据加载"><span>Model &amp; <wbr/>Work <wbr/>Events (数据加载)</span></a></li><li><a href="#render-events-渲染循环"><span>Render <wbr/>Events (渲染循环)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法-advanced-usage"><span>进阶用法 (<wbr/>Advanced <wbr/>Usage)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#events-事件系统"><span>Events (事件系统)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#on"><span>on</span></a></li><li><a href="#once"><span>once</span></a></li><li><a href="#off"><span>off</span></a></li></ul></li><li><a href="#event-对象"><span>Event 对象</span></a></li><li><ul><li><a href="#baseevent"><span>Base<wbr/>Event</span></a></li><li><a href="#baseextendableevent"><span>Base<wbr/>Extendable<wbr/>Event</span></a></li><li><a href="#preventdefault"><span>prevent<wbr/>Default</span></a></li><li><a href="#waituntil"><span>wait<wbr/>Until</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#gesture-events-交互手势"><span>Gesture <wbr/>Events (交互手势)</span></a></li><li><a href="#pano-events-全景导航"><span>Pano <wbr/>Events (全景导航)</span></a></li><li><a href="#state-events-状态变更"><span>State <wbr/>Events (状态变更)</span></a></li><li><a href="#model-work-events-数据加载"><span>Model &amp; <wbr/>Work <wbr/>Events (数据加载)</span></a></li><li><a href="#render-events-渲染循环"><span>Render <wbr/>Events (渲染循环)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法-advanced-usage"><span>进阶用法 (<wbr/>Advanced <wbr/>Usage)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>

package/docs/documents/features_flowing-light-2d-pass.html

@@ -157,122 +157,25 @@
 <p>释放 InstancedMesh、着色材质和渲染目标资源,避免内存泄漏。销毁 Pass 时必须调用。</p>
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>import { Five } from '@realsee/five';
-import { FlowingLight2DPass } from '../../lib/five/renderer/postprocessing';
-import * as THREE from 'three';</p>
-<p>const five = new Five();</p>
-<p>// 创建 2D 流光通道
-const flowing2D = new FlowingLight2DPass(five.camera);</p>
-<p>// 定义一条屏幕空间的路径(归一化坐标)
-const path = [
-new THREE.Vector2(0.2, 0.2),
-new THREE.Vector2(0.5, 0.8),
-new THREE.Vector2(0.8, 0.2),
-];
-const totalLen = 1.2; // 归一化单位</p>
-<p>flowing2D.setLines([{
-points: path,
-totalLength: totalLen,
-color: new THREE.Color(0x00ff00),
-opacity: 0.9,
-duration: 2000,
-lineWidth: 0.01,
-}]);</p>
-<p>five.addPass(flowing2D);</p>
-<p>function animate() {
-requestAnimationFrame(animate);
-five.render();
-}
-animate();</p>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">FlowingLight2DPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../../lib/five/renderer/postprocessing&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 创建 2D 流光通道</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">flowing2D</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 定义一条屏幕空间的路径(归一化坐标)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">path</span><span class="hl-1"> = [</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.2</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-11">0.8</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.8</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">];</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">totalLen</span><span class="hl-1"> = </span><span class="hl-11">1.2</span><span class="hl-1">; </span><span class="hl-8">// 归一化单位</span><br/><br/><span class="hl-6">flowing2D</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([{</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> </span><span class="hl-6">path</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-6">totalLen</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ff00</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.9</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">}]);</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">flowing2D</span><span class="hl-1">);</span><br/><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">animate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-5">requestAnimationFrame</span><span class="hl-1">(</span><span class="hl-6">animate</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">render</span><span class="hl-1">();</span><br/><span class="hl-1">}</span><br/><span class="hl-5">animate</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
 <h3 id="多条路径-动态更新" class="tsd-anchor-link">多条路径 &amp; 动态更新<a href="#多条路径-动态更新" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>const pass = new FlowingLight2DPass(five.camera);</p>
-<p>// 初始路径集合
-const paths = [
-{
-points: [
-new THREE.Vector2(0.1, 0.1),
-new THREE.Vector2(0.9, 0.1),
-],
-totalLength: 0.8,
-color: new THREE.Color(0xff6600),
-duration: 1500,
-lineWidth: 0.01,
-},
-{
-points: [
-new THREE.Vector2(0.1, 0.5),
-new THREE.Vector2(0.9, 0.5),
-],
-totalLength: 0.8,
-color: new THREE.Color(0x0066ff),
-opacity: 0.7,
-duration: 2000,
-delay: 500,
-lineWidth: 0.015,
-},
-];</p>
-<p>pass.setLines(paths);
-five.addPass(pass);</p>
-<p>// 响应用户交互动态更新路径
-document.addEventListener('click', (e) =&gt; {
-const rect = five.canvas.getBoundingClientRect();
-const x = (e.clientX - rect.left) / rect.width;
-const y = (e.clientY - rect.top) / rect.height; // 左上角为原点,无需翻转</p>
-<p>const newPath = {
-points: [
-new THREE.Vector2(0.5, 0.5),
-new THREE.Vector2(x, y),
-],
-totalLength: Math.hypot(x - 0.5, y - 0.5),
-color: new THREE.Color(Math.random() * 0xffffff),
-duration: 1200,
-lineWidth: 0.01,
-};
-pass.setLines([...paths, newPath]);
-});</p>
+<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 初始路径集合</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">paths</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0xff6600</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x0066ff</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.7</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">delay:</span><span class="hl-1"> </span><span class="hl-11">500</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.015</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">(</span><span class="hl-6">paths</span><span class="hl-1">);</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">pass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 响应用户交互动态更新路径</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&#39;click&#39;</span><span class="hl-1">, (</span><span class="hl-6">e</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">canvas</span><span class="hl-1">.</span><span class="hl-5">getBoundingClientRect</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><span class="hl-1"> = (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">clientX</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">y</span><span class="hl-1"> = (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">clientY</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1">; </span><span class="hl-8">// 左上角为原点,无需翻转</span><br/><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">newPath</span><span class="hl-1"> = {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-6">x</span><span class="hl-1">, </span><span class="hl-6">y</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">hypot</span><span class="hl-1">(</span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">() * </span><span class="hl-11">0xffffff</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1200</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">  </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([...</span><span class="hl-6">paths</span><span class="hl-1">, </span><span class="hl-6">newPath</span><span class="hl-1">]);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
 <h3 id="计算路径总长度" class="tsd-anchor-link">计算路径总长度<a href="#计算路径总长度" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>function calculatePathLength(points: THREE.Vector2[]): number {
-let length = 0;
-for (let i = 1; i &lt; points.length; i++) {
-length += points[i].distanceTo(points[i - 1]);
-}
-return length;
-}</p>
-<p>const points = [
-new THREE.Vector2(0.3, 0.7),
-new THREE.Vector2(0.7, 0.7),
-new THREE.Vector2(0.7, 0.3),
-new THREE.Vector2(0.3, 0.3),
-new THREE.Vector2(0.3, 0.7),
-];</p>
-<p>const pathLine = {
-points: points,
-totalLength: calculatePathLength(points),
-color: new THREE.Color(0x00ffff),
-duration: 2000,
-lineWidth: 0.01,
-};</p>
+<pre><code class="typescript"><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">calculatePathLength</span><span class="hl-1">(</span><span class="hl-6">points</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">[]): </span><span class="hl-7">number</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">length</span><span class="hl-1"> = </span><span class="hl-11">0</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-10">for</span><span class="hl-1"> (</span><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">i</span><span class="hl-1"> = </span><span class="hl-11">1</span><span class="hl-1">; </span><span class="hl-6">i</span><span class="hl-1"> &lt; </span><span class="hl-6">points</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1">; </span><span class="hl-6">i</span><span class="hl-1">++) {</span><br/><span class="hl-1">    </span><span class="hl-6">length</span><span class="hl-1"> += </span><span class="hl-6">points</span><span class="hl-1">[</span><span class="hl-6">i</span><span class="hl-1">].</span><span class="hl-5">distanceTo</span><span class="hl-1">(</span><span class="hl-6">points</span><span class="hl-1">[</span><span class="hl-6">i</span><span class="hl-1"> - </span><span class="hl-11">1</span><span class="hl-1">]);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">length</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">points</span><span class="hl-1"> = [</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pathLine</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> </span><span class="hl-6">points</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-5">calculatePathLength</span><span class="hl-1">(</span><span class="hl-6">points</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ffff</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+
 <h3 id="矩形路径示例" class="tsd-anchor-link">矩形路径示例<a href="#矩形路径示例" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 创建一个矩形路径(注意:左上角为原点)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rectPath</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),  </span><span class="hl-8">// 左上</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),  </span><span class="hl-8">// 右上</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),  </span><span class="hl-8">// 右下</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),  </span><span class="hl-8">// 左下</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),  </span><span class="hl-8">// 闭合路径</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">1.6</span><span class="hl-1">, </span><span class="hl-8">// 矩形周长</span><br/><span class="hl-1">  </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">1.0</span><span class="hl-1">, </span><span class="hl-11">1.0</span><span class="hl-1">, </span><span class="hl-11">1.0</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">1.0</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">4000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">delay:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([</span><span class="hl-6">rectPath</span><span class="hl-1">]);</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="高-dpr-场景优化" class="tsd-anchor-link">高 DPR 场景优化<a href="#高-dpr-场景优化" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>// InstancedMesh 实现自动优化高 DPR 性能
-// 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案</p>
-<p>const pass = new FlowingLight2DPass(camera);</p>
-<p>// 多条路径在高 DPR 下仍能保持流畅
-const paths = Array.from({ length: 10 }, (_, i) =&gt; ({
-points: [
-new THREE.Vector2(0.1, 0.1 + i * 0.08),
-new THREE.Vector2(0.9, 0.1 + i * 0.08),
-],
-totalLength: 0.8,
-color: new THREE.Color(Math.random() * 0xffffff),
-duration: 2000 + i * 100,
-delay: i * 200,
-lineWidth: 0.01,
-}));</p>
-<p>pass.setLines(paths);</p>
+<pre><code class="typescript"><span class="hl-8">// InstancedMesh 实现自动优化高 DPR 性能</span><br/><span class="hl-8">// 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</span><span class="hl-1">(</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 多条路径在高 DPR 下仍能保持流畅</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">paths</span><span class="hl-1"> = </span><span class="hl-6">Array</span><span class="hl-1">.</span><span class="hl-5">from</span><span class="hl-1">({ </span><span class="hl-6">length:</span><span class="hl-1"> </span><span class="hl-11">10</span><span class="hl-1"> }, (</span><span class="hl-6">_</span><span class="hl-1">, </span><span class="hl-6">i</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> ({</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">0.08</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">0.08</span><span class="hl-1">),</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">() * </span><span class="hl-11">0xffffff</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">100</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">delay:</span><span class="hl-1"> </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">200</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">}));</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">(</span><span class="hl-6">paths</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
 <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <ul>
 <li><strong>光带不出现</strong>: 检查 <code>color</code> 和 <code>opacity</code>,确保非全透明;验证 <code>points</code> 至少 2 个;确认坐标在 [0, 1] 范围内。</li>