UNPKG

@realsee/five

Version:

Realsee Renderer SDK

148 lines (142 loc) • 30.8 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/five | 如视 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/five</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="five-five-核心类" class="tsd-anchor-link">Five (Five 核心类)<a href="#five-five-核心类" 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 是 @realsee/five 的核心类,负责 3D 场景的渲染、资源加载、用户交互和状态管理。</li> <li><strong>Schema</strong>: FiveInitArgs 初始化参数接口。</li> <li><strong>Concepts</strong>: Instance Management, Rendering Loop, Resource Loading, State Sync.</li> <li><strong>Configuration</strong>: Five 初始化参数详解。</li> <li><strong>Examples</strong>: 基础初始化、加载数据、销毁实例。</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> <h3 id="fiveinitargs" class="tsd-anchor-link">FiveInitArgs<a href="#fiveinitargs" 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> <blockquote> <p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p> </blockquote> <p><code>new Five(args)</code> 的初始化参数对象。</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">/** 外部传入的渲染器 (如果传入,部分渲染配置将失效) */</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/><span class="hl-1"> </span><span class="hl-8">/**</span><br/><span class="hl-8"> * 屏幕渲染区域 { left, bottom, width, height }</span><br/><span class="hl-8"> * 必须配合外部 renderer 使用</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-6">viewport</span><span class="hl-1">?: </span><span class="hl-7">Viewport</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 背景颜色 (默认 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/><span class="hl-1"> </span><span class="hl-8">/** 背景透明度 (0-1, 默认 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/><span class="hl-1"> </span><span class="hl-8">/** 是否开启抗锯齿 (默认 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/><span class="hl-1"> </span><span class="hl-8">/** 全景图配置 (见 image-options.md) */</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/><span class="hl-1"> </span><span class="hl-8">/** 贴图配置 (见 image-options.md) */</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><span class="hl-8">/** 是否按需渲染 (默认 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/><span class="hl-1"> </span><span class="hl-8">/** 模式切换动画时长 (ms, 默认 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/><span class="hl-1"> </span><span class="hl-8">/** 是否支持滚轮缩放 (默认 true) */</span><br/><span class="hl-1"> </span><span class="hl-6">enableWheel</span><span class="hl-1">?: </span><span class="hl-7">boolean</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">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><span class="hl-1"> </span><span class="hl-8">/** 是否显示 Powered by Realsee */</span><br/><span class="hl-1"> </span><span class="hl-6">poweredByRealsee</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> <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> <h3 id="instance-management-实例管理" class="tsd-anchor-link">Instance Management (实例管理)<a href="#instance-management-实例管理" 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 实例是整个 3D 场景的入口。</p> <ul> <li><strong>Singleton-like</strong>: 虽然支持多实例,但在同一个 DOM 容器中通常只维护一个 Five 实例。</li> <li><strong>Lifecycle</strong>: 包含 <code>appendTo</code> (挂载)、<code>load</code> (加载数据)、<code>dispose</code> (销毁) 等生命周期方法。</li> </ul> <h3 id="rendering-loop-渲染循环" class="tsd-anchor-link">Rendering Loop (渲染循环)<a href="#rendering-loop-渲染循环" 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 内部维护了一个 <code>requestAnimationFrame</code> 循环。</p> <ul> <li><strong>按需渲染</strong>: 默认开启 <code>onlyRenderIfNeeds</code>,仅在画面发生变化(如视角移动、数据加载)时才触发 WebGL 绘制,大幅降低能耗。</li> <li><strong>手动触发</strong>: 可以通过 <code>five.needsRender = true</code> 强制下一帧进行渲染。</li> </ul> <h3 id="resource-loading-资源加载" class="tsd-anchor-link">Resource Loading (资源加载)<a href="#resource-loading-资源加载" 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>load()</code> 方法加载 Work 数据。</p> <ul> <li><strong>数据解析</strong>: 自动解析 Work 数据结构,生成场景图。</li> <li><strong>预加载</strong>: 支持配置预加载策略,平衡首屏速度与流量。</li> </ul> <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#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> <table> <thead> <tr> <th style="text-align:left">参数</th> <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>imageOptions</code></td> <td style="text-align:left"><code>ImageOptions</code></td> <td style="text-align:left"><code>{}</code></td> <td style="text-align:left">图片加载策略,详见 <a href="features_image-options.html">Image Options</a></td> </tr> <tr> <td style="text-align:left"><code>textureOptions</code></td> <td style="text-align:left"><code>TextureOptions</code></td> <td style="text-align:left"><code>{}</code></td> <td style="text-align:left">贴图加载策略,同上</td> </tr> <tr> <td style="text-align:left"><code>onlyRenderIfNeeds</code></td> <td style="text-align:left"><code>boolean</code></td> <td style="text-align:left"><code>true</code></td> <td style="text-align:left">是否仅在需要时渲染,建议保持 <code>true</code></td> </tr> <tr> <td style="text-align:left"><code>antialias</code></td> <td style="text-align:left"><code>boolean</code></td> <td style="text-align:left"><code>false</code></td> <td style="text-align:left">抗锯齿,开启会增加性能消耗</td> </tr> <tr> <td style="text-align:left"><code>modeChangeDuration</code></td> <td style="text-align:left"><code>number</code></td> <td style="text-align:left"><code>1000</code></td> <td style="text-align:left">模式切换动画时长 (ms)</td> </tr> <tr> <td style="text-align:left"><code>enableWheel</code></td> <td style="text-align:left"><code>boolean</code></td> <td style="text-align:left"><code>true</code></td> <td style="text-align:left">是否支持滚轮缩放</td> </tr> </tbody> </table> <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>创建一个全屏的 Five 实例并加载数据。</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-6">parseWork</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-8">// 1. 初始化实例</span><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/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> { </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1"> }, </span><span class="hl-8">// 初始加载小图</span><br/><span class="hl-1"> </span><span class="hl-6">onlyRenderIfNeeds:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 挂载到 DOM</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&quot;app&quot;</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 3. 加载数据</span><br/><span class="hl-8">// workData 通常来自服务端 API</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><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>使用外部渲染器并指定视口区域(例如用于分屏渲染)。</p> <pre><code class="typescript"><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">&quot;three&quot;</span><span class="hl-1">;</span><br/><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">renderer</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">WebGLRenderer</span><span class="hl-1">();</span><br/><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerWidth</span><span class="hl-1">, </span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerHeight</span><span class="hl-1">);</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-6">domElement</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/><span class="hl-1"> </span><span class="hl-6">renderer:</span><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-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-11">0</span><span class="hl-1">, </span><span class="hl-6">bottom:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1"> } </span><span class="hl-8">// 仅占用左半屏</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><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>使用 <code>updateCamera</code> 或 <code>updateCameraWithKeyframes</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">updateCamera</span><span class="hl-1">(</span><br/><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">2</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><span class="hl-8">// 目标姿态</span><br/><span class="hl-1"> </span><span class="hl-11">1000</span><span class="hl-1"> </span><span class="hl-8">// 动画时长 1秒</span><br/><span class="hl-1">).</span><span class="hl-5">then</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;移动完成&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</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;移动被打断&quot;</span><span class="hl-1">);</span><br/><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">keyframes</span><span class="hl-1"> = [</span><br/><span class="hl-1"> { </span><span class="hl-6">progress:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">value:</span><span class="hl-1"> { </span><span class="hl-6">longitude:</span><span class="hl-1"> </span><span class="hl-11">0</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">progress:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">value:</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><span class="hl-6">latitude:</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-6">progress:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-6">value:</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">2</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><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">updateCameraWithKeyframes</span><span class="hl-1">(</span><span class="hl-6">keyframes</span><span class="hl-1">, </span><span class="hl-11">2000</span><span class="hl-1">).</span><span class="hl-5">then</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;关键帧动画完成&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="实例属性-instance-properties" class="tsd-anchor-link">实例属性 (Instance Properties)<a href="#实例属性-instance-properties" 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> <ul> <li><strong><code>work</code></strong>: 当前加载的 Work 数据(主 Work)。详见 <a href="features_work.html">Work</a>。</li> <li><strong><code>works</code></strong>: 当前加载的所有 Work 数据列表。详见 <a href="features_work.html">Work</a>。</li> <li><strong><code>model</code></strong>: 当前加载的 Model 数据(主 Model)。详见 <a href="features_model.html">Model</a>。</li> <li><strong><code>models</code></strong>: 当前加载的所有 Model 数据列表。详见 <a href="features_model.html">Model</a>。</li> </ul> <h3 id="实例方法-instance-methods" class="tsd-anchor-link">实例方法 (Instance Methods)<a href="#实例方法-instance-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></h3> <ul> <li><strong><code>appendTo(element: HTMLElement)</code></strong>: 将 canvas 挂载到指定 DOM 元素。</li> <li><strong><code>load(work: Work, state?: State, duration?: number)</code></strong>: 加载场景数据。详见 <a href="features_work.html">Work</a>。</li> <li><strong><code>dispose()</code></strong>: 销毁实例,释放 WebGL 上下文与内存。</li> <li><strong><code>updateCamera(pose: Partial&lt;Pose&gt;, duration: number, userAction?: boolean)</code></strong>: 移动相机(不触发点位移动)。移动相机的视角或位置,不会改变当前所在的 PanoIndex。如果动画中途被打断,Promise 会被 reject。</li> <li><strong><code>updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)</code></strong>: 通过关键帧动画移动相机。</li> <li><strong><code>refresh()</code></strong>: 强制刷新画布尺寸。通常在窗口 resize 时调用,Five 会自动监听 resize,但在某些布局变化场景下可能需要手动调用。</li> <li><strong><code>getPixels(x, y, width, height, ...)</code> / <code>getPixels(options)</code></strong>: 获取画布指定区域的像素数据。常用于截图、生成缩略图或颜色拾取。支持配置区域、像素比 (pixelRatio)、Y轴翻转 (flipY) 及是否忽略全景图 (skipPanorama) 等。</li> <li><strong><code>project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null</code></strong>: 计算三维坐标对应到屏幕的二维坐标。如果坐标在视野外或被遮挡(开启 testModel 时),返回 null。详见 <a href="features_screen-project.html">Screen Project</a>。</li> <li><strong><code>ready(args?: { tile?: boolean })</code></strong>: Promise,当 Five 状态稳定时 resolve。 <ul> <li><strong>Resolve 时机</strong>: <ol> <li><strong>状态同步</strong>:相机姿态已通过动画过渡到目标状态(<code>stateSynced</code> 为 true)。</li> <li><strong>模型加载</strong>:如果是 Floorplan/Topview/Mapview/Model 模态,需等待模型加载完成 (<code>modelScene.loaded</code>)。</li> <li><strong>瓦片加载</strong>:如果是 Panorama 模态且传入了 <code>{ tile: true }</code>,需等待当前视角的瓦片加载完成。</li> </ol> </li> </ul> </li> <li><strong><code>setState(state: Partial&lt;State&gt;, options?: ChangeStateOptions)</code></strong>: 变更当前状态(如点位、视角)。详见 <a href="features_state.html">State</a>。</li> <li><strong><code>on(event, callback)</code> / <code>off(event, callback)</code></strong>: 事件监听。详见 <a href="features_event.html">Event</a>。</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_work.html">Work</a>: Work 数据结构说明。</li> <li><a href="features_model.html">Model</a>: Model 数据结构说明。</li> <li><a href="features_state.html">State</a>: 状态管理详解。</li> <li><a href="features_event.html">Event</a>: 事件系统说明。</li> <li><a href="features_image-options.html">Image Options</a>: 图片加载配置。</li> <li><a href="features_mode.html">Mode</a>: 模态切换说明。</li> <li><a href="features_parameter.html">Parameter</a>: 其他核心参数。</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">five</span><span class="hl-1">, </span><span class="hl-2">initialization</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">instance</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">, </span><span class="hl-2">canvas</span><span class="hl-1">, </span><span class="hl-2">appendTo</span><span class="hl-1">, </span><span class="hl-2">dispose</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="#five-five-核心类"><span>Five (<wbr/>Five 核心类)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#fiveinitargs"><span>Five<wbr/>Init<wbr/>Args</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instance-management-实例管理"><span>Instance <wbr/>Management (实例管理)</span></a></li><li><a href="#rendering-loop-渲染循环"><span>Rendering <wbr/>Loop (渲染循环)</span></a></li><li><a href="#resource-loading-资源加载"><span>Resource <wbr/>Loading (资源加载)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></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="#进阶用法:自定义渲染器与视口"><span>进阶用法:自定义渲染器与视口</span></a></li><li><a href="#进阶用法:自定义相机动画"><span>进阶用法:自定义相机动画</span></a></li><li><a href="#实例属性-instance-properties"><span>实例属性 (<wbr/>Instance <wbr/>Properties)</span></a></li><li><a href="#实例方法-instance-methods"><span>实例方法 (<wbr/>Instance <wbr/>Methods)</span></a></li></ul></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>