全景切换效果 (Move Pano Effect)

• Summary: 介绍 moveToPano 方法中 effect 和 effectEasing 参数的作用及使用方式，用于控制全景点位切换时的视觉过渡效果。
• Schema: MovePanoEffect (枚举字符串), MovePanoOptions (接口).
• Concepts: Effect Modes (切换模式), Easing Function (缓动函数), Blend Ratio (混合比例).
• Configuration: moveToPano 的 options 参数.
• Examples: 基础切换、自定义缓动函数.

Schema

MovePanoEffect

Definition: MovePanoEffect

effect 参数定义了全景切换的动画模式。

type MovePanoEffect =
  | "fly"      // 飞行效果 (默认)：模拟相机在空间中的移动
  | "instant"  // 瞬间切换：无动画，直接跳变
  | "fade"     // 淡入淡出：原场景渐隐，新场景渐现 (位置保持不变)
  | "montage"  // 蒙太奇：通过黑屏过渡 (渐变穿插到黑屏再亮起)
  | "spread"   // 扩散：新场景从中心向四周扩散
  | "zoomin"   // 放大：新场景从小放大覆盖
  | "zoomout"  // 缩小：原场景缩小消失
  | "model";   // 模型过渡：切换过程中展示 3D 模型结构
Copy

effectEasing

effectEasing 是一个函数，用于控制前后全景图的混合进度。

// 输入 0-1 的进度值，返回 0-1 的混合比例
type EffectEasing = (progress: number) => number;
Copy

• 输入 (Input): progress (0 到 1)，表示动画的时间进度。
• 输出 (Output): 混合比例 (0 到 1)。
  • 0: 完全显示前一个全景图。
  • 1: 完全显示后一个全景图。
  • 0.5: 两个全景图各显示 50%。

Concepts

Effect Modes (切换模式)

• Fly (飞行): 最常用的模式。相机在三维空间中真实移动，给用户强烈的空间位置感。适用于相邻或视线通透的点位切换。
• Fade (渐变): 保持相机位置不变，仅改变图像透明度。适用于距离较远、不通视或空间关系不明确的点位切换，避免产生"穿墙"的违和感。
• Model (模型): 在切换过程中淡入模型的线框或白模，强调空间结构。

Easing Function (缓动函数)

默认情况下，混合比例与时间进度是线性的 (y = x)。通过自定义 effectEasing，可以实现非线性的混合效果。例如：

• 快速切入: 开始时混合很快，后面变慢。
• 延迟切入: 开始时保持原图较长时间，最后快速切换到新图。
• 特殊场景: 如“地面-天空”切换，可能希望在特定的时间点才开始显示新图。

Examples

1. 基础用法 (Basic Usage)

使用不同的 effect 进行切换。

// 1. 飞行模式 (默认)
five.moveToPano(1, {
  effect: 'fly',
  duration: 1500
});

// 2. 瞬间切换 (无动画)
five.moveToPano(2, {
  effect: 'instant'
});

// 3. 淡入淡出 (适用于远距离切换)
five.moveToPano(10, {
  effect: 'fade',
  duration: 1000
});
Copy

2. 自定义缓动 (Custom Easing)

使用 effectEasing 控制混合节奏。

// 示例：Ease-In-Quad (先慢后快)
function easeInQuad(x: number): number {
  return x * x;
}

five.moveToPano(5, {
  effect: 'fly',
  duration: 2000,
  // 自定义混合曲线
  effectEasing: easeInQuad
});
Copy

3. 高级缓动控制 (Advanced Easing)

在某些特殊场景（如从地面点切换到航拍点），我们可能希望前 80% 的时间都显示地面点，最后 20% 才快速过渡到航拍图。

five.moveToPano(aerialPanoIndex, {
  effect: 'fly',
  duration: 3000,
  effectEasing: (progress) => {
    // 0 - 0.8 期间返回 0 (显示原图)
    // 0.8 - 1.0 期间线性过渡到 1
    if (progress < 0.8) return 0;
    return (progress - 0.8) / 0.2;
  }
});
Copy

Configuration

moveToPano 的第二个参数 options 支持以下配置：

参数	类型	说明	默认值
effect	MovePanoEffect	切换效果模式	'fly'
effectEasing	(p: number) => number	图片混合缓动函数	p => p (线性)
duration	number	动画耗时 (ms)	根据距离自动计算

Common Pitfalls

1. Effect 适用性: fly 效果虽然炫酷，但在穿过墙体或障碍物时可能会导致视觉上的“穿帮”。此时应优先考虑使用 fade 或 model。
2. Easing 范围: effectEasing 函数的返回值应严格控制在 0 到 1 之间。超出此范围可能会导致渲染异常（如过曝或反色）。
3. Duration: 如果 duration 设置为 0，无论 effect 是什么，效果都等同于 instant。

Related

• Camera Animation: 更多关于相机控制的说明。
• Five: Five 实例及 API。

---

tags: [全景切换, 走点效果, 淡入淡出, 飞行, 过渡动画, 缓动, move-pano-effect, camera-animation, pano-switch, fly, fade, easing]
Copy