# 实现一个360度全景插件|博客系列

> 本文详细介绍了如何使用Three.js开发一个360度全景插件，包括全景图像渲染、交互实现、核心技术原理解析及实用开发技巧，适合前端开发者学习WebGL和全景应用开发。

- 原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/comprehensive/-%E5%AE%9E%E7%8E%B0%E4%B8%80%E4%B8%AA360%E5%BA%A6%E5%85%A8%E6%99%AF%E6%8F%92%E4%BB%B6
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2025.10.25
- 可见范围：免费部分

---

## 导读

本文从绘图基础开始讲起，详细介绍了如何使用`Three.js`开发一个功能齐全的全景插件。

我们先来看一下插件的效果：

![](http://conardli.top/img/qj/qj_15_qj.gif)

![](http://conardli.top/img/qj/qj_17_qj.gif)

如果你对`Three.js`已经很熟悉了，或者你想跳过基础理论，那么你可以直接从[全景预览](#全景预览)开始看起。

本项目的`github`地址：https://github.com/ConardLi/tpanorama

![](http://conardli.top/img/qj/qj_0_%E6%96%87%E7%AB%A0%E5%AF%BC%E8%AF%BB.png)

## 一、理清关系

### 1.1 OpenGL

![](http://conardli.top/img/qj/WebGl.png)

`OpenGL`是用于渲染`2D、3D`量图形的跨语言、跨平台的应用程序编程接口`（API）`。

这个接口由近`350`个不同的函数调用组成，用来从简单的图形比特绘制复杂的三维景象。

`OpenGL ES` 是` OpenGL `三维图形` API `的子集，针对手机、`PDA`和游戏主机等嵌入式设备而设计。

基于`OpenGL`，一般使用`C`或`Cpp`开发，对前端开发者来说不是很友好。

### 1.2 WebGL

`WebGL`把`JavaScript`和`OpenGL ES 2.0`结合在一起，从而为前端开发者提供了使用`JavaScript`编写`3D`效果的能力。

`WebGL`为`HTML5 Canvas`提供硬件`3D`加速渲染，这样`Web`开发人员就可以借助系统显卡来在浏览器里更流畅地展示`3D`场景和模型了，还能创建复杂的导航和数据视觉化。

### 1.3 Canvas

`Canvas`是一个可以自由制定大小的矩形区域，可以通过`JavaScript`可以对矩形区域进行操作，可以自由的绘制图形，文字等。

一般使用`Canvas`都是使用它的`2d`的`context`功能，进行`2d`绘图，这是其本身的能力。

和这个相对的，`WebGL`是三维，可以描画`3D`图形，`WebGL`，想要在浏览器上进行呈现，它必须需要一个载体，这个载体就是`Canvas`，区别于之前的`2dcontext`，还可以从`Canvas`中获取`webglcontext`。

### 1.4 Three.js

![](http://conardli.top/img/qj/three.png)

我们先来从字面意思理解下：`Three`代表`3D`，`js`代表`JavaScript`，即使用`JavaScript`来开发`3D`效果。

`Three.js`是使用`JavaScript `对 `WebGL`接口进行封装与简化而形成的一个易用的`3D`库。

直接使用`WebGL`进行开发对于开发者来说成本相对来说是比较高的，它需要你掌握较多的计算机图形学知识。

`Three.js`在一定程度上简化了一些规范和难以理解的概念，对很多`API`进行了简化，这大大降低了学习和开发三维效果成本。

下面我们来具体看一下使用`Three.js`必须要知道的知识。

## 二、Three.js基础知识

使用`Three.js`绘制一个三维效果，至少需要以下几个步骤：

- 创建一个容纳三维空间的场景 — `Sence`

- 将需要绘制的元素加入到场景中，对元素的形状、材料、阴影等进行设置

- 给定一个观察场景的位置，以及观察角度，我们用相机对象（`Camera`）来控制

- 将绘制好的元素使用渲染器（`Renderer`）进行渲染，最终呈现在浏览器上

拿电影来类比的话，场景对应于整个布景空间，相机是拍摄镜头，渲染器用来把拍摄好的场景转换成胶卷。

### 2.1 场景

场景允许你设置哪些对象被`three.js`渲染以及渲染在哪里。

我们在场景中放置对象、灯光和相机。

很简单，直接创建一个`Scene`的实例即可。

```js
 _scene = new Scene();
```
### 2.2 元素

有了场景，我们接下来就需要场景里应该展示哪些东西。

![](http://conardli.top/img/qj/mesh.jpg)

一个复杂的三维场景往往就是由非常多的元素搭建起来的，这些元素可能是一些自定义的几何体（`Geometry`），或者外部导入的复杂模型。

`Three.js` 为我们提供了非常多的`Geometry`，例如`SphereGeometry`（球体）、	`TetrahedronGeometry`（四面体）、`TorusGeometry`（圆环体）等等。

在`Three.js`中，材质（`Material`）决定了几何图形具体是以什么形式展现的。它包括了一个几何体如何形状以外的其他属性，例如色彩、纹理、透明度等等，`Material`和`Geometry`是相辅相成的，必须结合使用。

下面的代码我们创建了一个长方体体，赋予它基础网孔材料（`MeshBasicMaterial`）

```js
    var geometry = new THREE.BoxGeometry(200, 100, 100);
    var material = new THREE.MeshBasicMaterial({ color: 0x645d50 });
    var mesh = new THREE.Mesh(geometry, material);
            _scene.add(mesh);
```

![](http://conardli.top/img/qj/pno1.png)

能以这个角度看到几何体实际上是相机的功劳，这个我们[下面的章节](#相机)再介绍，这让我们看到一个几何体的轮廓，但是感觉怪怪的，这并不像一个几何体，实际上我们还需要为它添加光照和阴影，这会让几何体看起来更真实。

基础网孔材料（`MeshBasicMaterial`）不受光照影响的，它不会产生阴影，下面我们为几何体换一种受光照影响的材料：网格标准材质(`Standard Material`)，并为它添加一些光照：

```js
    var geometry = new THREE.BoxGeometry(200, 100, 100);
    var material = new THREE.MeshStandardMaterial({ color: 0x645d50 });
    var mesh = new THREE.Mesh(geometry, material);
    _scene.add(mesh);
    // 创建平行光-照亮几何体
    var directionalLight = new THREE.DirectionalLight(0xffffff, 1);
     directionalLight.position.set(-4, 8, 12);
    _scene.add(directionalLight);
    // 创建环境光
    var ambientLight = new THREE.AmbientLight(0xffffff);
    _scene.add(ambientLight);
```

![](http://conardli.top/img/qj/pno2.png)

有了光线的渲染，让几何体看起来更具有`3D`效果，`Three.js`中光源有很多种，我们上面使用了环境光(`AmbientLight`)和平行光(`DirectionalLight`)。

环境光会对场景中的所有物品进行颜色渲染。

平行光你可以认为像太阳光一样，从极远处射向场景中的光。它具有方向性，也可以启动物体对光的反射效果。

除了这两种光，`Three.js`还提供了其他几种光源，它们适用于不同情况下对不同材质的渲染，可以根据实际情况选择。

### 2.3 坐标系

在说相机之前，我们还是先来了解一下坐标系的概念：

在三维世界中，坐标定义了一个元素所处于三维空间的位置，坐标系的原点即坐标的基准点。

最常用的，我们使用距离原点的三个长度（距离`x`轴、距离`y`轴、距离`z`轴）来定义一个位置，这就是直角坐标系。

在判定坐标系时，我们通常使用大拇指、食指和中指，并互为`90`度。大拇指代表`X`轴，食指代表`Y`轴，中指代表`Z`轴。

这就产生了两种坐标系：左手坐标系和右手坐标系。

![](http://conardli.top/img/qj/qj_4_zbx.png)

`Three.js`中使用的坐标系即右手坐标系。

我们可以在我们的场景中添加一个坐标系，这样我们可以清楚的看到元素处于什么位置：

```js
 var axisHelper = new THREE.AxisHelper(600);
 _scene.add(axisHelper);
```

![](http://conardli.top/img/qj/qj_5_zbx.png)

其中红色代表`X`轴，绿色代表`Y`轴，蓝色代表`Z`轴。

### 2.4 相机

上面看到的几何体的效果，如果不创建一个相机(`Camera`)，是什么也看不到的，因为默认的观察点在坐标轴原点，它处于几何体的内部。

相机(`Camera`)指定了我们在什么位置观察这个三维场景，以及以什么样的角度进行观察。

#### 2.4.1 两种相机的区别

目前`Three.js`提供了几种不同的相机，最常用的，也是下面插件中使用的两种相机是：`PerspectiveCamera`（透视相机）、 `OrthographicCamera`（正交投影相机）。

![](http://conardli.top/img/qj/qj_1_camera.png)

上面的图很清楚的解释了两种相机的区别：

右侧是 `OrthographicCamera`（正交投影相机）他不具有透视效果，即物体的大小不受远近距离的影响，对应的是投影中的正交投影。我们数学课本上所画的几何体大多数都采用这种投影。

左侧是`PerspectiveCamera`（透视相机），这符合我们正常人的视野，近大远小，对应的是投影中的透视投影。

如果你想让场景看起来更真实，更具有立体感，那么采用透视相机最合适，如果场景中有一些元素你不想让他随着远近放大缩小，那么采用正交投影相机最合适。

#### 2.4.2 构造参数

我们再分别来看看两个创建两个相机需要什么参数：

```js
_camera = new OrthographicCamera(left, right, top, bottom, near, far);
```

![](http://conardli.top/img/qj/qj_2_camera.jpg)

`OrthographicCamera`接收六个参数，`left, right, top, bottom`分别对应上、下、左、右、远、近的一个距离，超过这些距离的元素将不会出现在视野范围内，也不会被浏览器绘制。实际上，这六个距离就构成了一个立方体，所以`OrthographicCamera`的可视范围永远在这个立方体内。

```js
_camera = new PerspectiveCamera(fov, aspect, near, far);
```

![](http://conardli.top/img/qj/qj_3_camera.png)

`PerspectiveCamera`接收四个参数，`near`、`far`和上面的相同，分别对应相机可观测的最远和最近距离；`fov`代表水平范围可观测的角度，`fov`越大，水平范围能观测到的范围越广；`aspect`代表水平方向和竖直方向可观测距离的比值，所以`fov`和`aspect`就可以确定垂直范围内能观测到的范围。

#### 2.4.3 position、lookAt

关于相机还有两个必须要知道的点，一个是`position`属性，一个是`lookAt`函数：

`position`属性指定了相机所处的位置。

`lookAt`函数指定相机观察的方向。

实际上`position`的值和`lookAt`接收的参数都是一个类型为`Vector3`的对象，这个对象用来表示三维空间中的坐标，它有三个属性：`x、y、z`分别代表距离`x`轴、距离`y`轴、距离`z`轴的距离。

下面，我们让相机观察的方向指向原点，另外分别让`x、y、z`为0，另外两个参数不为0，看一下视野会发生什么变化：

```js
_camera = new OrthographicCamera(-window.innerWidth / 2, window.innerWidth / 2, window.innerHeight / 2, -window.innerHeight / 2, 0.1, 1000);
 _camera.lookAt(new THREE.Vector3(0, 0, 0))

 _camera.position.set(0, 300, 600); // 1 - x为0

 _camera.position.set(500, 0, 600); // 2 - y为0

 _camera.position.set(500, 300, 0); // 3 - z为0
```

![](http://conardli.top/img/qj/qj_6_xj.png)

很清楚的看到`position`决定了我们视野的出发点，但是镜头指向的方向是不变的。

下面我们将`position`固定，改变相机观察的方向：

```js
_camera = new OrthographicCamera(-window.innerWidth / 2, window.innerWidth / 2, window.innerHeight / 2, -window.innerHeight / 2, 0.1, 1000);
_camera.position.set(500, 300, 600); 

_camera.lookAt(new THREE.Vector3(0, 0, 0)) // 1 - 视野指向原点

_camera.lookAt(new THREE.Vector3(200, 0, 0)) // 2 - 视野偏向x轴
```

![](http://conardli.top/img/qj/qj_7_xj.png)

可见：我们视野的出发点是相同的，但是视野看向的方向发生了改变。

#### 2.4.4 两种相机对比

好，有了上面的基础，我们再来写两个例子看一看两个相机的视角对比，为了方便观看，我们创建两个位置不同的几何体：

```js
var geometry = new THREE.BoxGeometry(200, 100, 100);
var material = new THREE.MeshStandardMaterial({ color: 0x645d50 });
var mesh = new THREE.Mesh(geometry, material);
_scene.add(mesh);

var geometry = new THREE.SphereGeometry(50, 100, 100);
var ball = new THREE.Mesh(geometry, material);
ball.position.set(200, 0, -200);
_scene.add(ball);
```

正交投影相机视野：

```js
_camera = new OrthographicCamera(-window.innerWidth / 2, window.innerWidth / 2, window.innerHeight / 2, -window.innerHeight / 2, 0.1, 1000);
_camera.position.set(0, 300, 600);
_camera.lookAt(new THREE.Vector3(0, 0, 0))
```

![](http://conardli.top/img/qj/qj_8_xj.png)

透视相机视野：

```js
_camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1100);
_camera.position.set(0, 300, 600);
_camera.lookAt(new THREE.Vector3(0, 0, 0))
```

![](http://conardli.top/img/qj/qj_9_xj.png)

可见，这印证了我们上面[关于两种相机的理论](#两种相机的区别)

### 2.5 渲染器

上面我们创建了场景、元素和相机，下面我们要告诉浏览器将这些东西渲染到浏览器上。

`Three.js`也为我们提供了几种不同的渲染器，这里我们主要看`WebGL`渲染器(`WebGLRenderer`)。顾名思义：`WebGL`渲染器使用`WebGL`来绘制场景，其够利用`GPU`硬件加速从而提高渲染性能。

```js
_renderer = new THREE.WebGLRenderer();
```

你需要将你使用`Three.js`绘制的元素添加到浏览器上，这个过程需要一个载体，上面我们介绍，这个载体就是`Canvas`，你可以通过`_renderer.domElement`获取到这个`Canvas`，并将它给定到真实`DOM`中。

```js
 _container = document.getElementById('conianer');
 _container.appendChild(_renderer.domElement);
```

使用`setSize`函数设定你要渲染的范围，实际上它改变的就是上面`Canvas`的范围：

```js
_renderer.setSize(window.innerWidth, window.innerHeight);
```

现在，你已经指定了一个渲染的载体和载体的范围，你可以通过`render`函数渲染上面指定的场景和相机：

```js
_renderer.render(_scene, _camera);
```

实际上，你如果依次执行上面的代码，可能屏幕上还是黑漆漆的一片，并没有任何元素渲染出来。

这是因为上面你要渲染的元素可能并未被加载完，你就执行了渲染，并且只执行了一次，这时我们需要一种方法，让场景和相机进行实时渲染，我们需要用到下面的方法：

### 2.6 requestAnimationFrame

`window.requestAnimationFrame()`告诉浏览器——你希望执行一个动画，并且要求浏览器在下次重绘之前调用指定的回调函数更新动画。

该方法需要传入一个回调函数作为参数，该回调函数会在浏览器下一次重绘之前执行。

```js
window.requestAnimationFrame(callback);
```

若你想在浏览器下次重绘之前继续更新下一帧动画，那么回调函数自身必须再次调用`window.requestAnimationFrame()`。

使用者韩函数就意味着，你可以在`requestAnimationFrame`不停的执行绘制操作，浏览器就实时的知道它需要渲染的内容。

当然，某些时候你已经不需要实时绘制了，你也可以使用`cancelAnimationFrame`立即停止这个绘制：

```js
window.cancelAnimationFrame(myReq);
```

来看一个简单的例子：

```js
        var i = 0;
        var animateName;
        animate();
        function animate() {
            animateName = requestAnimationFrame(animate);
            console.log(i++);
            if (i > 100) {
                cancelAnimationFrame(animateName);
            }
        }
```

来看一下执行效果：

![](http://conardli.top/img/qj/requestAnimationFrame.gif)

我们使用`requestAnimationFrame`和`Three.js`的渲染器结合使用，这样就能实时绘制三维动画了：

```js
        function animate() {
            requestAnimationFrame(animate);
            _renderer.render(_scene, _camera);
        }
```

借助上面的代码，我们可以简单实现一些动画效果：

```js
        var y = 100;
        var option = 'down';
        function animateIn() {
            animateName = requestAnimationFrame(animateIn);
            mesh.rotateX(Math.PI / 40);
            if (option == 'up') {
                ball.position.set(200, y += 8, 0);
            } else {
                ball.position.set(200, y -= 8, 0);
            }
            if (y < 1) { option = 'up'; }
            if (y > 100) { option = 'down' }
        }
```

![](http://conardli.top/img/qj/qj_10_animate.gif)

### 2.7 总结

上面的知识是`Three.js`中最基础的知识，也是最重要的和最主干的。

这些知识能够让你在看到一个复杂的三维效果时有一定的思路，当然，要实现还需要非常多的细节。这些细节你可以去[官方文档](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene)中查阅。

下面的章节即告诉你如何使用`Three.js`进行实战 — 实现一个360度全景插件。

这个插件包括两部分，第一部分是对全景图进行预览。

第二部分是对全景图的标记进行配置，并关联预览的坐标。

我们首先来看看全景预览部分。

## 三、全景预览

![](http://conardli.top/img/qj/qj_11_qj.gif)

### 3.1 基本逻辑

- 将一张全景图包裹在球体的内壁

- 设定一个观察点，在球的圆心

- 使用鼠标可以拖动球体，从而改变我们看到全景的视野

- 鼠标滚轮可以缩放，和放大，改变观察全景的远近

- 根据坐标在全景图上挂载一些标记，如文字、图标等，并且可以增加事件，如点击事件

### 3.2 初始化

我们先把必要的基础设施搭建起来：

场景、相机（选择远景相机，这样可以让全景看起来更真实）、渲染器：

```js

_scene = new THREE.Scene();
initCamera();
initRenderer();
animate();

// 初始化相机
function initCamera() {
    _camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1100);
    _camera.position.set(0, 0, 2000);
    _camera.lookAt(new THREE.Vector3(0, 0, 0));
}

// 初始化渲染器
function initRenderer() {
    _renderer = new THREE.WebGLRenderer();
    _renderer.setSize(window.innerWidth, window.innerHeight);
    _container = document.getElementById('panoramaConianer');
    _container.appendChild(_renderer.domElement);
}

// 实时渲染
function animate() {
    requestAnimationFrame(animate);
    _renderer.render(_scene, _camera);
}
```

下面我们在场景内添加一个球体，并把全景图作为材料包裹在球体上面：

```js
var mesh = new THREE.Mesh(new THREE.SphereGeometry(1000, 100, 100),
new THREE.MeshBasicMaterial(
        { map: ImageUtils.loadTexture('img/p3.png') }
    ));
_scene.add(mesh);
```

然后我们看到的场景应该是这样的：

![](http://conardli.top/img/qj/qj_12_qj.png)

这不是我们想要的效果，我们想要的是从球的内部观察全景，并且全景图是附着外球的内壁的，而不是铺在外面：

我们只要需将`Material`的`scale`的一个属性设置为负值，材料即可附着在几何体的内部：

```js
 mesh.scale.x = -1;
```

然后我们将相机的中心点移动到球的中心：

```js
 _camera.position.set(0, 0, 0);
```

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/comprehensive/-%E5%AE%9E%E7%8E%B0%E4%B8%80%E4%B8%AA360%E5%BA%A6%E5%85%A8%E6%99%AF%E6%8F%92%E4%BB%B6
