第01章 项目概述与功能特性

1.1 项目简介

map-360-demo 是一个基于 Vue 3 + Vite + TypeScript 的纯前端演示项目，核心目标是实现 360° 全景图与真实地图（Leaflet）的双向联动。它展示了如何将 Photo Sphere Viewer v5 的全景浏览能力与 Leaflet 的真实地图能力无缝结合，构建一个可交互、可管理标记的沉浸式地图应用。

项目不依赖任何后端服务，所有数据（场景、标记）均在前端管理，标记数据通过浏览器 localStorage 持久化。这意味着克隆项目后即可本地运行，非常适合作为学习 Vue 3 组合式 API、Photo Sphere Viewer 插件体系以及地图联动开发的入门范例。

项目地址： https://github.com/znlgis/map-360-demo

1.2 核心功能特性

1.2.1 360° 全景浏览

基于 Photo Sphere Viewer v5 实现，支持：

• 拖拽旋转：鼠标拖拽或触摸滑动旋转视角
• 缩放：滚轮缩放，查看细节
• 全屏：一键全屏沉浸式浏览
• 导航栏：内置缩放、全屏、标题、标记列表等控制按钮

1.2.2 多场景切换

项目内置两个预设场景：

切换场景时，全景图与右下角地图会同步更新，包括地图中心坐标、方位角（bearing）和缩放级别。

1.2.3 地图联动

右下角嵌入的 Leaflet 地图（通过 PlanPlugin 实现）与全景图双向联动：

• 点击全景中的标记热点，地图上对应的热点会高亮
• 点击地图上的热点，全景会自动旋转到对应位置
• 地图与全景通过标记的 data.plan 字段自动关联

1.2.4 标记管理

这是项目的核心交互功能，支持：

• 添加标记：显式「添加模式」，点击全景空白处或地图精确定位，红色脉冲预览 pin 即时反馈，可取消重选
• 编辑标记：修改名称、描述、坐标与类型
• 删除标记：悬停标记行点击删除按钮
• 搜索标记：底部列表按名称/描述过滤
• 折叠列表：底部标记列表可折叠
• 新标记置顶：按创建时间倒序排列

1.2.5 场景跳转标记

标记类型二选一：

• 信息标记（📍）：展示信息，点击后全景旋转到对应位置
• 跳转标记（➜）：点击后切换到目标场景，使用绿色箭头 pin 标识

1.2.6 数据导入导出

• 导出：将全部标记下载为 JSON 文件（文件名带日期）
• 导入：选择 JSON 文件合并标记，自动校验与去重

1.2.7 数据持久化

• 标记自动保存到 localStorage，刷新页面不丢失
• 「恢复默认」一键还原预设标记

1.2.8 安全处理

标记名称/描述经过 HTML 转义，防止 XSS 注入。

1.2.9 中文界面

全部 UI 与交互文案为中文，包括 PSV 内置控件的语言配置。

1.3 技术栈

1.4 架构设计理念

项目采用纯前端、无后端、无 Pinia 的架构，核心设计理念包括：

1. 组合式函数（Composables）管理状态：全局状态、添加/编辑状态机、Toast 反馈分别封装为三个 composable，逻辑复用性强
2. 组件职责单一：App.vue 只做编排，PsvContainer 是唯一与 PSV 直接交互的组件
3. 模块级单例：状态通过模块顶层 ref 共享，多处调用返回同一份数据
4. 语义化接口：通过 defineExpose 暴露语义化方法，不直接暴露插件实例

1.5 适用场景

• 学习 Vue 3 组合式 API 与组件通信
• 学习 Photo Sphere Viewer v5 的插件体系（markers-plugin、plan-plugin）
• 学习全景图与地图联动的实现原理
• 作为 WebGIS 前端开发的参考范例

1.6 开源协议

本项目采用 MIT 协议开源，可自由使用、修改与分发。