第六章 Vue3 + Three.js 实现高质量全景图查看器：从基础到优化

效果图

全景图技术在现代 Web 应用中越来越受欢迎，无论是虚拟旅游、房产展示还是产品 360° 预览，都能为用户带来沉浸式体验。本文将详细介绍如何使用 Vue3 和 Three.js 构建一个功能完善、交互流畅的全景图查看器，并分享一些关键的优化技巧。

实现效果与核心功能

我们构建的全景图查看器具有以下特点：

• 支持多张全景图切换，满足多场景展示需求
• 流畅的鼠标拖动旋转功能，实现 360° 全方位观察
• 滚轮缩放控制，可近距离查看细节
• 加载状态提示，提升用户体验
• 响应式设计，适配不同屏幕尺寸
• 优化的场景参数，避免画面拉伸和变形

技术选型

• Vue3 ：采用 Composition API，通过<script setup>语法实现组件逻辑，代码更简洁高效
• Three.js：WebGL 的封装库，用于实现 3D 全景效果
• OrbitControls：Three.js 的控制器扩展，提供旋转、缩放等交互功能

实现步骤详解

1. 基础结构设计

首先，我们设计组件的基础结构，包括全景图渲染容器、加载提示和控制面板：

<template>
  <div class="panorama-viewer">
    <!-- 全景图渲染容器 -->
    <div ref="container" class="viewer-container"></div>

    <!-- 加载提示 -->
    <div v-if="isLoading" class="loading-indicator">加载中...</div>

    <!-- 控制面板 -->
    <div class="controls-panel">
      <div class="info">
        <p>拖动鼠标: 旋转视角</p>
        <p>滚轮: 缩放</p>
      </div>
      <div class="panorama-switch">
        <button
          :class="{ active: currentPanorama === 0 }"
          @click="switchPanorama(0)"
        >
          场景 1
        </button>
        <button
          :class="{ active: currentPanorama === 1 }"
          @click="switchPanorama(1)"
        >
          场景 2
        </button>
      </div>
    </div>
  </div>
</template>

2. 核心逻辑实现

接下来是组件的核心逻辑，我们使用 Three.js 创建 3D 场景并实现全景图效果：

<template>
  <div class="panorama-viewer">
    <!-- 全景图渲染容器 -->
    <div ref="container" class="viewer-container"></div>

    <!-- 加载提示 -->
    <div v-if="isLoading" class="loading-indicator">加载中...</div>

    <!-- 控制面板 -->
    <div class="controls-panel">
      <div class="info">
        <p>拖动鼠标: 旋转视角</p>
        <p>滚轮: 缩放</p>
      </div>
      <div class="panorama-switch">
        <button
          :class="{ active: currentPanorama === 0 }"
          @click="switchPanorama(0)"
        >
          场景 1
        </button>
        <button
          :class="{ active: currentPanorama === 1 }"
          @click="switchPanorama(1)"
        >
          场景 2
        </button>
      </div>
    </div>
  </div>
</template>

<script setup>
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { onMounted, onUnmounted, ref, watch } from 'vue';
import img1 from '@/assets/a.jpg';
import img2 from '@/assets/b.jpg';

// DOM引用
const container = ref(null);

// 状态管理
const currentPanorama = ref(0); // 当前显示的全景图索引
const isLoading = ref(true); // 加载状态
const animationId = ref(null); // 动画帧ID

// Three.js核心对象
let scene, camera, renderer;
let controls;
let sphere; // 用于展示全景图的球体
let textures = []; // 存储全景图纹理

// 全景图路径
const panoramaImages = [
  img1, // 示例全景图1
  img2, // 示例全景图2
];

/**
 * 初始化Three.js场景 - 关键调整：缩小场景视野（相机+球体参数）
 */
const initScene = () => {
  if (!container.value) return;

  // 1. 创建场景（无修改）
  scene = new THREE.Scene();

  // 2. 相机参数调整：缩小视野范围
  // 关键修改：
  // - fov从75→50：减小视场角，避免视角过广导致的"拉伸感"（数值越小，视野越窄，场景越"紧凑"）
  // - far从1000→500：缩短远裁剪面，减少无效渲染范围
  camera = new THREE.PerspectiveCamera(
    100, // 视场角：从75缩小到50，核心缩小场景的参数
    container.value.clientWidth / container.value.clientHeight, // 宽高比（保持不变）
    1, // 近裁剪面（保持不变，避免过近导致穿模）
    500 // 远裁剪面：从1000缩短到500，匹配球体尺寸
  );
  camera.position.set(40, 0, 0); // 相机仍在中心（全景图核心逻辑）

  // 3. 创建渲染器（无修改）
  renderer = new THREE.WebGLRenderer({
    antialias: true, // 抗锯齿（保持，避免画面模糊）
    alpha: true,
  });
  renderer.setSize(container.value.clientWidth, container.value.clientHeight);
  renderer.setPixelRatio(window.devicePixelRatio);
  // 清除旧画布（避免重复渲染）
  while (container.value.firstChild) {
    container.value.removeChild(container.value.firstChild);
  }
  container.value.appendChild(renderer.domElement);

  // 4. 初始化控制器（优化缩放范围，匹配缩小后的场景）
  initControls();

  // 5. 加载纹理（无修改）
  loadTextures();

  // 6. 监听窗口 resize（无修改）
  window.addEventListener('resize', onWindowResize);

  // 初始渲染（无修改）
  renderer.render(scene, camera);
};

/**
 * 初始化控制器 - 关键调整：匹配缩小后的场景，限制缩放范围
 */
const initControls = () => {
  if (!renderer || !renderer.domElement) {
    console.error('渲染器DOM元素不存在');
    return;
  }

  controls = new OrbitControls(camera, renderer.domElement);

  // 基础交互配置（保持不变）
  controls.enableZoom = true; // 允许缩放
  controls.enableRotate = true; // 允许旋转
  controls.enablePan = false; // 禁用平移（全景图不需要）
  controls.rotateSpeed = 0.5; // 旋转速度（保持，避免过快）
  controls.enableDamping = true; // 阻尼效果（保持，旋转更平滑）
  controls.dampingFactor = 0.05; // 阻尼强度（保持）
  controls.minPolarAngle = 0; // 垂直旋转下限（保持）
  controls.maxPolarAngle = Math.PI; // 垂直旋转上限（保持）

  // 关键修改：限制缩放范围，匹配缩小后的场景
  // 缩小场景后，不需要过大的缩放区间，避免缩放过小导致"空场景"
  controls.minDistance = 50; // 最小缩放距离：从默认0→50（避免太近穿模）
  controls.maxDistance = 300; // 最大缩放距离：从默认无限→200（避免太远看不到场景）

  controls.update(); // 强制更新控制器状态
  console.log('控制器初始化完成，旋转和缩放已启用（匹配缩小场景）');
};

/**
 * 加载全景图纹理（无修改）
 */
const loadTextures = () => {
  const loader = new THREE.TextureLoader();
  loader.crossOrigin = 'anonymous';

  panoramaImages.forEach((url, index) => {
    loader.load(
      url,
      (texture) => {
        texture.wrapS = THREE.ClampToEdgeWrapping; // 避免纹理边缘重复
        texture.wrapT = THREE.ClampToEdgeWrapping;
        textures[index] = texture;

        // 第一张图加载完成后初始化球体
        if (index === 0) {
          initSphere(texture);
          isLoading.value = false;
        }
      },
      (xhr) => {
        console.log(
          `全景图 ${index + 1} 加载中: ${Math.round(
            (xhr.loaded / xhr.total) * 100
          )}%`
        );
      },
      (error) => {
        console.error(`加载全景图 ${index + 1} 失败:`, error);
        isLoading.value = false;
      }
    );
  });
};

/**
 * 初始化全景球体 - 关键调整：缩小球体尺寸（核心"场景缩小"逻辑）
 */
const initSphere = (texture) => {
  // 关键修改：球体半径从500→200（直接缩小球体尺寸，场景自然缩小）
  // 分段数60/40保持不变，确保球体表面平滑，避免纹理拉伸
  const geometry = new THREE.SphereGeometry(200, 60, 40);

  // 反转球体UV：使纹理显示在球体内侧（全景图核心逻辑，无修改）
  geometry.scale(-1, 1, 1);

  // 材质配置（修复原代码注释错误，DoubleSide→FrontSide，避免性能浪费）
  const material = new THREE.MeshBasicMaterial({
    map: texture,
    side: THREE.FrontSide, // 因球体已反转，FrontSide即可显示内侧纹理（比DoubleSide更高效）
  });

  // 创建球体并添加到场景（无修改）
  sphere = new THREE.Mesh(geometry, material);
  scene.add(sphere);
};

/**
 * 切换全景图（无修改）
 */
const switchPanorama = (index) => {
  if (
    index < 0 ||
    index >= textures.length ||
    !textures[index] ||
    index === currentPanorama.value
  )
    return;

  isLoading.value = true;
  currentPanorama.value = index;

  if (sphere && sphere.material) {
    sphere.material.map = textures[index];
    sphere.material.needsUpdate = true; // 强制Three.js更新材质
    setTimeout(() => {
      isLoading.value = false;
    }, 300); // 延迟隐藏加载提示，确保纹理渲染完成
  }
};

/**
 * 窗口大小变化处理（无修改）
 */
const onWindowResize = () => {
  if (!container.value || !camera || !renderer) return;

  const width = container.value.clientWidth;
  const height = container.value.clientHeight;

  // 更新相机宽高比（保持场景比例正确）
  camera.aspect = width / height;
  camera.updateProjectionMatrix();

  // 更新渲染器尺寸（保持全屏）
  renderer.setSize(width, height);
};

/**
 * 动画循环（无修改）
 */
const animate = () => {
  animationId.value = requestAnimationFrame(animate);

  // 阻尼效果必须更新控制器（保持）
  if (controls) {
    controls.update();
  }

  // 渲染场景（保持）
  if (renderer && scene && camera) {
    renderer.render(scene, camera);
  }
};

// 监听全景图切换（无修改）
watch(currentPanorama, (newVal) => {
  if (newVal >= 0 && newVal < textures.length) {
    switchPanorama(newVal);
  }
});

// 组件挂载初始化（无修改）
onMounted(() => {
  setTimeout(() => {
    if (container.value) {
      initScene();
      animate();
    }
  }, 100); // 延迟初始化，确保DOM加载完成
});

// 组件卸载清理（无修改）
onUnmounted(() => {
  if (animationId.value) {
    cancelAnimationFrame(animationId.value);
  }
  window.removeEventListener('resize', onWindowResize);
  if (controls) controls.dispose();
  if (renderer) {
    renderer.dispose();
    if (container.value && renderer.domElement) {
      container.value.removeChild(renderer.domElement);
    }
  }
  textures.forEach((texture) => {
    if (texture) texture.dispose();
  });
  if (scene) scene.clear();
});
</script>

<style scoped>
/* 样式无修改（场景缩小是3D逻辑，不影响CSS布局） */
.panorama-viewer {
  position: relative;
  width: 100vw;
  height: 100vh;
  overflow: hidden;
}

.viewer-container {
  width: 100%;
  height: 100%;
  pointer-events: auto;
}

.loading-indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background-color: rgba(0, 0, 0, 0.7);
  color: white;
  padding: 10px 20px;
  border-radius: 4px;
  z-index: 200;
}

.controls-panel {
  position: absolute;
  bottom: 20px;
  left: 50%;
  transform: translateX(-50%);
  background-color: rgba(0, 0, 0, 0.6);
  color: white;
  padding: 15px 20px;
  border-radius: 8px;
  font-family: Arial, sans-serif;
  display: flex;
  flex-direction: column;
  gap: 10px;
  z-index: 100;
  pointer-events: auto;
}

.info {
  font-size: 14px;
  line-height: 1.5;
}

.panorama-switch {
  display: flex;
  gap: 10px;
  margin-top: 5px;
}

.panorama-switch button {
  background-color: rgba(255, 255, 255, 0.2);
  color: white;
  border: none;
  padding: 8px 15px;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s ease;
}

.panorama-switch button:hover {
  background-color: rgba(255, 255, 255, 0.3);
}

.panorama-switch button.active {
  background-color: #42b983;
}
</style>

3. 样式设计

为了提供良好的用户体验，我们需要设计简洁直观的界面样式：

<style scoped>
.panorama-viewer {
  position: relative;
  width: 100vw;
  height: 100vh;
  overflow: hidden;
}

.viewer-container {
  width: 100%;
  height: 100%;
  pointer-events: auto;
}

.loading-indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background-color: rgba(0, 0, 0, 0.7);
  color: white;
  padding: 10px 20px;
  border-radius: 4px;
  z-index: 200;
}

.controls-panel {
  position: absolute;
  bottom: 20px;
  left: 50%;
  transform: translateX(-50%);
  background-color: rgba(0, 0, 0, 0.6);
  color: white;
  padding: 15px 20px;
  border-radius: 8px;
  font-family: Arial, sans-serif;
  display: flex;
  flex-direction: column;
  gap: 10px;
  z-index: 100;
  pointer-events: auto;
}

.info {
  font-size: 14px;
  line-height: 1.5;
}

.panorama-switch {
  display: flex;
  gap: 10px;
  margin-top: 5px;
}

.panorama-switch button {
  background-color: rgba(255, 255, 255, 0.2);
  color: white;
  border: none;
  padding: 8px 15px;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s ease;
}

.panorama-switch button:hover {
  background-color: rgba(255, 255, 255, 0.3);
}

.panorama-switch button.active {
  background-color: #42b983;
}
</style>

关键技术点解析

1. 全景图原理

全景图的实现核心是 "Inside-out" 技术：

1. 创建一个巨大的球体，将全景图像作为纹理贴在球体内表面
2. 将相机放置在球体中心，这样用户就仿佛置身于全景环境中
3. 通过反转球体的 UV 坐标（geometry.scale(-1, 1, 1)），使纹理正确显示在球体内侧

2. 性能优化技巧

• 合理设置球体大小：球体半径设为 200 而非更大值，减少渲染负载
• 相机参数优化：调整视场角 (fov) 和远裁剪面 (far)，避免不必要的渲染
• 材质优化 ：使用FrontSide而非DoubleSide，减少一半的绘制操作
• 资源管理：在组件卸载时清理 Three.js 资源，包括几何体、材质、纹理和渲染器
• 缩放范围限制：设置合理的缩放范围，避免用户缩放过小导致 "空场景"

3. 交互体验优化

• 阻尼效果 ：启用控制器的阻尼效果 (enableDamping: true)，使旋转更平滑自然
• 操作提示：清晰的操作指南帮助用户快速掌握使用方法
• 加载状态：显示加载进度，提升用户体验
• 响应式设计：监听窗口大小变化，自动调整渲染尺寸

使用与扩展

如何添加更多全景图

1. 导入新的图片资源
2. 添加到panoramaImages数组中
3. 在控制面板添加对应的切换按钮

可能的扩展方向

• 添加全景图热点 (Hotspot)，实现场景内交互
• 增加 VR 模式支持，配合 VR 设备使用
• 添加自动旋转功能，自动展示全景效果
• 实现全景图之间的平滑过渡动画
• 添加全屏切换功能

总结

本文介绍了如何使用 Vue3 和 Three.js 构建一个高质量的全景图查看器，从基础实现到性能优化，涵盖了全景图技术的核心要点。通过合理设置 3D 场景参数和优化交互体验，我们可以创建出流畅、沉浸式的全景浏览效果。

该实现具有良好的可扩展性，可以根据实际需求添加更多功能，适用于虚拟旅游、房产展示、产品 360° 预览等多种场景。

希望本文能帮助你快速掌握全景图技术的实现方法，如果你有任何问题或改进建议，欢迎在评论区交流讨论！