# Cesium-Map

**Repository Path**: scedm/cesium-map

## Basic Information

- **Project Name**: Cesium-Map
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Cesium-Map, GIS

## README

# Cesium-Map

## 项目介绍

Cesium-Map 是一个基于 React + TypeScript + Cesium 的多源地图集成库，支持高德地图和百度地图的瓦片图层加载。

## Commands

```bash
npm run dev          # 启动开发服务器 (demo 目录)
npm run build        # 构建生产版本
npm run build:lib    # 构建库版本 (ES + UMD)
npm run lint         # ESLint 检查
npm run lint:fix     # ESLint 自动修复
npm run test         # 运行 Vitest 测试
npm run test:ui      # Vitest UI 界面
npm run type-check   # TypeScript 类型检查
```

## Architecture

### Core Pattern: Provider 模式

```
src/providers/
├── BaseImageryProvider.ts    # 抽象基类，定义 addToViewer/removeFromViewer 等方法
├── AmapImageryProvider.ts    # 高德地图实现
├── BaiduImageryProvider.ts   # 百度地图实现
└── index.ts                  # ImageryProviderFactory 工厂类
```

所有地图服务提供者继承 `BaseImageryProvider`，必须实现 `createImageryProvider()` 和 `getProviderName()` 抽象方法。

### Component Structure

```
src/components/
├── CesiumMap/           # 主地图组件，管理 Viewer 生命周期
├── MapControls/         # LayerSwitcher 图层切换控件
├── LayerManager/        # 多图层管理
├── OverlayTools/        # MarkerTool, PolylineTool, PolygonTool 标注工具
└── ErrorBoundary.tsx    # 错误边界
```

### Context & Hooks

- `CesiumContext`: 通过 Context API 共享 Viewer 实例
- `useCesium()`: 获取当前 Viewer 和 isReady 状态
- `useMapLayer()`: 图层管理 hook
- `useMapEvent()`: 事件绑定 hook

### Types

```
src/types/
├── provider.types.ts    # MapProvider, MapLayerType 枚举, ProviderConfig
├── map.types.ts         # Coordinate, MarkerStyle, PolylineStyle, PolygonStyle
├── component.types.ts   # 组件 Props 类型
└── error.types.ts       # 错误类型定义
```

## Key Implementation Notes

### Cesium Viewer 生命周期

在 `CesiumMap.tsx` 中，使用 `useRef` 存储 `onReady`/`onError` 回调以避免 useEffect 依赖导致的无限循环。在访问 viewer 属性（如 `viewer.scene`）前，必须先检查 `viewer.isDestroyed()`，因为 Cesium 的 getter 在 viewer 销毁后会抛出异常。

### 坐标系

- WGS84: GPS 原始坐标（Cesium 使用）
- GCJ02: 高德地图坐标（火星坐标）
- BD09: 百度地图坐标

使用 `CoordinateTransformer` 进行坐标转换。

### Demo 目录

`demo/` 目录包含示例应用，`npm run dev` 会启动 demo 作为开发预览。

## API Keys

地图服务 API Key 通过 `configManager.setConfig()` 配置，或直接传入 `ProviderConfig`。