@realsee/five
Version:
Realsee Renderer SDK
111 lines (104 loc) • 21.6 kB
HTML
<html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/move-pano-effect | 如视 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/move-pano-effect</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="全景切换效果-move-pano-effect" class="tsd-anchor-link">全景切换效果 (Move Pano Effect)<a href="#全景切换效果-move-pano-effect" 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>: 介绍 <code>moveToPano</code> 方法中 <code>effect</code> 和 <code>effectEasing</code> 参数的作用及使用方式，用于控制全景点位切换时的视觉过渡效果。</li>
<li><strong>Schema</strong>: <code>MovePanoEffect</code> (枚举字符串), <code>MovePanoOptions</code> (接口).</li>
<li><strong>Concepts</strong>: Effect Modes (切换模式), Easing Function (缓动函数), Blend Ratio (混合比例).</li>
<li><strong>Configuration</strong>: <code>moveToPano</code> 的 <code>options</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="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>
<blockquote>
<p><strong>Definition</strong>: <a href="../../five/types/movePanoEffect.d.ts">MovePanoEffect</a></p>
</blockquote>
<p><code>effect</code> 参数定义了全景切换的动画模式。</p>
<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">"fly"</span><span class="hl-1"> </span><span class="hl-8">// 飞行效果 (默认)：模拟相机在空间中的移动</span><br/><span class="hl-1"> | </span><span class="hl-9">"instant"</span><span class="hl-1"> </span><span class="hl-8">// 瞬间切换：无动画，直接跳变</span><br/><span class="hl-1"> | </span><span class="hl-9">"fade"</span><span class="hl-1"> </span><span class="hl-8">// 淡入淡出：原场景渐隐，新场景渐现 (位置保持不变)</span><br/><span class="hl-1"> | </span><span class="hl-9">"montage"</span><span class="hl-1"> </span><span class="hl-8">// 蒙太奇：通过黑屏过渡 (渐变穿插到黑屏再亮起)</span><br/><span class="hl-1"> | </span><span class="hl-9">"spread"</span><span class="hl-1"> </span><span class="hl-8">// 扩散：新场景从中心向四周扩散</span><br/><span class="hl-1"> | </span><span class="hl-9">"zoomin"</span><span class="hl-1"> </span><span class="hl-8">// 放大：新场景从小放大覆盖</span><br/><span class="hl-1"> | </span><span class="hl-9">"zoomout"</span><span class="hl-1"> </span><span class="hl-8">// 缩小：原场景缩小消失</span><br/><span class="hl-1"> | </span><span class="hl-9">"model"</span><span class="hl-1">; </span><span class="hl-8">// 模型过渡：切换过程中展示 3D 模型结构</span>
</code><button type="button">Copy</button></pre>
<h3 id="effecteasing" class="tsd-anchor-link">effectEasing<a href="#effecteasing" 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>effectEasing</code> 是一个函数，用于控制前后全景图的混合进度。</p>
<pre><code class="typescript"><span class="hl-8">// 输入 0-1 的进度值，返回 0-1 的混合比例</span><br/><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">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">=></span><span class="hl-1"> </span><span class="hl-7">number</span><span class="hl-1">;</span>
</code><button type="button">Copy</button></pre>
<ul>
<li><strong>输入 (Input)</strong>: <code>progress</code> (0 到 1)，表示动画的时间进度。</li>
<li><strong>输出 (Output)</strong>: 混合比例 (0 到 1)。
<ul>
<li><code>0</code>: 完全显示前一个全景图。</li>
<li><code>1</code>: 完全显示后一个全景图。</li>
<li><code>0.5</code>: 两个全景图各显示 50%。</li>
</ul>
</li>
</ul>
<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="effect-modes-切换模式" class="tsd-anchor-link">Effect Modes (切换模式)<a href="#effect-modes-切换模式" 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>Fly (飞行)</strong>: 最常用的模式。相机在三维空间中真实移动，给用户强烈的空间位置感。适用于相邻或视线通透的点位切换。</li>
<li><strong>Fade (渐变)</strong>: 保持相机位置不变，仅改变图像透明度。适用于距离较远、不通视或空间关系不明确的点位切换，避免产生"穿墙"的违和感。</li>
<li><strong>Model (模型)</strong>: 在切换过程中淡入模型的线框或白模，强调空间结构。</li>
</ul>
<h3 id="easing-function-缓动函数" class="tsd-anchor-link">Easing Function (缓动函数)<a href="#easing-function-缓动函数" 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>y = x</code>)。通过自定义 <code>effectEasing</code>，可以实现非线性的混合效果。例如：</p>
<ul>
<li><strong>快速切入</strong>: 开始时混合很快，后面变慢。</li>
<li><strong>延迟切入</strong>: 开始时保持原图较长时间，最后快速切换到新图。</li>
<li><strong>特殊场景</strong>: 如“地面-天空”切换，可能希望在特定的时间点才开始显示新图。</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="1-基础用法-basic-usage" class="tsd-anchor-link">1. 基础用法 (Basic Usage)<a href="#1-基础用法-basic-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>effect</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">moveToPano</span><span class="hl-1">(</span><span class="hl-11">1</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">'fly'</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><br/><span class="hl-1">});</span><br/><br/><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">'instant'</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 3. 淡入淡出 (适用于远距离切换)</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">10</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">'fade'</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><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h3 id="2-自定义缓动-custom-easing" class="tsd-anchor-link">2. 自定义缓动 (Custom Easing)<a href="#2-自定义缓动-custom-easing" 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>effectEasing</code> 控制混合节奏。</p>
<pre><code class="typescript"><span class="hl-8">// 示例：Ease-In-Quad (先慢后快)</span><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">easeInQuad</span><span class="hl-1">(</span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</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-6">x</span><span class="hl-1"> * </span><span class="hl-6">x</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">moveToPano</span><span class="hl-1">(</span><span class="hl-11">5</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">'fly'</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-8">// 自定义混合曲线</span><br/><span class="hl-1"> </span><span class="hl-6">effectEasing:</span><span class="hl-1"> </span><span class="hl-6">easeInQuad</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h3 id="3-高级缓动控制-advanced-easing" class="tsd-anchor-link">3. 高级缓动控制 (Advanced Easing)<a href="#3-高级缓动控制-advanced-easing" 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>在某些特殊场景（如从地面点切换到航拍点），我们可能希望前 80% 的时间都显示地面点，最后 20% 才快速过渡到航拍图。</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">aerialPanoIndex</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">'fly'</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">3000</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">effectEasing</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">progress</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 0 - 0.8 期间返回 0 (显示原图)</span><br/><span class="hl-1"> </span><span class="hl-8">// 0.8 - 1.0 期间线性过渡到 1</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">progress</span><span class="hl-1"> < </span><span class="hl-11">0.8</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-10">return</span><span class="hl-1"> (</span><span class="hl-6">progress</span><span class="hl-1"> - </span><span class="hl-11">0.8</span><span class="hl-1">) / </span><span class="hl-11">0.2</span><span class="hl-1">;</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<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>moveToPano</code> 的第二个参数 <code>options</code> 支持以下配置：</p>
<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>effect</code></td>
<td style="text-align:left"><code>MovePanoEffect</code></td>
<td style="text-align:left">切换效果模式</td>
<td style="text-align:left"><code>'fly'</code></td>
</tr>
<tr>
<td style="text-align:left"><code>effectEasing</code></td>
<td style="text-align:left"><code>(p: number) => number</code></td>
<td style="text-align:left">图片混合缓动函数</td>
<td style="text-align:left"><code>p => p</code> (线性)</td>
</tr>
<tr>
<td style="text-align:left"><code>duration</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left">动画耗时 (ms)</td>
<td style="text-align:left">根据距离自动计算</td>
</tr>
</tbody>
</table>
<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>Effect 适用性</strong>: <code>fly</code> 效果虽然炫酷，但在穿过墙体或障碍物时可能会导致视觉上的“穿帮”。此时应优先考虑使用 <code>fade</code> 或 <code>model</code>。</li>
<li><strong>Easing 范围</strong>: <code>effectEasing</code> 函数的返回值应严格控制在 <code>0</code> 到 <code>1</code> 之间。超出此范围可能会导致渲染异常（如过曝或反色）。</li>
<li><strong>Duration</strong>: 如果 <code>duration</code> 设置为 <code>0</code>，无论 <code>effect</code> 是什么，效果都等同于 <code>instant</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_camera-animation.html">Camera Animation</a>: 更多关于相机控制的说明。</li>
<li><a href="features_five.html">Five</a>: Five 实例及 API。</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">move-pano-effect</span><span class="hl-1">, </span><span class="hl-2">camera-animation</span><span class="hl-1">, </span><span class="hl-2">pano-switch</span><span class="hl-1">, </span><span class="hl-2">fly</span><span class="hl-1">, </span><span class="hl-2">fade</span><span class="hl-1">, </span><span class="hl-2">easing</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="#全景切换效果-move-pano-effect"><span>全景切换效果 (<wbr/>Move <wbr/>Pano <wbr/>Effect)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#movepanoeffect"><span>Move<wbr/>Pano<wbr/>Effect</span></a></li><li><a href="#effecteasing"><span>effect<wbr/>Easing</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#effect-modes-切换模式"><span>Effect <wbr/>Modes (切换模式)</span></a></li><li><a href="#easing-function-缓动函数"><span>Easing <wbr/>Function (缓动函数)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-基础用法-basic-usage"><span>1. 基础用法 (<wbr/>Basic <wbr/>Usage)</span></a></li><li><a href="#2-自定义缓动-custom-easing"><span>2. 自定义缓动 (<wbr/>Custom <wbr/>Easing)</span></a></li><li><a href="#3-高级缓动控制-advanced-easing"><span>3. 高级缓动控制 (<wbr/>Advanced <wbr/>Easing)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></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>