360度全景图像查看器技术文档

2026-01-25 05:08:50作者：尤辰城Agatha

本文档旨在详细介绍如何使用360-image-viewer库，一个轻量级的WebGL全景图像查看器，适合桌面和移动设备。该库通过使用regl，提供了仅140KB的压缩版本（或46KB的gzipped版本），作为对比，ThreeJS大小约为500KB，非常适合对体积有要求的项目。

安装指南

要将此全景图像查看器集成到您的项目中，请通过npm进行安装：

npm install 360-image-viewer --save

这将把360-image-viewer添加为项目的依赖项。

使用说明

快速启动

一旦安装完成，您可以通过以下简短代码片段来初始化并展示一个全屏的360度全景图像查看器。

首先，确保您的图片已经加载完毕：

const image = new Image();
image.src = 'panosphere.jpg';

然后，在图片加载完成后设置查看器：

image.onload = () => {
  const viewer = create360Viewer({ image });
  document.body.appendChild(viewer.canvas);
  
  const fit = canvasFit(viewer.canvas, window, window.devicePixelRatio);
  window.addEventListener('resize', fit, false);
  fit();
  viewer.start();
};

高级使用

create360Viewer函数允许传递一个选项对象以自定义查看器的行为：

const viewer = create360Viewer({
  image,
  fov: 60, // 默认视场角为45度
  rotateSpeed: 0.2, // 控制旋转速度
});

核心方法

viewer.start(): 启动渲染循环。
viewer.stop(): 停止渲染循环。
viewer.render(): 渲染当前帧，适用于手动控制渲染的情况。
viewer.enableControls(): 开启控件，使鼠标和触摸事件生效。
viewer.disableControls(): 禁用控件。
viewer.texture(newImage): 更换当前显示的图像。

API使用文档

创建查看器: create360Viewer([opt])
- image: 图像元素，也可以稍后设置。
- 可选参数包括canvas, fov, rotateSpeed, damping, 和 clearColor等，支持自定义配置。
核心属性与方法：
- viewer.canvas: 获取用于渲染的canvas元素。
- viewer.fov, viewer.phi, viewer.theta: 分别表示视角角度和旋转角度。
- viewer.texture: 动态更换图像源。