bxztApp/packages/screen/src/map

🗺️ 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. 复制模块

# 复制整个地图模块到你的项目
cp -r src/map /your-project/src/

2. 安装依赖

# 核心依赖
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 配置

// 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. 主入口配置

// 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. 使用示例

<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: 无

使用示例：

<MapControls />

useMapStore()

地图核心状态管理 Store。

主要方法：

• init(viewer) - 初始化地图实例
• onReady(callback) - 地图就绪回调
• services() - 获取地图服务（camera, layer, entity, query）
• destroy() - 销毁地图实例

使用示例：

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 配置底图服务：

{
  "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 配置图层目录：

[
  {
    "Name": "业务图层",
    "Rid": "business-layers",
    "Children": [
      {
        "Name": "我的图层",
        "Attribute": {
          "rid": "my-layer-001",
          "serviceTypeName": "WmtsServiceLayer",
          "servicePath": "https://..."
        }
      }
    ]
  }
]

环境变量

# .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

{
  "cesium": "^1.135.0",
  "vue": "^3.5.0",
  "pinia": "^3.0.0",
  "element-plus": "^2.0.0",
  "vue-router": "^4.0.0"
}

DevDependencies

{
  "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