bxztApp/packages/screen/src/map/README.md

# 🗺️ 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**