photo-sphere-viewer 在 Vue 中的使用

qq_34041185

2077人浏览 · 2025-09-26 10:01:29

qq_34041185 · 2025-09-26 10:01:29 发布

photo-sphere-viewer 完整使用指南

一、简介

photo-sphere-viewer 是一款功能强大的全景图查看器 JavaScript 库，支持 360° 全景图片展示、虚拟导览、标记点、指南针等功能，适用于网页端全景图交互展示场景。本指南基于版本 5.11.1，结合 Vue 框架进行详细说明。

二、依赖安装

核心库及插件版本

所有@photo-sphere-viewer相关包的版本均为 5.11.1：

依赖包名称	版本	说明
@photo-sphere-viewer/core	5.11.1	核心库
@photo-sphere-viewer/compass-plugin	5.11.1	指南针插件
@photo-sphere-viewer/markers-plugin	5.11.1	标记点插件
@photo-sphere-viewer/virtual-tour-plugin	5.11.1	虚拟导览插件
@photo-sphere-viewer/gallery-plugin	5.11.1	画廊插件

安装命令

npm install @photo-sphere-viewer/core@5.11.1 @photo-sphere-viewer/compass-plugin@5.11.1 @photo-sphere-viewer/markers-plugin@5.11.1 @photo-sphere-viewer/virtual-tour-plugin@5.11.1 @photo-sphere-viewer/gallery-plugin@5.11.1 --save

三、Vue 集成步骤

1. 依赖引入

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

2. 创建容器

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

3. 初始化全景查看器

mounted() {
  // 销毁已有实例（防止重复初始化）
  if (this.viewer) {
    await this.viewer.destroy();
  }

  // 初始化全景查看器
  this.viewer = new Viewer({
    container: document.querySelector("#viewer"),
    panorama: "path/to/your/panorama.jpg", // 全景图路径
    plugins: [
      [CompassPlugin, {
        position: 'bottom right',
        hotspots: [
          { yaw: '0deg', color: 'red' },
          { yaw: '90deg' },
          { yaw: '180deg' },
          { yaw: '270deg' },
        ],
      }],
      [VirtualTourPlugin, {
        positionMode: 'manual',
        renderMode: '3d',
        nodes: this.nodes, // 导览节点数据
        startNodeId: this.nodes[0]?.id,
        dataMode: 'client',
        preload: true,
      }],
      MarkersPlugin,
      GalleryPlugin
    ],
    size: {
      width: "100%",
      height: "100%",
    },
    navbar: [],
  });

  // 获取插件实例
  this.markersPlugin = this.viewer.getPlugin(MarkersPlugin);
  this.virtualTourPlugin = this.viewer.getPlugin(VirtualTourPlugin);
  
  // 初始化事件监听
  this.initEventListeners();
}

四、核心功能实现

1. 标记点插件使用

添加多种类型标记点

// 在点击事件中添加标记点
this.viewer.addEventListener('click', ({ data }) => {
  if (!data.rightclick) {
    // 圆形标记点
    if (this.value === '0') {
      const marker = {
        id: '#' + Math.random(),
        tooltip: '圆形标点',
        circle: 10,
        svgStyle: {
          fill: 'rgba(30,144,255,0.6)',
          stroke: 'dodgerblue',
          strokeWidth: '1px',
        },
        position: { yaw: data.yaw, pitch: data.pitch },
        anchor: 'bottom center',
        data: { deletable: true },
      };
      this.markersPlugin.addMarker(marker);
    }
    // HTML标记点（带文本和图片）
    else if (this.value === '2') {
      const marker = {
        id: '#' + Math.random(),
        position: { yaw: data.yaw, pitch: data.pitch },
        html: `
          <div style="text-align: center;">
            <span style="color: white;">自定义文本</span>
            <img src="./image/photo/pin-blue.png" style="width: 34px;"/>
          </div>
        `,
        anchor: 'bottom right',
        data: { deletable: true },
      };
      this.markersPlugin.addMarker(marker);
    }
  }
});

标记点事件监听

initEventListeners() {
  // 双击删除标记点
  this.markersPlugin.addEventListener('select-marker', ({ marker, doubleClick }) => {
    if (marker.data?.deletable && doubleClick) {
      this.markersPlugin.removeMarker(marker);
      this.$message.success('标记点已删除');
    }
  });
}

2. 虚拟导览功能

节点切换与事件监听

// 切换到指定节点
changeNode(nodeId) {
  this.virtualTourPlugin.setCurrentNode(nodeId);
}

// 监听节点变化事件
this.virtualTourPlugin.addEventListener('node-changed', (e) => {
  this.currentNodeId = e.node.id;
  console.log('当前节点:', e.node.id);
});

节点数据结构详解

完整nodes数组示例（隐藏真实IP）

[
  {
    "id": "nodes-001",
    "panorama": "http://{server_ip}:15038/profile/upload/2025/09/26/250813_113320314_20250926014743A003.jpg",
    "thumbnail": "http://{server_ip}:15038/profile/upload/2025/09/26/250813_113320314_20250926014743A003.jpg",
    "time": "2025-08-13 11:33:34",
    "markers": [],
    "sphereCorrection": { "pan": "0deg" },
    "links": [
      { "nodeId": "nodes-002", "position": { "textureX": "2482", "textureY": "2128" } }
    ]
  },
  {
    "id": "nodes-002",
    "panorama": "http://{server_ip}:15038/profile/upload/2025/09/26/250813_094510819_20250926014819A004.jpg",
    "thumbnail": "http://{server_ip}:15038/profile/upload/2025/09/26/250813_094510819_20250926014819A004.jpg",
    "time": "2025-08-13 09:45:24",
    "markers": [],
    "sphereCorrection": { "pan": "0deg" },
    "links": [
      { "nodeId": "nodes-001", "position": { "textureX": "2482", "textureY": "2128" } }
    ]
  }
]

节点字段说明

字段名	类型	说明
`id`	string	节点唯一标识（必填）
`panorama`	string	全景图URL（`{server_ip}`需替换为实际服务器IP）
`thumbnail`	string	缩略图URL（可选）
`markers`	array	关联标记点数组（可选）
`sphereCorrection`	object	全景图校正参数（如`{ "pan": "0deg" }`）
`links`	array	关联节点信息（含`nodeId`和`position`）

五、关键生命周期管理

// 组件销毁前清理
beforeDestroy() {
  if (this.viewer) {
    this.viewer.destroy(); // 释放资源
  }
}

// 节点数据更新时重新初始化
watch: {
  nodes(newVal) {
    this.init(); 
  }
}

六、核心配置参数说明

参数名	类型	说明	示例值
`container`	HTMLElement	全景图容器元素	`document.querySelector("#viewer")`
`panorama`	string	全景图URL	`"https://example.com/pano.jpg"`
`plugins`	array	插件配置数组	`[[CompassPlugin, { position: 'bottom right' }]]`
`size`	object	尺寸配置	`{ width: "100%", height: "80vh" }`
`navbar`	array	导航栏按钮配置	`['zoom', 'fullscreen']`