UNPKG

@realsee/five

Version:

Realsee Renderer SDK

174 lines (162 loc) • 32.2 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/camera-animation | 如视 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/camera-animation</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="相机动画-camera-animation" class="tsd-anchor-link">相机动画 (Camera Animation)<a href="#相机动画-camera-animation" 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>State</code> (状态), <code>MovePanoOptions</code> (移动参数)。</li> <li><strong>Concepts</strong>: Pose (位姿), Animation Loop, Easing (缓动), Fly/Fade Effect。</li> <li><strong>Configuration</strong>: <code>modeChangeDuration</code>, <code>movePanoOptions</code>。</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="movepanooptions" class="tsd-anchor-link">MovePanoOptions<a href="#movepanooptions" 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/types/movePanoOptions.d.ts">MovePanoOptions</a></p> </blockquote> <p>点位移动参数配置。</p> <pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">MovePanoOptions</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">Partial</span><span class="hl-1">&lt;</span><span class="hl-7">Omit</span><span class="hl-1">&lt;</span><span class="hl-7">State</span><span class="hl-1">, </span><span class="hl-9">&quot;offset&quot;</span><span class="hl-1"> | </span><span class="hl-9">&#39;distance&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mode&#39;</span><span class="hl-1">&gt;&gt; {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 动画效果: &#39;fly&#39; | &#39;fade&#39; | &#39;instant&#39; ... */</span><br/><span class="hl-1"> </span><span class="hl-6">effect</span><span class="hl-1">?: </span><span class="hl-7">MovePanoEffect</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">effectEasing</span><span class="hl-1">?: (</span><span class="hl-6">progress</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-8"> * 运动耗时 (ms)</span><br/><span class="hl-8"> * - number: 固定时长</span><br/><span class="hl-8"> * - function: (distance, speed) =&gt; number 根据距离动态计算</span><br/><span class="hl-8"> */</span><br/><span class="hl-1"> </span><span class="hl-6">duration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | ((</span><span class="hl-6">distance</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">speed</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><span class="hl-7">string</span><span class="hl-1"> | </span><span class="hl-7">null</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">moveStartCallback</span><span class="hl-1">?: (</span><span class="hl-6">toState</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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">/** 运动结束回调 */</span><br/><span class="hl-1"> </span><span class="hl-5">moveEndCallback</span><span class="hl-1">?: (</span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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">/** 运动被取消回调 */</span><br/><span class="hl-1"> </span><span class="hl-5">moveCancelCallback</span><span class="hl-1">?: () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </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> <h3 id="movepanoeffect" class="tsd-anchor-link">MovePanoEffect<a href="#movepanoeffect" 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">type</span><span class="hl-1"> </span><span class="hl-7">MovePanoEffect</span><span class="hl-1"> =</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;fly&quot;</span><span class="hl-1"> </span><span class="hl-8">// 通过相机移动方式变化 (默认)</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;instant&quot;</span><span class="hl-1"> </span><span class="hl-8">// 直接变化 (无动画)</span><br/><span class="hl-1"> | </span><span class="hl-9">&quot;fade&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> </code><button type="button">Copy</button></pre> <h2 id="core-methods-核心方法" class="tsd-anchor-link">Core Methods (核心方法)<a href="#core-methods-核心方法" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <p>Five 提供了多种层级的 API 来控制相机动画。</p> <h3 id="1-setstate" class="tsd-anchor-link">1. setState<a href="#1-setstate" 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>longitude</code> / <code>latitude</code> (旋转) 或 <code>fov</code> (缩放) 来产生动画。</p> <pre><code class="typescript"><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">state</span><span class="hl-1">: </span><span class="hl-6">Partial</span><span class="hl-1">&lt;</span><span class="hl-6">State</span><span class="hl-1">&gt;, </span><span class="hl-6">immediately</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><span class="hl-1">): </span><span class="hl-3">void</span> </code><button type="button">Copy</button></pre> <ul> <li><code>state</code>: 目标状态 (包含 mode, panoIndex, longitude, latitude, fov 等)。</li> <li><code>immediately</code>: 是否立即跳转 (无动画)。默认为 <code>false</code> (有动画)。</li> </ul> <h3 id="2-movetopano" class="tsd-anchor-link">2. moveToPano<a href="#2-movetopano" 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>专用于全景点位之间的切换。支持 &quot;飞行&quot; (Fly) 和 &quot;渐变&quot; (Fade) 两种效果。</p> <pre><code class="typescript"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">moveToPano</span><span class="hl-1">(</span><span class="hl-6">panoIndex</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">, </span><span class="hl-6">options</span><span class="hl-1">?: </span><span class="hl-6">MovePanoOptions</span><span class="hl-1">): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span> </code><button type="button">Copy</button></pre> <ul> <li><code>options.effect</code>: 切换效果。<code>'fly'</code> (空间飞行) 或 <code>'fade'</code> (淡入淡出)。</li> <li><code>options.duration</code>: 动画时长 (ms)。</li> <li><code>options.moveEndCallback</code>: 动画结束回调。</li> </ul> <h3 id="3-changemode" class="tsd-anchor-link">3. changeMode<a href="#3-changemode" 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">changeMode</span><span class="hl-1">(</span><span class="hl-6">mode</span><span class="hl-1">: </span><span class="hl-6">Mode</span><span class="hl-1">, </span><span class="hl-6">options</span><span class="hl-1">?, </span><span class="hl-6">animationOptions</span><span class="hl-1">?): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span> </code><button type="button">Copy</button></pre> <h3 id="4-updatecamera" class="tsd-anchor-link">4. updateCamera<a href="#4-updatecamera" 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>在不切换全景点位的情况下,将相机平滑动画到目标位姿。适用于&quot;定点环顾&quot;或&quot;聚焦某个方向&quot;等场景。</p> <pre><code class="typescript"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">updateCamera</span><span class="hl-1">(</span><span class="hl-6">pose</span><span class="hl-1">: </span><span class="hl-6">Partial</span><span class="hl-1">&lt;</span><span class="hl-6">Pose</span><span class="hl-1">&gt;, </span><span class="hl-6">duration</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">, </span><span class="hl-6">userAction</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><span class="hl-1">): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span> </code><button type="button">Copy</button></pre> <ul> <li><code>pose</code>: 目标位姿 (longitude, latitude, fov, offset, distance 等)。</li> <li><code>duration</code>: 动画时长 (ms)。</li> <li><code>userAction</code>: 是否标记为用户触发。</li> <li><strong>返回</strong>: <code>Promise&lt;void&gt;</code>,动画完成时 resolve,被打断时 reject。</li> </ul> <blockquote> <p>与 <code>setState</code> 的区别:<code>updateCamera</code> 返回 Promise,可以精确等待动画结束;<code>setState</code> 是 fire-and-forget 风格。</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> <h3 id="pose-位姿" class="tsd-anchor-link">Pose (位姿)<a href="#pose-位姿" 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><strong>Longitude (经度)</strong>: 水平旋转角度 (0 - 2π)。</li> <li><strong>Latitude (纬度)</strong>: 垂直旋转角度 (-π/2 - π/2)。</li> <li><strong>FOV (视场角)</strong>: 相机可视范围角度。</li> </ul> <h3 id="animation-effects-动画效果" class="tsd-anchor-link">Animation Effects (动画效果)<a href="#animation-effects-动画效果" 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>Linear / Easing</strong>: 大多数 <code>setState</code> 产生的旋转和缩放动画使用平滑的缓动函数 (Ease-in-out)。</li> <li><strong>Fly (飞行)</strong>: 模拟真实空间中的移动,相机位置会发生物理位移。适用于 <code>Panorama</code> 模式下的点位切换。</li> <li><strong>Fade (渐变)</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> <h3 id="global-configuration-全局配置" class="tsd-anchor-link">Global Configuration (全局配置)<a href="#global-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>new Five(config)</code> 初始化时可以设置全局动画参数:</p> <table> <thead> <tr> <th style="text-align:left">Parameter</th> <th style="text-align:left">Type</th> <th style="text-align:left">Default</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <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">模态切换 (如 Panorama -&gt; Mapview) 的默认时长 (ms)。</td> </tr> </tbody> </table> <h3 id="movepanooptions-configuration-移动参数" class="tsd-anchor-link">MovePanoOptions Configuration (移动参数)<a href="#movepanooptions-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.moveToPano(index, options)</code> 时使用的配置参数:</p> <table> <thead> <tr> <th style="text-align:left">Parameter</th> <th style="text-align:left">Type</th> <th style="text-align:left">Default</th> <th style="text-align:left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align:left"><code>effect</code></td> <td style="text-align:left"><code>MovePanoEffect</code></td> <td style="text-align:left"><code>'fly'</code></td> <td style="text-align:left">动画效果。<br><code>'fly'</code>: 空间移动(模拟行走);<br><code>'fade'</code>: 淡入淡出(保持位置不变);<br><code>'instant'</code>: 瞬间跳转。</td> </tr> <tr> <td style="text-align:left"><code>duration</code></td> <td style="text-align:left"><code>number</code> | <code>Function</code></td> <td style="text-align:left">-</td> <td style="text-align:left">动画时长 (ms)。若不传,则根据距离和速度自动计算。</td> </tr> <tr> <td style="text-align:left"><code>effectEasing</code></td> <td style="text-align:left"><code>Function</code></td> <td style="text-align:left">-</td> <td style="text-align:left">自定义过渡效果的缓动函数。</td> </tr> <tr> <td style="text-align:left"><code>moveEndCallback</code></td> <td style="text-align:left"><code>Function</code></td> <td style="text-align:left">-</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="1-旋转视角-rotate-camera" class="tsd-anchor-link">1. 旋转视角 (Rotate Camera)<a href="#1-旋转视角-rotate-camera" 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-8">// 旋转到水平 0 度,垂直 0 度</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</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-11">0</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">latitude:</span><span class="hl-1"> </span><span class="hl-11">0</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">setState</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-3">true</span><span class="hl-1">);</span> </code><button type="button">Copy</button></pre> <h3 id="2-切换全景点-change-pano" class="tsd-anchor-link">2. 切换全景点 (Change Pano)<a href="#2-切换全景点-change-pano" 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-8">// 飞向索引为 2 的全景点</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">moveToPano</span><span class="hl-1">(</span><span class="hl-11">2</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">effect:</span><span class="hl-1"> </span><span class="hl-9">&#39;fly&#39;</span><span class="hl-1">, </span><span class="hl-8">// 飞行效果</span><br/><span class="hl-1"> </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><span class="hl-1">, </span><span class="hl-8">// 1.5秒</span><br/><span class="hl-1"> </span><span class="hl-5">moveEndCallback</span><span class="hl-6">:</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/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="3-模态切换-change-mode" class="tsd-anchor-link">3. 模态切换 (Change Mode)<a href="#3-模态切换-change-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></h3> <p>从全景模式切换到户型图模式。</p> <pre><code class="typescript"><span class="hl-8">// 切换到 Floorplan 模式</span><br/><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-9">&#39;Floorplan&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 切换回 Panorama 模式,并指定进入时的视角</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">mode:</span><span class="hl-1"> </span><span class="hl-9">&#39;Panorama&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">panoIndex:</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">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><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="4-自动巡更-auto-tour" class="tsd-anchor-link">4. 自动巡更 (Auto Tour)<a href="#4-自动巡更-auto-tour" 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> 或 <code>moveToPano</code> 实现简单的自动导览。</p> <pre><code class="typescript"><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">startTour</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 先看天花板</span><br/><span class="hl-1"> </span><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">latitude:</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><br/><span class="hl-1"> </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-5">wait</span><span class="hl-1">(</span><span class="hl-11">2000</span><span class="hl-1">); </span><span class="hl-8">// 等待动画完成</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 移动到下一个点</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">moveToPano</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, { </span><span class="hl-6">effect:</span><span class="hl-1"> </span><span class="hl-9">&#39;fly&#39;</span><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 切换到模型鸟瞰</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-9">&#39;Mapview&#39;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">wait</span><span class="hl-1">(</span><span class="hl-6">ms</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-10">return</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-7">Promise</span><span class="hl-1">(</span><span class="hl-6">resolve</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-5">setTimeout</span><span class="hl-1">(</span><span class="hl-6">resolve</span><span class="hl-1">, </span><span class="hl-6">ms</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>setState</code>,这可能会打断当前动画或导致状态突变。建议使用 <code>Promise</code> 或回调等待动画结束。</li> <li><strong>相机位姿</strong>: 确保传入的 <code>longitude</code> / <code>latitude</code> 符合 Five 的坐标系定义 (Y-up, 右手系)。</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_five.html">Five</a>: Five 核心类及 <code>setState</code> 方法。</li> <li><a href="features_mode.html">Mode</a>: 各种交互模式说明。</li> <li><a href="features_state.html">State</a>: 状态对象的完整定义。</li> <li><a href="features_move-pano-effect.html">Move Pano Effect</a>: 全景点位切换的过渡效果配置。</li> <li><a href="features_coordinate-system.html">Coordinate System</a>: 坐标系定义,理解 longitude/latitude 的含义。</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">camera-animation</span><span class="hl-1">, </span><span class="hl-2">pose</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">, </span><span class="hl-2">auto-tour</span><span class="hl-1">, </span><span class="hl-2">fly-through</span><span class="hl-1">, </span><span class="hl-2">rotate</span><span class="hl-1">, </span><span class="hl-2">zoom</span><span class="hl-1">, </span><span class="hl-2">transition</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="#相机动画-camera-animation"><span>相机动画 (<wbr/>Camera <wbr/>Animation)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#movepanooptions"><span>Move<wbr/>Pano<wbr/>Options</span></a></li><li><a href="#movepanoeffect"><span>Move<wbr/>Pano<wbr/>Effect</span></a></li></ul></li><li><a href="#core-methods-核心方法"><span>Core <wbr/>Methods (核心方法)</span></a></li><li><ul><li><a href="#1-setstate"><span>1. set<wbr/>State</span></a></li><li><a href="#2-movetopano"><span>2. move<wbr/>To<wbr/>Pano</span></a></li><li><a href="#3-changemode"><span>3. change<wbr/>Mode</span></a></li><li><a href="#4-updatecamera"><span>4. update<wbr/>Camera</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#pose-位姿"><span>Pose (位姿)</span></a></li><li><a href="#animation-effects-动画效果"><span>Animation <wbr/>Effects (动画效果)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#global-configuration-全局配置"><span>Global <wbr/>Configuration (全局配置)</span></a></li><li><a href="#movepanooptions-configuration-移动参数"><span>Move<wbr/>Pano<wbr/>Options <wbr/>Configuration (移动参数)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-旋转视角-rotate-camera"><span>1. 旋转视角 (<wbr/>Rotate <wbr/>Camera)</span></a></li><li><a href="#2-切换全景点-change-pano"><span>2. 切换全景点 (<wbr/>Change <wbr/>Pano)</span></a></li><li><a href="#3-模态切换-change-mode"><span>3. 模态切换 (<wbr/>Change <wbr/>Mode)</span></a></li><li><a href="#4-自动巡更-auto-tour"><span>4. 自动巡更 (<wbr/>Auto <wbr/>Tour)</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>