UNPKG

@realsee/five

Version:

Realsee Renderer SDK

115 lines (102 loc) • 36.6 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/mode | 如视 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/mode</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="mode-模式" class="tsd-anchor-link">Mode (模式)<a href="#mode-模式" 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 支持多种交互模式,包括全景漫游、模型浏览、VR/XR 等,适用于不同的看房场景。</li> <li><strong>Schema</strong>: 字符串枚举类型,定义了 6 种交互模式。</li> <li><strong>Concepts</strong>: Panorama, Mapview, Floorplan, Topview, Model, VR/XR。</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> <blockquote> <p><strong>Definition</strong>: <a href="../../five/application/mode.d.ts">Mode</a>, <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p> </blockquote> <p><strong>Mode</strong> 类型定义如下:</p> <pre><code class="ts"><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">Mode</span><span class="hl-1"> =</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;Panorama&quot;</span><span class="hl-1"> </span><span class="hl-8">// 全景图游走模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;Mapview&quot;</span><span class="hl-1"> </span><span class="hl-8">// 模型地图模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;Floorplan&quot;</span><span class="hl-1"> </span><span class="hl-8">// 模型户型图模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;Topview&quot;</span><span class="hl-1"> </span><span class="hl-8">// 模型平面图模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;Model&quot;</span><span class="hl-1"> </span><span class="hl-8">// 模型游走模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;VRPanorama&quot;</span><span class="hl-1"> </span><span class="hl-8">// Cardboard VR 眼镜模式</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;XRPanorama&quot;</span><span class="hl-1"> </span><span class="hl-8">// WebXR 虚拟现实 VR 眼镜模式</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> <ul> <li><strong>Panorama (全景漫游)</strong>: 适用于以观察点为中心进行全景图浏览的场景。使用透视相机,位于某个观察点绕自身旋转。常用来展示室内全景照片。 <ul> <li>交互:鼠标拖拽 / Pan手势旋转视角;滚轮 / Pinch手势缩放视场角;点击 / Tap手势切换全景点。</li> </ul> </li> <li><strong>Mapview (模型地图)</strong>: 适用于比较大的模型场景。交互类似地图软件。使用透视相机,上帝视角鸟瞰。 <ul> <li>交互:左键拖拽 / 单指Pan旋转视角;右键拖拽 / 双指Pan平移相机;滚轮 / Pinch前进后退;点击 / Tap切换到最近全景点。</li> </ul> </li> <li><strong>Floorplan (模型户型)</strong>: 适用于从四周观察模型的场景。使用透视相机围绕模型,并观察模型中心。 <ul> <li>交互:鼠标拖拽 / Pan手势旋转视角;滚轮 / Pinch手势缩放视场角;点击 / Tap切换到最近全景点。</li> </ul> </li> <li><strong>Topview (模型平面)</strong>: 适用于查看户型结构。使用正交相机,默认从顶部垂直向下观察模型。 <ul> <li>交互:鼠标拖拽 / Pan手势平移相机;滚轮 / Pinch手势缩放画面;点击 / Tap切换到最近全景点。</li> </ul> </li> <li><strong>Model (模型漫游)</strong>: 适用于第一人称在场景中自由游览。交互同 Panorama,但不限制相机只能在观察点位置。 <ul> <li>交互:鼠标拖拽 / Pan手势旋转视角;滚轮 / Pinch手势缩放视场角;点击 / Tap移动到指定位置。</li> </ul> </li> <li><strong>VRPanorama / XRPanorama</strong>: 适配 VR 设备(如 Google Cardboard, Apple Vision Pro 等)的沉浸式模式。 <ul> <li>交互:配合设备手柄或头部追踪,基本交互逻辑同 Panorama。</li> </ul> </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> <p>初始化 <code>new Five()</code> 时,可以通过配置参数对各个模式进行个性化定制。</p> <h3 id="panorama-全景漫游" class="tsd-anchor-link">Panorama (全景漫游)<a href="#panorama-全景漫游" 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="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">PanoramaConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 默认相机俯仰角 (Default: 0) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLatitude</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">/** 默认垂直 FOV (Default: 90) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultFov</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">/** 最大垂直 FOV (Default: 120) */</span><br/><span class="hl-1"> </span><span class="hl-6">maxFov</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">/** 最小垂直 FOV (Default: 20) */</span><br/><span class="hl-1"> </span><span class="hl-6">minFov</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-6">maxLatitude</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | ((</span><span class="hl-6">fov</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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-6">minLatitude</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | ((</span><span class="hl-6">fov</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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">/** 点位间移动速度 (m/s) (Default: 3.6) */</span><br/><span class="hl-1"> </span><span class="hl-6">moveSpeed</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-6">maxAccessibleDistance</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-6">panoTapTriggerRadius</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">/** 航拍点最小高度 (Default: 5) */</span><br/><span class="hl-1"> </span><span class="hl-6">aerialObserverMinHeight</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">/** 全景进入渐变时长 (s) */</span><br/><span class="hl-1"> </span><span class="hl-6">tileAppearDuration</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-6">tileMaxRequest</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-8"> * 地面观察点标识自定义创建器</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">observer</span><span class="hl-8"> - 观察点数据</span><br/><span class="hl-8"> * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">options</span><span class="hl-8"> - 配置项,如航拍点最小高度</span><br/><span class="hl-8"> * </span><span class="hl-3">@returns</span><span class="hl-8"> PanoCircleMeshInterface 实例 (如 PanoCircleMesh, PanoCircleMeshSolid)</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-5">panoCircleMeshCreator</span><span class="hl-1">?: (</span><br/><span class="hl-1"> </span><span class="hl-6">observer</span><span class="hl-1">: </span><span class="hl-7">WorkObserver</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">options</span><span class="hl-1">: { </span><span class="hl-6">aerialObserverMinHeight</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">=&gt;</span><span class="hl-1"> </span><span class="hl-7">PanoCircleMeshInterface</span><span class="hl-1">;</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h3 id="mapview-模型地图" class="tsd-anchor-link">Mapview (模型地图)<a href="#mapview-模型地图" 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="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">MapviewConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 默认水平角 (Default: Math.PI / 4) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLongitude</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">/** 默认俯仰角 (Default: Math.PI / 4) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLatitude</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">/** 默认相机距离 (Default: 150) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultDistance</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">/** 相机类型: &#39;perspective&#39; | &#39;orthographic&#39; | &#39;auto&#39; (Default: &#39;auto&#39;) */</span><br/><span class="hl-1"> </span><span class="hl-6">cameraType</span><span class="hl-1">?: </span><span class="hl-9">&quot;perspective&quot;</span><span class="hl-1"> | </span><span class="hl-9">&quot;orthographic&quot;</span><span class="hl-1"> | </span><span class="hl-9">&quot;auto&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">cameraFence</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Box3</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Sphere</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h3 id="floorplan-模型户型" class="tsd-anchor-link">Floorplan (模型户型)<a href="#floorplan-模型户型" 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="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FloorplanConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 默认水平角 (Default: Math.PI / 4) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLongitude</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">/** 默认俯仰角 (Default: Math.PI / 4) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLatitude</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">/** 默认垂直 FOV (Default: 80) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultFov</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h3 id="topview-模型平面" class="tsd-anchor-link">Topview (模型平面)<a href="#topview-模型平面" 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="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">TopviewConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 默认水平角 (Default: 0) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLongitude</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">/** 默认俯仰角 (Default: Math.PI / 2) */</span><br/><span class="hl-1"> </span><span class="hl-6">defaultLatitude</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h3 id="model-模型漫游" class="tsd-anchor-link">Model (模型漫游)<a href="#model-模型漫游" 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>继承自 Panorama 配置,支持 FOV、俯仰角限制及移动速度等参数。</p> <pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">ModelConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">moveSpeed</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-6">defaultFov</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">// ... 同 Panorama 基础配置</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h3 id="vrpanorama-xrpanorama-vr-模式" class="tsd-anchor-link">VRPanorama / XRPanorama (VR 模式)<a href="#vrpanorama-xrpanorama-vr-模式" 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>继承自 Panorama 配置,但移除了俯仰角限制(<code>maxLatitude</code>, <code>minLatitude</code>),因为 VR 模式下视角由设备姿态控制。</p> <pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">VRPanoramaConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// ... 同 Panorama 基础配置</span><br/><span class="hl-1"> </span><span class="hl-8">// 移除: maxLatitude, minLatitude</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">XRPanoramaConfig</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// ... 同 Panorama 基础配置</span><br/><span class="hl-1"> </span><span class="hl-8">// 移除: maxLatitude, minLatitude</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <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>使用 <code>setState</code> 切换模式:</p> <pre><code class="ts"><span class="hl-8">// 切换到模型地图模式</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</span><span class="hl-1">({ </span><span class="hl-6">mode:</span><span class="hl-1"> </span><span class="hl-9">&#39;Mapview&#39;</span><span class="hl-1"> });</span> </code><button type="button">Copy</button></pre> <h3 id="初始化配置示例-initialization-configuration-example" class="tsd-anchor-link">初始化配置示例 (Initialization Configuration Example)<a href="#初始化配置示例-initialization-configuration-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>在 <code>new Five()</code> 时配置各个模式的默认参数:</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">PanoCircleMeshSolid</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/><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-8">// 全景模式配置</span><br/><span class="hl-1"> </span><span class="hl-6">panorama:</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">minFov:</span><span class="hl-1"> </span><span class="hl-11">40</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">maxFov:</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-8">// 调整移动速度</span><br/><span class="hl-1"> </span><span class="hl-6">moveSpeed:</span><span class="hl-1"> </span><span class="hl-11">5.0</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">panoCircleMeshCreator</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">observer</span><span class="hl-1">, </span><span class="hl-6">options</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">// 这里的 options 包含了 aerialObserverMinHeight 等信息</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">PanoCircleMeshSolid</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-11">0x3366ff</span><span class="hl-1">, </span><span class="hl-8">// 自定义颜色</span><br/><span class="hl-1"> </span><span class="hl-6">scale:</span><span class="hl-1"> </span><span class="hl-11">1.2</span><span class="hl-1"> </span><span class="hl-8">// 自定义大小</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><span class="hl-8">// 模型地图配置</span><br/><span class="hl-1"> </span><span class="hl-6">mapview:</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">defaultLatitude:</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">3</span><span class="hl-1">, </span><span class="hl-8">// 60度俯视</span><br/><span class="hl-1"> </span><span class="hl-6">defaultDistance:</span><span class="hl-1"> </span><span class="hl-11">200</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-8">// 模型漫游配置</span><br/><span class="hl-1"> </span><span class="hl-6">model:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">moveSpeed:</span><span class="hl-1"> </span><span class="hl-11">10.0</span><span class="hl-1"> </span><span class="hl-8">// 模型模式下移动更快</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="动态修改配置-update-configuration" class="tsd-anchor-link">动态修改配置 (Update Configuration)<a href="#动态修改配置-update-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></h3> <p>初始化后,可以使用 <code>five.updateConfiguration()</code> 动态修改各模式的配置参数,无需重新实例化。</p> <pre><code class="typescript"><span class="hl-8">// 动态修改全景模式的移动速度和最大 FOV</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">updateConfiguration</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">panorama:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">moveSpeed:</span><span class="hl-1"> </span><span class="hl-11">10.0</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">maxFov:</span><span class="hl-1"> </span><span class="hl-11">140</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">updateConfiguration</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">mapview:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">defaultDistance:</span><span class="hl-1"> </span><span class="hl-11">300</span><br/><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>changeMode</code> 精准控制切换过程,并监听完成时机:</p> <pre><code class="ts"><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">Mode</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/><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/><br/><span class="hl-8">// 定义一个切换模式的函数</span><br/><span class="hl-3">async</span><span class="hl-1"> </span><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">switchMode</span><span class="hl-1">(</span><span class="hl-6">targetMode</span><span class="hl-1">: </span><span class="hl-7">Mode</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-10">try</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// changeMode 返回 Promise,resolve 时表示切换动画结束</span><br/><span class="hl-1"> </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-6">targetMode</span><span class="hl-1">, </span><span class="hl-3">undefined</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">1000</span><span class="hl-1"> </span><span class="hl-8">// 动画时长 1000ms</span><br/><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">`成功切换到 </span><span class="hl-3">${</span><span class="hl-6">targetMode</span><span class="hl-3">}</span><span class="hl-9"> 模式`</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-10">catch</span><span class="hl-1"> (</span><span class="hl-6">error</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">error</span><span class="hl-1">(</span><span class="hl-9">`切换到 </span><span class="hl-3">${</span><span class="hl-6">targetMode</span><span class="hl-3">}</span><span class="hl-9"> 失败`</span><span class="hl-1">, </span><span class="hl-6">error</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">document</span><span class="hl-1">.</span><span class="hl-5">querySelector</span><span class="hl-1">(</span><span class="hl-9">&#39;#btn-map&#39;</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-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">switchMode</span><span class="hl-1">(</span><span class="hl-9">&#39;Mapview&#39;</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" 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> <ol> <li><strong>相机类型差异</strong>:<code>Topview</code> 模式使用的是正交相机 (OrthographicCamera),而其他模式使用的是透视相机 (PerspectiveCamera)。在进行自定义渲染或计算时需注意投影矩阵的差异。</li> <li><strong>切换动画</strong>:<code>setState</code> 触发的切换动画是自动规划的,而 <code>changeMode</code> 允许更细粒度的控制。如果需要精确控制动画时长或回调,请使用 <code>changeMode</code>。</li> <li><strong>全景加载</strong>:<code>Panorama</code> 模式下会自动使用瓦片(tile)方式加载全景图以平衡效率和清晰度,而其他模式(如 <code>Mapview</code>)主要展示模型几何。</li> </ol> <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>: 了解 Mode 在 State 中的位置及其他状态属性。</li> <li><a href="features_gesture.html">Gesture - 手势</a>: 了解不同模式下的手势交互逻辑。</li> <li><a href="features_event.html">Event - 事件</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">视角</span><span class="hl-1">, </span><span class="hl-2">mode</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">, </span><span class="hl-2">interaction</span><span class="hl-1">, </span><span class="hl-2">VR</span><span class="hl-1">, </span><span class="hl-2">panorama</span><span class="hl-1">, </span><span class="hl-2">floorplan</span><span class="hl-1">, </span><span class="hl-2">mapview</span><span class="hl-1">, </span><span class="hl-2">topview</span><span class="hl-1">, </span><span class="hl-2">model</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="#mode-模式"><span>Mode (模式)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#panorama-全景漫游"><span>Panorama (全景漫游)</span></a></li><li><a href="#mapview-模型地图"><span>Mapview (模型地图)</span></a></li><li><a href="#floorplan-模型户型"><span>Floorplan (模型户型)</span></a></li><li><a href="#topview-模型平面"><span>Topview (模型平面)</span></a></li><li><a href="#model-模型漫游"><span>Model (模型漫游)</span></a></li><li><a href="#vrpanorama-xrpanorama-vr-模式"><span>VR<wbr/>Panorama / <wbr/>XR<wbr/>Panorama (<wbr/>VR 模式)</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="#初始化配置示例-initialization-configuration-example"><span>初始化配置示例 (<wbr/>Initialization <wbr/>Configuration <wbr/>Example)</span></a></li><li><a href="#动态修改配置-update-configuration"><span>动态修改配置 (<wbr/>Update <wbr/>Configuration)</span></a></li><li><a href="#进阶用法-advanced-usage"><span>进阶用法 (<wbr/>Advanced <wbr/>Usage)</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</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>