UNPKG

@realsee/five

Version:

Realsee Renderer SDK

173 lines (162 loc) • 35 kB
<!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> 接口定义;<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> <p><strong>Definition</strong>: <a href="../../five/application/five.d.ts">Five</a>, <a href="../../five/application/events.d.ts">EventTypes</a></p> </blockquote> <p>Five 实例提供了以下方法来管理事件监听:</p> <h3 id="on" class="tsd-anchor-link">on<a href="#on" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-6">name</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">callback</span><span class="hl-1">: (...</span><span class="hl-6">args</span><span class="hl-1">: </span><span class="hl-7">any</span><span class="hl-1">[]) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-3">void</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">once</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><br/><span class="hl-1">): () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-3">void</span> </code><button type="button">Copy</button></pre> <ul> <li><strong>name</strong>: 事件名称(支持的事件见 Concepts)。</li> <li><strong>callback</strong>: 事件触发时的回调函数。</li> <li><strong>once</strong>: (可选) 是否仅执行一次,默认为 <code>false</code>。</li> <li><strong>返回</strong>: 一个函数,调用该函数可取消当前监听。</li> </ul> <h3 id="once" class="tsd-anchor-link">once<a href="#once" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">once</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-6">name</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">callback</span><span class="hl-1">: (...</span><span class="hl-6">args</span><span class="hl-1">: </span><span class="hl-7">any</span><span class="hl-1">[]) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-3">void</span><br/><span class="hl-1">): () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-3">void</span> </code><button type="button">Copy</button></pre> <h3 id="off" class="tsd-anchor-link">off<a href="#off" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">off</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-6">name</span><span class="hl-1">?: </span><span class="hl-6">string</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">callback</span><span class="hl-1">?: (...</span><span class="hl-6">args</span><span class="hl-1">: </span><span class="hl-7">any</span><span class="hl-1">[]) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-3">void</span><br/><span class="hl-1">): </span><span class="hl-3">void</span> </code><button type="button">Copy</button></pre> <ul> <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> <p><code>PanoPrepareEvent</code> 额外包含以下属性:</p> <table> <thead> <tr> <th style="text-align:left">属性</th> <th style="text-align:left">类型</th> <th style="text-align:left">描述</th> </tr> </thead> <tbody> <tr> <td style="text-align:left"><code>options</code></td> <td style="text-align:left"><code>MovePanoOptions</code></td> <td style="text-align:left">点位切换时的选项(如 <code>effect</code>、<code>duration</code>、<code>longitude</code>、<code>latitude</code>、<code>fov</code> 等)。<strong>支持在回调中修改此对象</strong>,修改后的值将影响实际的切换行为。</td> </tr> <tr> <td style="text-align:left"><code>prevMode</code></td> <td style="text-align:left"><code>Mode</code></td> <td style="text-align:left">切换发生前的显示模式。</td> </tr> <tr> <td style="text-align:left"><code>prevPano</code></td> <td style="text-align:left"><code>Pano</code></td> <td style="text-align:left">切换前的点位信息。</td> </tr> <tr> <td style="text-align:left"><code>pano</code></td> <td style="text-align:left"><code>Pano</code></td> <td style="text-align:left">目标点位信息。</td> </tr> </tbody> </table> <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">// event.pano 目标点位</span><br/><span class="hl-1"> </span><span class="hl-8">// event.prevPano 切换前点位</span><br/><span class="hl-1"> </span><span class="hl-8">// event.prevMode 切换前模式</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><br/><br/><span class="hl-8">// 示例:修改 event.options 影响切换行为</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-6">options</span><span class="hl-1">.</span><span class="hl-6">effect</span><span class="hl-1"> = </span><span class="hl-9">&quot;instant&quot;</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-6">options</span><span class="hl-1">.</span><span class="hl-6">longitude</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-4">PI</span><span class="hl-1"> / </span><span class="hl-11">4</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-6">options</span><span class="hl-1">.</span><span class="hl-6">latitude</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-6">event</span><span class="hl-1">.</span><span class="hl-6">options</span><span class="hl-1">.</span><span class="hl-6">fov</span><span class="hl-1"> = </span><span class="hl-11">90</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">// 注意:直接修改 event.options 属性即可,不需要重新赋值 event.options</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> <p>监听用户的鼠标或触摸操作。</p> <ul> <li><code>gesture.tap</code>: 点击/轻触。</li> <li><code>gesture.dbltap</code>: 双击/双击轻触。</li> <li><code>gesture.press</code>: 长按。</li> <li><code>gesture.pan</code>: 平移/拖拽。</li> <li><code>gesture.pinch</code>: 缩放(双指或滚轮)。</li> <li><code>gesture.mousewheel</code>: 鼠标滚轮滚动。</li> <li><code>gesture.mousemove</code>: 鼠标移动。</li> </ul> <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> 取消本次走点。事件对象包含 <code>options</code>(可修改,影响切换行为)、<code>prevMode</code>(切换前模式)、<code>prevPano</code>(切换前点位)、<code>pano</code>(目标点位)等属性。</li> <li><code>pano.arrived</code>: 成功到达新点位(移动动画结束)。</li> <li><code>pano.moving</code>: 正在移动到新点位(动画进行中)。</li> <li><code>pano.willChange</code>: 即将发生点位变更(旧版兼容)。</li> <li><code>pano.error</code>: 点位加载或移动出错。</li> </ul> <h3 id="state-events-状态变更" class="tsd-anchor-link">State Events (状态变更)<a href="#state-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>监听 Five 内部状态(State)的变化,常用于 UI 同步或数据记录。</p> <ul> <li><code>state.change</code>: 状态发生变更(可能是用户操作或代码触发)。</li> <li><code>currentState.change</code>: 当前状态发生变更(通常指即时状态)。</li> <li><code>state.synced</code>: 状态已同步。</li> </ul> <h3 id="model-work-events-数据加载" class="tsd-anchor-link">Model &amp; Work Events (数据加载)<a href="#model-work-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>监听场景数据(Work)或模型(Model)的加载生命周期。</p> <ul> <li><code>works.load</code>: Work 数据开始加载。</li> <li><code>works.ready</code>: Work 数据加载完成且 Controller 就绪。</li> <li><code>model.load</code>: 模型开始加载。</li> <li><code>models.load</code>: 所有模型加载完成。</li> </ul> <h3 id="render-events-渲染循环" class="tsd-anchor-link">Render Events (渲染循环)<a href="#render-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>render</code>: 每一帧渲染后触发。</li> <li><code>render.prepare</code>: 每一帧渲染前触发。</li> </ul> <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">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> <p>使用 <code>once</code> 监听一次性初始化事件,使用返回值取消监听。</p> <pre><code class="typescript"><span class="hl-8">// 1. 等待首次数据加载完成</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">once</span><span class="hl-1">(</span><span class="hl-9">&quot;works.ready&quot;</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;Five is ready!&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// 执行初始化逻辑,如自动巡游</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 动态绑定与解绑</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-5">onRender</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-5">updateUI</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;render&quot;</span><span class="hl-1">, </span><span class="hl-6">onRender</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 在某个时刻取消监听(例如组件销毁时)</span><br/><span class="hl-8">// five.off(&quot;render&quot;, onRender);</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>使用 <code>five.on(&quot;error&quot;, (err) =&gt; console.error(err))</code> 捕获全局错误。</li> </ul> <h2 id="related" class="tsd-anchor-link">Related<a href="#related" 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><a href="features_state.html">State</a>: 了解 State 的结构与变更机制。</li> <li><a href="features_five.html">Five</a>: Five 核心类说明。</li> </ul> <hr> <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">事件监听</span><span class="hl-1">, </span><span class="hl-2">点击</span><span class="hl-1">, </span><span class="hl-2">拖拽</span><span class="hl-1">, </span><span class="hl-2">加载完成</span><span class="hl-1">, </span><span class="hl-2">渲染回调</span><span class="hl-1">, </span><span class="hl-2">生命周期</span><span class="hl-1">, </span><span class="hl-2">回调</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><span class="hl-3">on</span><span class="hl-1">, </span><span class="hl-3">off</span><span class="hl-1">, </span><span class="hl-2">subscribe</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="#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>