Zzc
67f9653829
* 将 `SvgIcon` 组件移至 `map/shared/SvgIcon` * 将地图图标迁移至 `map/assets/icons` * 更新组件导入，使用 `MapIcon` 替代 `svg-icon` * 为 Cesium 地图 SDK 添加详尽的 `README.md` * 更新 vite 配置，纳入新的图标目录 * 移除 `main.js` 中的 `SvgIcon` 导入
390 lines
7.8 KiB
Markdown
390 lines
7.8 KiB
Markdown
# 🗺️ Cesium 地图 SDK
|
||
|
||
基于 Cesium 的 Vue 3 地图组件库，提供完整的地图交互、图层管理、底图切换等功能。
|
||
|
||
## ✨ 特性
|
||
|
||
- 🎯 **完全自包含** - 所有依赖集成在 `/map` 目录内
|
||
- 🚀 **开箱即用** - 复制目录即可使用，无需额外配置
|
||
- 📦 **模块化设计** - 组件化架构，灵活组合
|
||
- 🎨 **UI 集成** - 内置精美的地图控件 UI
|
||
- 🔧 **TypeScript 友好** - 完整的类型支持（计划中）
|
||
- 🌍 **多底图支持** - 天地图、ArcGIS、Cesium Ion 等
|
||
|
||
## 📦 核心组件
|
||
|
||
### 地图容器
|
||
- **MapViewport** - 地图视口容器，Cesium Viewer 初始化
|
||
- **MapControls** - 地图控制面板容器
|
||
|
||
### 交互控件
|
||
- **BaseMapSwitcher** - 底图切换器
|
||
- **LayerDirectoryControl** - 图层目录管理
|
||
- **MapCompass** - 指南针导航
|
||
- **SceneModeToggle** - 2D/3D 场景切换
|
||
|
||
### 工具组件
|
||
- **MapIcon** - SVG 图标组件
|
||
|
||
### 状态管理
|
||
- **useMapStore** - 地图核心状态管理
|
||
- **useMapUiStore** - 地图 UI 状态管理
|
||
|
||
### Composables
|
||
- **useMapViewSnapshot** - 地图视图快照管理
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 复制模块
|
||
|
||
```bash
|
||
# 复制整个地图模块到你的项目
|
||
cp -r src/map /your-project/src/
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
# 核心依赖
|
||
npm install cesium@^1.135.0
|
||
npm install vite-plugin-cesium@^1.2.22
|
||
npm install vite-plugin-svg-icons@^2.0.1
|
||
|
||
# Vue 生态（如果项目中没有）
|
||
npm install vue@^3.5.0 pinia@^3.0.0
|
||
npm install element-plus@^2.0.0
|
||
npm install vue-router@^4.0.0
|
||
```
|
||
|
||
### 3. Vite 配置
|
||
|
||
```javascript
|
||
// vite.config.js
|
||
import { defineConfig } from 'vite'
|
||
import vue from '@vitejs/plugin-vue'
|
||
import cesium from 'vite-plugin-cesium'
|
||
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
|
||
import { resolve } from 'path'
|
||
|
||
export default defineConfig({
|
||
plugins: [
|
||
vue(),
|
||
cesium(),
|
||
createSvgIconsPlugin({
|
||
iconDirs: [resolve(__dirname, 'src/map/assets/icons')],
|
||
symbolId: 'icon-[name]'
|
||
})
|
||
],
|
||
define: {
|
||
CESIUM_BASE_URL: JSON.stringify('/cesium')
|
||
},
|
||
resolve: {
|
||
alias: {
|
||
'@': resolve(__dirname, 'src')
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
### 4. 主入口配置
|
||
|
||
```javascript
|
||
// main.js
|
||
import { createApp } from 'vue'
|
||
import { createPinia } from 'pinia'
|
||
import ElementPlus from 'element-plus'
|
||
import 'element-plus/dist/index.css'
|
||
import 'cesium/Build/Cesium/Widgets/widgets.css'
|
||
import 'virtual:svg-icons-register'
|
||
import App from './App.vue'
|
||
|
||
const app = createApp(App)
|
||
app.use(createPinia())
|
||
app.use(ElementPlus)
|
||
app.mount('#app')
|
||
```
|
||
|
||
### 5. 使用示例
|
||
|
||
```vue
|
||
<template>
|
||
<div class="map-container">
|
||
<MapViewport />
|
||
<MapControls />
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { MapViewport, MapControls } from '@/map'
|
||
import { useMapStore } from '@/map'
|
||
import { onMounted } from 'vue'
|
||
|
||
const mapStore = useMapStore()
|
||
|
||
onMounted(() => {
|
||
// 等待地图加载完成
|
||
mapStore.onReady(() => {
|
||
console.log('地图已就绪')
|
||
|
||
// 获取地图服务
|
||
const { camera, layer } = mapStore.services()
|
||
|
||
// 飞行到指定位置
|
||
camera.setCenter(116.4074, 39.9042, 10000)
|
||
})
|
||
})
|
||
</script>
|
||
|
||
<style scoped>
|
||
.map-container {
|
||
width: 100vw;
|
||
height: 100vh;
|
||
position: relative;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 API 文档
|
||
|
||
### MapViewport
|
||
|
||
地图视口容器，负责初始化 Cesium Viewer。
|
||
|
||
**Props:** 无
|
||
|
||
**Events:** 无
|
||
|
||
**说明：**
|
||
- 自动初始化 Cesium Viewer
|
||
- 配置地图基础参数（地形、场景模式等）
|
||
- 加载默认底图
|
||
- 注入 mapStore 实例
|
||
|
||
### MapControls
|
||
|
||
地图控制面板容器，包含所有交互控件。
|
||
|
||
**Props:** 无
|
||
|
||
**使用示例：**
|
||
```vue
|
||
<MapControls />
|
||
```
|
||
|
||
### useMapStore()
|
||
|
||
地图核心状态管理 Store。
|
||
|
||
**主要方法：**
|
||
- `init(viewer)` - 初始化地图实例
|
||
- `onReady(callback)` - 地图就绪回调
|
||
- `services()` - 获取地图服务（camera, layer, entity, query）
|
||
- `destroy()` - 销毁地图实例
|
||
|
||
**使用示例：**
|
||
```javascript
|
||
import { useMapStore } from '@/map'
|
||
|
||
const mapStore = useMapStore()
|
||
|
||
// 等待地图就绪
|
||
mapStore.onReady(() => {
|
||
const { camera, layer } = mapStore.services()
|
||
|
||
// 添加图层
|
||
layer.addLayer({
|
||
id: 'my-layer',
|
||
type: 'WmtsServiceLayer',
|
||
url: 'https://...',
|
||
options: { visible: true }
|
||
})
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 高级配置
|
||
|
||
### 底图配置
|
||
|
||
编辑 `src/map/data/baseMap.json` 配置底图服务：
|
||
|
||
```json
|
||
{
|
||
"Groups": [
|
||
{
|
||
"Attribute": {
|
||
"rid": "tianditu-group",
|
||
"name": "天地图",
|
||
"sortValue": 1
|
||
},
|
||
"Children": [
|
||
{
|
||
"Attribute": {
|
||
"rid": "tianditu-img",
|
||
"name": "天地图影像",
|
||
"serviceTypeName": "TiandituImgLayer",
|
||
"servicePath": "http://t{s}.tianditu.gov.cn/img_w/wmts?...",
|
||
"sortValue": 1
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 图层目录配置
|
||
|
||
编辑 `src/map/data/layerMap.json` 配置图层目录：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"Name": "业务图层",
|
||
"Rid": "business-layers",
|
||
"Children": [
|
||
{
|
||
"Name": "我的图层",
|
||
"Attribute": {
|
||
"rid": "my-layer-001",
|
||
"serviceTypeName": "WmtsServiceLayer",
|
||
"servicePath": "https://..."
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
```bash
|
||
# .env
|
||
VITE_CESIUM_ION_TOKEN=your_cesium_ion_token
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 目录结构
|
||
|
||
```
|
||
src/map/
|
||
├── components/ # 地图组件
|
||
│ ├── MapViewport.vue # 地图视口
|
||
│ ├── MapControls.vue # 控制面板
|
||
│ ├── BaseMapSwitcher.vue # 底图切换器
|
||
│ ├── LayerDirectoryControl.vue # 图层目录
|
||
│ ├── MapCompass.vue # 指南针
|
||
│ └── SceneModeToggle.vue # 场景切换
|
||
├── services/ # 地图服务
|
||
│ ├── createCameraService.js # 相机服务
|
||
│ ├── createLayerService.js # 图层服务
|
||
│ ├── createEntityService.js # 实体服务
|
||
│ └── createQueryService.js # 查询服务
|
||
├── stores/ # 状态管理
|
||
│ ├── mapStore.js # 地图状态
|
||
│ └── mapUiStore.js # UI 状态
|
||
├── composables/ # 组合式函数
|
||
│ └── useMapViewSnapshot.js
|
||
├── shared/ # 共享组件
|
||
│ └── SvgIcon/ # 图标组件
|
||
├── assets/ # 资源文件
|
||
│ └── icons/ # SVG 图标
|
||
├── data/ # 配置数据
|
||
│ ├── baseMap.json # 底图配置
|
||
│ ├── mapBaseConfig.json # 地图配置
|
||
│ └── layerMap.json # 图层目录
|
||
├── utils/ # 工具函数
|
||
│ ├── pickPosition.js
|
||
│ └── utils.js
|
||
├── index.js # 导出入口
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
---
|
||
|
||
## 🌍 浏览器支持
|
||
|
||
- Chrome >= 90
|
||
- Firefox >= 88
|
||
- Safari >= 14
|
||
- Edge >= 90
|
||
|
||
**注意：** Cesium 需要 WebGL 2.0 支持。
|
||
|
||
---
|
||
|
||
## 📝 依赖清单
|
||
|
||
### PeerDependencies
|
||
|
||
```json
|
||
{
|
||
"cesium": "^1.135.0",
|
||
"vue": "^3.5.0",
|
||
"pinia": "^3.0.0",
|
||
"element-plus": "^2.0.0",
|
||
"vue-router": "^4.0.0"
|
||
}
|
||
```
|
||
|
||
### DevDependencies
|
||
|
||
```json
|
||
{
|
||
"vite-plugin-cesium": "^1.2.22",
|
||
"vite-plugin-svg-icons": "^2.0.1"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔨 开发指南
|
||
|
||
### 添加新组件
|
||
|
||
1. 在 `components/` 创建新组件
|
||
2. 在 `index.js` 导出组件
|
||
3. 更新本 README 文档
|
||
|
||
### 添加新服务
|
||
|
||
1. 在 `services/` 创建服务文件
|
||
2. 在 `mapStore.js` 中注册服务
|
||
3. 提供完整的 JSDoc 注释
|
||
|
||
### 添加新图标
|
||
|
||
1. 将 SVG 文件放到 `assets/icons/`
|
||
2. 使用 `<MapIcon icon-class="your-icon" />` 引用
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
## 📮 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
|
||
- Issue: [GitHub Issues](#)
|
||
- Email: [your-email@example.com](#)
|
||
|
||
---
|
||
|
||
**Generated with ❤️ by Cesium Map SDK Team**
|