Skills-SI市场
skills-si.com
提交技能
/
界面已本地化；技能介绍与说明文档按所选语言由 AI 自动翻译，代码、命令、路径和专业术语保留原文，以原作者文档为准。
探索技能
开发与工程 · SKILL.md

photo-sphere-viewer

photo-sphere-viewer

【开发与工程】Use when displaying 360-degree panoramic images (equirectangular/cubemap/dual-fisheye) in web applications, building virtual tours with markers and transitions, embedding interactive panoramas in Vue/React/vanilla JS, or creating 360-degree video players with gyroscope VR support. Photo-Sphere-Viewer v5: JavaScript panorama viewer based on Three.js. …

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Zznlgis / opengis-skillsMIT

技能说明

GitHub

name: photo-sphere-viewer description: "Use when displaying 360-degree panoramic images (equirectangular/cubemap/dual-fisheye) in web applications, building virtual tours with markers and transitions, embedding interactive panoramas in Vue/React/vanilla JS, or creating 360-degree video players with gyroscope VR support. Photo-Sphere-Viewer v5: JavaScript panorama viewer based on Three.js. Covers Viewer class, 6 adapters, 14 plugins, and markers system." tags:

  • javascript
  • typescript
  • threejs
  • webgl
  • 3d
  • panorama
  • 360-photo
  • virtual-tour

仓库地址： https://github.com/mistic100/Photo-Sphere-Viewer

文档： https://photo-sphere-viewer.js.org

演示： https://photo-sphere-viewer.js.org/demos/

API 参考： https://photo-sphere-viewer.js.org/api/

Playground： https://photo-sphere-viewer.js.org/playground.html

许可证： MIT

最新版本： v5.15.1（2026-08）

概述

Photo-Sphere-Viewer (PSV) 是一个基于 Three.js 的纯 JavaScript 库，用于在 Web 浏览器中显示 360° 全景照片/球体图像。支持从简单的照片球体到复杂的带标记、导航、陀螺仪和 VR 的虚拟导览。

特性说明
全景格式等距柱状图、立方体贴图（6面/条纹/展开图）、双鱼眼原始格式
分块加载大图分块（Equirectangular/Cubemap Tiles Adapter）
360° 视频等距柱状图 + 立方体贴图视频支持
标记系统图片/HTML/视频/SVG/多边形/折线标记，含提示框和动态缩放
VR 支持移动端陀螺仪 + 立体视差模式（需 GyroscopePlugin + StereoPlugin）
虚拟导览多全景场景链接，支持平滑过渡与双向箭头指示
插件生态14 个官方插件（Markers、Gallery、VirtualTour、Autorotate、Map 等）
框架集成原生 ES 模块，React wrapper 可用

唯一运行时依赖： Three.js（^0.185.1）。所有适配器和插件作为 @photo-sphere-viewer/* 独立 NPM 包发布。

环境准备与安装

安装核心包

npm install @photo-sphere-viewer/core

安装适配器和插件（按需）

# 适配器
npm install @photo-sphere-viewer/cubemap-adapter          # 立方体贴图
npm install @photo-sphere-viewer/equirectangular-video-adapter  # 360° 视频
npm install @photo-sphere-viewer/equirectangular-tiles-adapter  # 分块加载大图
npm install @photo-sphere-viewer/dual-fisheye-adapter     # 双鱼眼（Ricoh Theta 等）

# 常用插件
npm install @photo-sphere-viewer/markers-plugin           # 标记系统
npm install @photo-sphere-viewer/gallery-plugin           # 底部画廊
npm install @photo-sphere-viewer/virtual-tour-plugin      # 虚拟导览
npm install @photo-sphere-viewer/gyroscope-plugin         # 陀螺仪
npm install @photo-sphere-viewer/stereo-plugin            # 立体/VR
npm install @photo-sphere-viewer/autorotate-plugin        # 自动旋转
npm install @photo-sphere-viewer/video-plugin             # 视频控制条
npm install @photo-sphere-viewer/compass-plugin           # 罗盘
npm install @photo-sphere-viewer/map-plugin               # 地图集成

直接 HTML 引入

<div id="viewer" style="width: 100%; height: 100vh;"></div>

<script type="module">
  import { Viewer } from '@photo-sphere-viewer/core';
  import '@photo-sphere-viewer/core/index.css';

  const viewer = new Viewer({
    container: '#viewer',
    panorama: 'pano.jpg',
  });
</script>

注意： 需要 WebGL 支持（现代浏览器均支持）。移动端陀螺仪和立体 VR 功能需 HTTPS。

快速上手

基础全景查看器

import { Viewer } from '@photo-sphere-viewer/core';
import '@photo-sphere-viewer/core/index.css';

const viewer = new Viewer({
  container: document.querySelector('#viewer'),
  panorama: 'https://example.com/panorama.jpg',
  caption: '山顶全景',
  description: '拍摄于 2026 年 7 月',
  defaultYaw: '45deg',
  defaultPitch: '10deg',
  defaultZoomLvl: 50,
  navbar: ['zoom', 'fullscreen', 'caption'],
  loadingTxt: '加载中...',
  lang: {
    zoom: '缩放',
    fullscreen: '全屏',
  },
});

带标记和画廊

import { Viewer } from '@photo-sphere-viewer/core';
import { MarkersPlugin } from '@photo-sphere-viewer/markers-plugin';
import { GalleryPlugin } from '@photo-sphere-viewer/gallery-plugin';
import '@photo-sphere-viewer/markers-plugin/index.css';

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room1.jpg',
  navbar: ['zoom', 'fullscreen', 'markers', 'gallery'],
  plugins: [
    MarkersPlugin.withConfig({
      markers: [
        {
          id: 'door',
          position: { yaw: '30deg', pitch: 0 },
          image: 'pin.png',
          size: { width: 40, height: 40 },
          tooltip: '入口',
          content: '<h3>入口大门</h3><p>由此进入主展厅</p>',
        },
        {
          id: 'window',
          position: { yaw: '-90deg', pitch: '5deg' },
          html: '<div class="hotspot">窗</div>',
          tooltip: '落地窗 - 点击查看详情',
        },
      ],
    }),
    GalleryPlugin.withConfig({
      items: [
        { id: '1', name: '客厅', panorama: 'room1.jpg', thumbnail: 'thumb1.jpg' },
        { id: '2', name: '餐厅', panorama: 'room2.jpg', thumbnail: 'thumb2.jpg' },
        { id: '3', name: '卧室', panorama: 'room3.jpg', thumbnail: 'thumb3.jpg' },
      ],
      visibleOnLoad: true,
      hideOnClick: false,
    }),
  ],
});

viewer.addEventListener('ready', () => {
  console.log('全景加载完成');
});

立方体贴图

import { Viewer } from '@photo-sphere-viewer/core';
import { CubemapAdapter } from '@photo-sphere-viewer/cubemap-adapter';

const viewer = new Viewer({
  container: '#viewer',
  adapter: CubemapAdapter,
  panorama: {
    left: 'cubemap/left.jpg',
    front: 'cubemap/front.jpg',
    right: 'cubemap/right.jpg',
    back: 'cubemap/back.jpg',
    top: 'cubemap/top.jpg',
    bottom: 'cubemap/bottom.jpg',
  },
});

核心 API

Viewer 类

new Viewer(config: ViewerConfig) — 创建查看器实例，返回已初始化的 Viewer。

关键配置项：

配置项类型默认值说明
containerHTMLElement | string必填容器元素
panoramastring | object必填全景源（URL 或适配器对象）
adapterAdapterConstructorEquirectangularAdapter适配器类
pluginsPluginDefinition[][]插件数组
defaultYawnumber | string0默认水平角
defaultPitchnumber | string0默认俯仰角
defaultZoomLvlnumber50默认缩放 (0-100)
minFov / maxFovnumber30 / 90视场角范围（度）
fisheyeboolean | numberfalse鱼眼效果（0-1 或 true）
moveSpeednumber1拖拽灵敏度
zoomSpeednumber1滚轮缩放灵敏度
moveInertiaboolean | number0.8惯性移动（false 关闭）
navbarNavbarConfig—导航栏按钮配置
keyboardboolean | string'fullscreen'键盘控制
canvasBackgroundstring'#000'画布背景色
langobject—国际化覆盖（覆盖默认英文）

主要方法：

方法返回值说明
animate(options)Animation平滑旋转/缩放（yaw, pitch, zoom, speed）
rotate(position)—立即旋转到指定视角
setPanorama(url, options?)Promise切换全景图（支持过渡动画）
zoom(level) / zoomIn(step?) / zoomOut(step?)—缩放控制
getPosition(){ yaw, pitch }获取当前视角
getZoomLevel()number获取当前缩放 (0-100)
getPlugin(PluginClass)PluginInstance获取插件实例
setOption(key, value)—更新单个选项
setOptions(obj)—批量更新选项
destroy()—销毁查看器，释放 Three.js 资源

主要事件：

事件回调参数触发时机
ready—全景加载完成，首次渲染就绪
click{ rightclick, data: { yaw, pitch, ... } }点击全景
position-updated{ position: { yaw, pitch } }视角变化
zoom-updated{ zoomLevel }缩放变化
panorama-loaded{ data }新全景加载完成
load-progress{ progress }加载进度 (0-100)
fullscreen-updated{ fullscreen }全屏状态变化

适配器（全景格式）

适配器NPM 包适用场景配置要点
EquirectangularAdapter@photo-sphere-viewer/core（内置）标准 2:1 全景图默认即用，自动读取 XMP 元数据
CubemapAdapter@photo-sphere-viewer/cubemap-adapter立方体贴图（6 面/条纹/展开图）panorama: { left, front, ... }
EquirectangularTilesAdapter@photo-sphere-viewer/equirectangular-tiles-adapter大图分块加载配置多级 tiles 尺寸
CubemapTilesAdapter@photo-sphere-viewer/cubemap-tiles-adapter立方体贴图分块类似上者，六面分块
EquirectangularVideoAdapter@photo-sphere-viewer/equirectangular-video-adapter360° 视频（等距柱状）panorama: { source: 'video.mp4' }
CubemapVideoAdapter@photo-sphere-viewer/cubemap-video-adapter360° 视频（立方体贴图）需配合 VideoPlugin
DualFisheyeAdapter@photo-sphere-viewer/dual-fisheye-adapter双鱼眼原始格式（Ricoh Theta Z1 等）v5.15+ 含 DualFisheyeVideoAdapter

适配器的全景数据配置（PanoData）

const viewer = new Viewer({
  adapter: EquirectangularAdapter,
  panorama: 'crop.jpg',
  panoData: {
    fullWidth: 4096,   // 源图像完整宽度
    fullHeight: 2048,   // 源图像完整高度
    croppedWidth: 2048, // 裁剪后宽度
    croppedHeight: 1024,// 裁剪后高度
    croppedX: 1024,     // 裁剪 X 偏移
    croppedY: 512,      // 裁剪 Y 偏移
  },
});

等距柱状图适配器默认使用 useXmpData: true 自动读取图像 XMP 元数据获取裁剪信息。v5.14.2+ 新增 shader 选项（默认 false，可设为 true 用像素着色器消除极点扭曲）。

插件系统、MarkersPlugin 与虚拟导览（VirtualTourPlugin）的完整用法见 reference/plugins.md

AI 使用建议

  • 推荐工作流模式：AI 助手应将全景项目组织为「Viewer 核心配置 → 适配器选择 → 插件组合 → 标记定义」的结构。初始用 EquirectangularAdapter + MarkersPlugin + GalleryPlugin 组合覆盖 80% 场景，后续按需添加 VirtualTourPlugin 或 GyroscopePlugin。
  • 关键注意事项：① panorama 路径需确保 CORS 头正确配置（Access-Control-Allow-Origin: *）；② 所有时长/速度参数以毫秒为单位（speed: 1500 = 1.5 秒）或 '3rpm' 格式（每分钟旋转次数计算）；③ MarkersPlugin 的 CSS 样式需通过 className + 外部 CSS 控制，不建议内联大量样式；④ setPanorama() 后标记需重新设置，除非使用 VirtualTourPlugin 管理节点。
  • 常用代码模式：
    • 基础查看器：new Viewer({ container, panorama }) + @photo-sphere-viewer/core/index.css
    • 标记：MarkersPlugin.withConfig({ markers: [{ id, position, image, tooltip }] })
    • 画廊：GalleryPlugin.withConfig({ items: [{ id, name, panorama, thumbnail }] })
    • 导览：VirtualTourPlugin.withConfig({ nodes, startNodeId, positionMode: 'manual' })
    • 动画：viewer.animate({ yaw, pitch, zoom, speed: 1500 })
    • 获取插件：viewer.getPlugin(MarkersPlugin).addMarker(...)

参考资源

相关技能

发现更多相关技能

查看全部技能
我的收藏