# mapbox
**Repository Path**: manyhappy163/mapbox
## Basic Information
- **Project Name**: mapbox
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-19
- **Last Updated**: 2025-08-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Mapbox 地图应用 - 模块化架构
## 项目概述
这是一个基于 **MapLibre GL** 和 **Vue 3** 的现代化地图应用，采用模块化的管理器架构设计。项目支持自定义实体、拖拽功能、绘制工具、鹰眼、分屏等多种地图功能，并提供了完整的UI组件库。
## 🚀 核心特性
- 🗺️ **高性能地图渲染**: 基于 MapLibre GL 5.6.0 的高性能地图渲染
- 🎯 **丰富的图形实体**: 支持点、线、面、箭头、广告牌等多种图形实体
- 🖱️ **流畅拖拽体验**: 优化的拖拽功能，避免闪烁问题
- ✏️ **智能绘制工具**: 支持动态绘制多种图形，支持撤销和重做
- 👁️ **鹰眼功能**: 提供鹰眼小地图，实时同步主地图视野
- 🖼️ **分屏显示**: 支持多地图分屏显示功能
- 🎨 **现代化UI**: 基于 Element Plus 的现代化UI组件
- 🔧 **模块化架构**: 清晰的功能分离和职责划分
- 📱 **响应式设计**: 支持移动端和桌面端适配
## 🛠️ 技术栈
- **前端框架**: Vue 3 + Vue Router 4
- **地图引擎**: MapLibre GL 5.6.0
- **UI组件库**: Element Plus 2.10.2
- **构建工具**: Vite 6.3.5
- **样式处理**: SCSS + PostCSS
- **坐标转换**: Proj4.js
- **地理计算**: Turf.js
- **音效处理**: Tone.js
## 🏗️ 架构设计
### 核心管理器
1. **MapInitializer** - 地图初始化器
- 负责地图实例的创建和初始化配置
- 验证和合并配置选项
- 添加地图控制器
2. **EntityManager** - 实体管理器
- 管理地图上的所有图形实体
- 提供实体的增删改查功能
- 处理实体的生命周期
3. **DrawManager** - 绘制管理器
- 处理地图上的图形绘制功能
- 管理绘制事件和状态
- 支持单点、双点和多点绘制
4. **OverviewManager** - 鹰眼管理器
- 管理地图的鹰眼小地图功能
- 同步主地图视野到鹰眼
- 提供鹰眼的显示/隐藏控制
5. **SplitScreenManager** - 分屏管理器
- 管理多地图分屏显示
- 处理分屏布局和同步
- 控制分屏模式切换
6. **MapController** - 地图控制器
- 负责地图的飞行定位和配置更新
- 提供地图状态查询功能
- 控制地图交互行为
7. **UIManager** - UI管理器
- 管理地图相关的UI组件
- 处理状态栏和右键菜单
- 控制UI组件的生命周期
## 📁 项目结构
```
mapbox/
├── packages/ # 核心地图包
│ ├── graphic/ # 图形实体
│ │ ├── AttackArrow.js # 攻击箭头
│ │ ├── BaseGraphic.js # 基础图形类
│ │ ├── BillboardEntity.js # 广告牌实体
│ │ ├── BottomCurveArrow.js # 底部曲线箭头
│ │ ├── CompositeBillboardLineLabel.js # 复合广告牌线标签
│ │ ├── DoubleArrow.js # 双箭头
│ │ ├── GatheringPlace.js # 集结地
│ │ ├── Label.js # 标签实体
│ │ ├── Line.js # 线实体
│ │ ├── Point.js # 点实体
│ │ ├── Polygon.js # 面实体
│ │ ├── Rectangle.js # 矩形实体
│ │ ├── SatelliteEntity.js # 卫星实体
│ │ ├── StraightArrow.js # 直线箭头
│ │ ├── SwallowtailArrow.js # 燕尾箭头
│ │ ├── graphicRegistry.js # 图形注册表
│ │ └── mixins/ # 功能混入
│ │ ├── ClickMixin.js # 点击混入
│ │ ├── DraggableMixin.js # 拖拽混入
│ │ ├── EditMixin.js # 编辑混入
│ │ ├── PopupMixin.js # 弹窗混入
│ │ ├── RemoveMixin.js # 删除混入
│ │ └── ShowMixin.js # 显示混入
│ ├── managers/ # 管理器模块
│ │ ├── DrawManager.js # 绘制管理器
│ │ ├── EntityManager.js # 实体管理器
│ │ ├── MapController.js # 地图控制器
│ │ ├── MapInitializer.js # 地图初始化器
│ │ ├── OverviewManager.js # 鹰眼管理器
│ │ ├── SplitScreenManager.js # 分屏管理器
│ │ ├── TrajectoryManager.js # 轨迹管理器
│ │ └── UIManager.js # UI管理器
│ ├── ui/ # UI组件
│ │ ├── contextMenu.js # 右键菜单
│ │ ├── dialog.js # 对话框
│ │ ├── draw.js # 绘制提示
│ │ ├── label.js # 标签编辑
│ │ ├── popup.js # 弹窗
│ │ ├── rainEffect.js # 雨滴效果
│ │ ├── snowEffect.js # 雪花效果
│ │ ├── statusBar.js # 状态栏
│ │ └── style.scss # 样式文件
│ ├── utils/ # 工具类
│ │ ├── animationUtils.js # 动画工具
│ │ ├── coordUtils.js # 坐标工具
│ │ ├── draw.js # 绘制工具
│ │ ├── eventUtils.js # 事件工具
│ │ ├── formatUtils.js # 格式化工具
│ │ ├── mapLayerUtils.js # 地图图层工具
│ │ ├── outlineUtils.js # 轮廓工具
│ │ ├── popup.js # 弹窗工具
│ │ └── utils.js # 通用工具
│ ├── theme/ # 主题
│ │ └── theme.js # 主题配置
│ └── index.js # 主入口文件
├── src/ # Vue应用源码
│ ├── views/ # 页面组件
│ │ ├── Home.vue # 首页
│ │ └── example/ # 示例页面
│ │ ├── Arrow.vue # 箭头示例
│ │ ├── BillboardEntity.vue # 广告牌示例
│ │ ├── Draw.vue # 绘制示例
│ │ ├── DynamicStyle.vue # 动态样式示例
│ │ ├── PointLinePolygon.vue # 点线面示例
│ │ ├── SatelliteDemo.vue # 卫星示例
│ │ ├── SplitScreen.vue # 分屏示例
│ │ └── TrajectoryPlayback.vue # 轨迹回放示例
│ ├── components/ # Vue组件
│ │ ├── MapToolbar.vue # 地图工具栏
│ │ └── ParticleBackground.vue # 粒子背景
│ ├── layout/ # 布局组件
│ │ └── index.vue # 主布局
│ ├── router/ # 路由配置
│ │ └── index.js # 路由入口
│ ├── mock/ # 模拟数据
│ │ └── mockBillboardEntities.js # 广告牌模拟数据
│ ├── assets/ # 静态资源
│ │ ├── images.jpg # 示例图片
│ │ ├── index.scss # 全局样式
│ │ ├── style.json # 样式配置
│ │ └── vue.svg # Vue logo
│ └── main.js # 应用入口
├── public/ # 静态资源
│ ├── fontawesome/ # 字体图标
│ │ ├── css/
│ │ │ └── all.min.css # FontAwesome 样式
│ │ └── webfonts/
│ │ ├── fa-brands-400.ttf
│ │ ├── fa-brands-400.woff2
│ │ ├── fa-regular-400.ttf
│ │ ├── fa-regular-400.woff2
│ │ ├── fa-solid-900.ttf
│ │ ├── fa-solid-900.woff2
│ │ ├── fa-v4compatibility.ttf
│ │ └── fa-v4compatibility.woff2
│ └── vite.svg # Vite logo
├── build.js # 构建脚本
├── index.html # HTML模板
├── package.json # 项目配置
├── package-lock.json # 锁定依赖
├── statistics.js # 统计脚本
├── vite.config.js # Vite配置
└── README.md # 项目文档
```
## 🚀 快速开始
### 环境要求
- Node.js >= 16.0.0
- npm >= 8.0.0
### 安装依赖
```bash
npm install
```
### 启动开发服务器
```bash
npm run dev
```
### 构建生产版本
```bash
npm run build
```
### 预览生产版本
```bash
npm run preview
```
### 构建地图包
```bash
npm run build:packages
```
### 生成文档
```bash
npm run doc
```
## 📖 使用示例
### 基本使用
```javascript
import Map from './packages/index.js';
// 创建地图实例
const map = new Map('map-container', {
style: 'https://demotiles.maplibre.org/style.json',
scene: {
center: { lng: 116.397, lat: 39.916 },
zoom: 10
},
overview: true,
splitScreen: false
});
// 添加点实体
const point = new Map.Graphic.Point({
position: [116.397, 39.916],
style: {
color: 'red',
size: 10
}
});
map.addGraphic(point);
// 开始绘制
map.startDraw({
type: 'Line',
style: {
color: 'blue',
width: 2
},
onDrawEnd: (graphic) => {
console.log('绘制完成:', graphic);
}
});
```
### 使用管理器
```javascript
// 获取各个管理器
const entityManager = map.getEntityManager();
const drawManager = map.getDrawManager();
const mapController = map.getMapController();
const overviewManager = map.getOverviewManager();
// 使用实体管理器
const entities = entityManager.getEntities();
const entity = entityManager.findEntityById('entity-id');
// 使用地图控制器
mapController.flyTo({
center: [116.397, 39.916],
zoom: 15,
duration: 2000
});
// 控制鹰眼
overviewManager.show();
overviewManager.hide();
```
### 高级功能
```javascript
// 启用拖拽功能
const draggablePoint = new Map.Graphic.Point({
position: [116.397, 39.916],
draggable: true,
onDragStart: () => console.log('开始拖拽'),
onDragEnd: (position) => console.log('拖拽结束:', position)
});
// 添加带弹窗的实体
const popupPoint = new Map.Graphic.Point({
position: [116.397, 39.916],
popup: {
content: '标题
内容
',
maxWidth: 200
}
});
// 启用分屏模式
map.enableSplitScreen({
leftMap: { style: 'style1.json' },
rightMap: { style: 'style2.json' }
});
```
## 🎯 功能特性详解
### 实体拖拽
项目实现了完整的实体拖拽功能，解决了 MapLibre GL 符号图层拖拽时的闪烁问题：
- 使用 DOM 元素和 Marker 实现拖拽
- 支持拖拽状态管理
- 拖拽时自动禁用弹窗和右键菜单
- 支持拖拽回调函数
- 支持拖拽约束和限制
### 绘制工具
支持多种图形的动态绘制：
- **单点绘制**: 点击一次完成（如点、广告牌）
- **双点绘制**: 点击两次完成（如直线、箭头）
- **多点绘制**: 支持添加、删除点，双击完成（如多边形、曲线）
### 图形实体
支持丰富的图形实体类型：
- **基础图形**: 点、线、面、矩形
- **箭头图形**: 直线箭头、攻击箭头、双箭头、燕尾箭头
- **特殊图形**: 集结地、标签、广告牌
- **复合图形**: 复合广告牌线标签
### 特效功能
- **雨滴效果**: 可配置的雨滴动画效果
- **雪花效果**: 可配置的雪花动画效果
- **粒子背景**: 动态粒子背景效果
### 鹰眼功能
提供鹰眼小地图功能：
- 同步主地图视野范围
- 支持显示/隐藏控制
- 可自定义位置和大小
### UI组件
丰富的UI组件支持：
- 状态栏：显示地图状态信息
- 右键菜单：上下文操作菜单
- 弹窗：实体信息展示
- 绘制提示：绘制过程中的操作提示
## 开发指南
### 添加新的图形实体
1. 继承 `BaseGraphic` 类
2. 实现必要的方法（`render`, `remove` 等）
3. 在 `graphicRegistry` 中注册
4. 添加到 `Map.Graphic` 命名空间
```javascript
import { BaseGraphic } from './BaseGraphic.js';
export class CustomGraphic extends BaseGraphic {
render(map, draw) {
// 实现渲染逻辑
}
remove() {
// 实现清理逻辑
}
}
```
### 添加新的混入功能
1. 创建混入文件
2. 实现混入方法
3. 在实体类中应用混入
```javascript
// 创建混入
export const CustomMixin = {
customMethod() {
// 实现自定义方法
}
};
// 应用混入
Object.assign(CustomGraphic.prototype, CustomMixin);
```
### 扩展管理器功能
1. 在对应的管理器中添加新方法
2. 在主类中暴露新方法
3. 更新文档
## 🔧 配置选项
### 地图配置
```javascript
const mapConfig = {
style: 'map-style-url', // 地图样式URL
scene: { // 场景配置
center: { lng: 116.397, lat: 39.916 },
zoom: 10,
pitch: 0,
bearing: 0
},
overview: true, // 是否显示鹰眼
splitScreen: false, // 是否启用分屏
controls: { // 控件配置
navigation: true,
fullscreen: true,
geolocate: false
}
};
```
### 实体样式配置
```javascript
const entityStyle = {
color: '#ff0000', // 颜色
size: 10, // 大小
width: 2, // 线宽
opacity: 0.8, // 透明度
fillColor: '#00ff00', // 填充色
strokeColor: '#0000ff', // 描边色
strokeWidth: 1 // 描边宽度
};
```
## 📚 API 文档
详细的API文档请运行 `npm run doc` 生成，或查看 `docs/` 目录。
## 🤝 贡献指南
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
## 👥 作者
- **zhangp** - *初始工作* - [zhangp@example.com](mailto:zhangp@example.com)
## 🙏 致谢
- [MapLibre GL](https://maplibre.org/) - 开源地图渲染库
- [Vue.js](https://vuejs.org/) - 渐进式JavaScript框架
- [Element Plus](https://element-plus.org/) - Vue 3 UI组件库
- [Turf.js](https://turfjs.org/) - 地理空间分析库
## 🌐 浏览器支持
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+