@gis_victory/gismap 1.0.57 → 2.0.0

package/README.md

@@ -1,350 +1,475 @@
-# @gis_victory/gismap 组件库
+# GISMap - 通用地图组件库
 
-一个基于 Vue 3 + TypeScript + Vite 开发的 GIS 地图组件库，提供丰富的地图交互功能和移动端适配。
+GISMap 是一个基于适配器模式设计的通用地图组件库，支持多种地图引擎（如 Mapbox GL、MapLibre 等），提供统一的 API 接口和丰富的功能模块。
 
 ## 特性
 
-- 📦 开箱即用的地图组件
-- 🎨 支持多种地图样式和图层
-- 📱 移动端适配
-- 🔍 地图搜索功能
-- 🎯 地图工具和控件
-- 📍 标记和弹窗
-- 📊 图例和数据可视化
-- 🔄 地图切换和扩展
+- **多引擎支持**：通过适配器模式，支持不同的地图引擎
+- **丰富的管理器**：提供图层、标记、雷达、地形、绘制、测量等多种管理器
+- **响应式设计**：基于 Vue 3 的 Composition API，提供响应式的地图状态管理
+- **模块化架构**：清晰的代码结构，易于扩展和维护
+- **TypeScript 支持**：完整的类型定义，提供良好的开发体验
 
 ## 安装
 
 ```bash
-npm install @gis_victory/gismap
-# 或
-yarn add @gis_victory/gismap
+# 使用 npm
+npm install gismap
+
+# 使用 yarn
+yarn add gismap
+
+# 使用 pnpm
+pnpm add gismap
 ```
 
-## 快速开始
+## 基本使用
 
-### 基础使用
+### 1. 基础地图组件
 
 ```vue
 <template>
-  <MapContainer 
-    :mapViewData="mapViewData" 
-    :switchData="switchData" 
-    :layerData="layerData"
-    :toolsData="toolsData" 
-    :searchData="searchData" 
-    @load="onMapLoad"
-  >
-    <!-- 自定义插槽内容 -->
-    <template #bottom-left>
-      <GisMapCompass />
-    </template>
-  </MapContainer>
+  <div style="width: 100vw; height: 100vh;">
+    <GisMapContainer
+      :center="[120, 30]"
+      :zoom="10"
+      :access-token="'your-mapbox-access-token'"
+      :init-icons="initIcons"
+    >
+      <!-- 可以在这里添加地图控件 -->
+    </GisMapContainer>
+  </div>
 </template>
 
 <script setup lang="ts">
-import { ref, reactive } from 'vue';
-import { MapContainer, GisMapCompass, GSMap } from '@gis_victory/gismap';
-
-const mapViewData = reactive({
-  zoom: 9,
-  center: [120.65677441301864, 29.745141743380103],
-  style: {
-    glyphs: "http://www.gisx.work/map-assets/fonts/{fontstack}/{range}.pbf",
+import { GisMapContainer } from 'gismap';
+
+// 初始化图标配置
+const initIcons = [
+  {
+    name: 'marker-icon',
+    url: 'https://example.com/marker.png'
   },
-  icons: [
-    {
-      name: 'point',
-      label: "点",
-      url: 'assets/icons/point.png',
+  {
+    name: 'icon-2',
+    url: 'https://example.com/icon2.png'
+  }
+];
+</script>
+```
+
+### 2. 使用组合式函数
+
+```vue
+<template>
+  <div style="width: 100vw; height: 100vh;">
+    <GisMapContainer @ready="handleMapReady">
+      <button @click="addMarker" style="position: absolute; top: 10px; left: 10px; z-index: 1000;">
+        添加标记
+      </button>
+    </GisMapContainer>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { GisMapContainer } from 'gismap';
+import { useMap, useMarker, useLayer } from 'gismap';
+
+const { map, layers, markers } = useMap();
+
+const handleMapReady = () => {
+  console.log('地图就绪');
+};
+
+const addMarker = () => {
+  // 添加标记
+  markers.value.add({
+    id: `marker-${Date.now()}`,
+    position: [120, 30],
+    options: {
+      draggable: true
+    }
+  });
+};
+</script>
+```
+
+## 核心功能
+
+### 1. 图层管理
+
+```typescript
+import { useLayers } from 'gismap';
+
+const { addLayer, removeLayer, layers } = useLayers();
+
+// 添加 GeoJSON 图层
+const layer = addLayer({
+  id: 'points',
+  type: 'circle',
+  source: {
+    type: 'geojson',
+    data: {
+      type: 'FeatureCollection',
+      features: [
+        {
+          type: 'Feature',
+          geometry: {
+            type: 'Point',
+            coordinates: [120, 30]
+          }
+        }
+      ]
     }
-    // 更多图标配置...
-  ]
+  },
+  paint: {
+    'circle-radius': 10,
+    'circle-color': '#ff0000'
+  }
 });
 
-const switchData = reactive({
-  layers: [{
-    name: "tdt-vec",
-    label: "标准地图",
-    iconName: "vector",
-    checked: true
-  }, {
-    name: "tdt-img",
-    label: "卫星影像",
-    iconName: "satellite",
-    checked: false
-  }],
-  extensions: [{
-    name: "tdt-cia",
-    label: "注记",
-    checked: true,
-  }]
+// 移除图层
+removeLayer(layer.id);
+```
+
+### 2. 标记管理
+
+```typescript
+import { useMarkers } from 'gismap';
+
+const { add, remove, getAll } = useMarkers();
+
+// 添加标记
+const marker = add({
+  id: 'marker-1',
+  position: [120, 30],
+  options: {
+    draggable: true,
+    anchor: 'bottom'
+  }
 });
 
-const layerData = ref([]);
-const toolsData = ref([]);
-const searchData = ref([]);
+// 移除标记
+remove('marker-1');
 
-const onMapLoad = (map: GSMap) => {
-  console.log('地图加载完成:', map);
-  // 地图操作逻辑...
-};
-</script>
+// 获取所有标记
+const allMarkers = getAll();
 ```
 
-## 组件列表
+### 3. 绘制功能
 
-### 核心组件
+```typescript
+import { useDraw } from 'gismap';
 
-| 组件名 | 描述 | 示例 |
-|-------|------|------|
-| `MapContainer` | 地图容器，包含所有地图组件 | `<MapContainer :mapViewData="mapViewData" @load="onMapLoad" />` |
-| `GisMapView` | 地图视图组件 | `<GisMapView :mapViewData="mapViewData" />` |
-| `GisMapLayer` | 地图图层管理组件 | `<GisMapLayer :layerData="layerData" />` |
-| `GisMapLegend` | 地图图例组件 | `<GisMapLegend />` |
-| `GisMapTools` | 地图工具组件 | `<GisMapTools :toolsData="toolsData" />` |
-| `GisMapSwitch` | 地图切换组件 | `<GisMapSwitch :switchData="switchData" />` |
-| `GisMapSearch` | 地图搜索组件 | `<GisMapSearch :searchData="searchData" />` |
+const { startDraw, stopDraw, isDrawing, selected } = useDraw();
 
-### 工具组件
+// 开始绘制多边形
+startDraw('polygon', (type, geoJson, wkt, feature) => {
+  console.log('绘制完成:', type, geoJson, wkt);
+});
 
-| 组件名 | 描述 | 示例 |
-|-------|------|------|
-| `GisMapCompass` | 地图指南针组件 | `<GisMapCompass />` |
-| `GisMapPopupBar` | 弹窗工具栏组件 | `<GisMapPopupBar>` |
-| `GisMapPopupBarItem` | 弹窗工具栏项组件 | `<GisMapPopupBarItem label="示例" />` |
+// 停止绘制
+stopDraw();
+```
 
-### 移动端组件
+### 4. 测量功能
 
-| 组件名 | 描述 | 示例 |
-|-------|------|------|
-| `MobileMapLayer` | 移动端地图图层组件 | `<MobileMapLayer>` |
-| `MobileBaseLayerSwitch` | 移动端底图切换组件 | `<MobileBaseLayerSwitch :data="layersData" />` |
+```typescript
+import { useMeasure } from 'gismap';
 
-## API 文档
+const { startMeasure, stopMeasure, isMeasuring, results } = useMeasure();
 
-### MapContainer 组件
+// 开始测量距离
+startMeasure('line', (result) => {
+  console.log('测量结果:', result.value, result.unit);
+});
 
-#### Props
+// 停止测量
+stopMeasure();
+```
 
-| 属性名 | 类型 | 描述 | 默认值 |
-|-------|------|------|--------|
-| `mapViewData` | `Object` | 地图视图配置 | `{}` |
-| `switchData` | `Object` | 地图切换配置 | `{}` |
-| `layerData` | `Array` | 图层数据 | `[]` |
-| `toolsData` | `Array` | 工具数据 | `[]` |
-| `searchData` | `Array` | 搜索数据 | `[]` |
+### 5. 雷达图层
 
-#### Events
+```typescript
+import { useMap } from 'gismap';
 
-| 事件名 | 参数 | 描述 |
-|-------|------|------|
-| `load` | `map: GSMap` | 地图加载完成事件 |
+const { radarManager } = useMap();
 
-#### Slots
+// 添加雷达
+radarManager.value?.add({
+  center: [120, 30],
+  radius: 500,
+  sectorVisible: true,
+  sectorAngle: 45
+});
 
-| 插槽名 | 描述 |
-|-------|------|
-| `bottom-left` | 地图左下角插槽 |
-| `bottom-right` | 地图右下角插槽 |
-| `top-left` | 地图左上角插槽 |
-| `top-right` | 地图右上角插槽 |
+// 开始扫描
+radarManager.value?.startScan();
 
-### GSMap 实例
+// 停止扫描
+radarManager.value?.stopScan();
 
-#### 方法
+// 移除雷达
+radarManager.value?.remove();
+```
 
-| 方法名 | 参数 | 描述 |
-|-------|------|------|
-| `pubsub.on` | `event: string, callback: Function` | 订阅地图事件 |
-| `pubsub.emit` | `event: string, data: any` | 发布地图事件 |
-| `manager.templateManager.add` | `id: string, template: string` | 添加模板 |
-| `manager.maskManager.add` | `data: string` | 添加遮罩 |
+### 6. 地形管理
 
-## 配置项
+```typescript
+import { useMap } from 'gismap';
 
-### mapViewData 配置
+const { terrainManager } = useMap();
 
-```javascript
-{
-  zoom: 9, // 初始缩放级别
-  center: [120.65677441301864, 29.745141743380103], // 初始中心点坐标
-  style: {
-    glyphs: "http://www.gisx.work/map-assets/fonts/{fontstack}/{range}.pbf", // 字体配置
+// 添加地形
+terrainManager.value?.add({
+  source: {
+    tiles: ['https://example.com/terrain/{z}/{x}/{y}.png'],
+    minzoom: 0,
+    maxzoom: 14
   },
-  icons: [ // 图标配置
-    {
-      name: 'point', // 图标名称
-      label: "点", // 图标标签
-      url: 'assets/icons/point.png', // 图标路径
-    }
-  ]
-}
+  layer: {
+    exaggeration: 1.5
+  }
+});
+
+// 添加山体阴影
+terrainManager.value?.addHillshade();
+
+// 移除地形
+terrainManager.value?.remove();
 ```
 
-### switchData 配置
+### 7. 图标管理
 
-```javascript
-{
-  layers: [ // 底图配置
-    {
-      name: "tdt-vec", // 图层名称
-      label: "标准地图", // 图层标签
-      iconName: "vector", // 图标名称
-      checked: true // 是否默认选中
-    }
-  ],
-  extensions: [ // 扩展配置
-    {
-      name: "tdt-cia", // 扩展名称
-      label: "注记", // 扩展标签
-      checked: true, // 是否默认选中
-      config: { // 扩展配置
-        source: {
-          tiles: ["http://www.gisx.work/tiles/dem/{z}_{x}_{y}.webp"]
+#### 最佳实践：在地图初始化完成后立即加载图标
+
+为了确保地图能够正确读取图标，应该在地图初始化完成后立即加载图标。推荐使用 `useMapReady` 组合式函数来监听地图就绪事件：
+
+```typescript
+import { useMapReady } from 'gismap';
+
+// 在地图就绪后立即加载图标
+useMapReady(async (context) => {
+  try {
+    // 批量加载图标
+    await context.iconManager?.load([
+      {
+        name: 'marker-icon',
+        url: 'https://example.com/marker.png'
+      },
+      {
+        name: 'icon-2',
+        url: 'https://example.com/icon2.png'
+      }
+    ], {
+      batchSize: 5, // 每批加载5个图标
+      batchInterval: 100, // 每批间隔100毫秒
+      onProgress: (loaded, total) => {
+        console.log(`加载进度: ${loaded}/${total}`);
+      }
+    });
+    
+    console.log('图标加载完成');
+    
+    // 图标加载完成后，再添加使用图标的图层
+    addIconLayer(context);
+  } catch (error) {
+    console.error('图标加载失败:', error);
+  }
+});
+
+// 添加使用图标的图层
+function addIconLayer(context) {
+  if (context?.layerManager) {
+    context.layerManager.addLayer({
+      id: 'icon-layer',
+      type: 'symbol',
+      source: {
+        type: 'geojson',
+        data: {
+          type: 'FeatureCollection',
+          features: [
+            {
+              type: 'Feature',
+              geometry: {
+                type: 'Point',
+                coordinates: [120, 30]
+              }
+            }
+          ]
         }
+      },
+      layout: {
+        'icon-image': 'marker-icon', // 使用已加载的图标
+        'icon-size': 1.5
       }
-    }
-  ]
+    });
+  }
 }
 ```
 
-## 示例
+#### 其他用法
 
-### 完整示例
+```typescript
+import { useMap } from 'gismap';
 
-```vue
-<template>
-  <MapContainer 
-    :mapViewData="mapViewData" 
-    :switchData="switchData" 
-    :layerData="layerData"
-    :toolsData="toolsData" 
-    :searchData="searchData" 
-    @load="onMapLoad"
-  >
-    <template #bottom-left>
-      <GisMapCompass />
-    </template>
-    <template #top-right>
-      <MobileMapLayer>
-        <MobileBaseLayerSwitch :data="switchData.layers" />
-      </MobileMapLayer>
-    </template>
-  </MapContainer>
-</template>
+const { iconManager } = useMap();
 
-<script setup lang="ts">
-import { ref, reactive, onMounted } from 'vue';
-import { MapContainer, GisMapCompass, GSMap, MobileMapLayer, MobileBaseLayerSwitch } from '@gis_victory/gismap';
-
-const mapViewData = reactive({
-  zoom: 9,
-  center: [120.65677441301864, 29.745141743380103],
-  style: {
-    glyphs: "http://www.gisx.work/map-assets/fonts/{fontstack}/{range}.pbf",
+// 批量加载图标（基本用法）
+iconManager.value?.load([
+  {
+    name: 'marker-icon',
+    url: 'https://example.com/marker.png'
   },
-  icons: [
-    {
-      name: 'point',
-      label: "点",
-      url: 'assets/icons/point.png',
-    }
-  ]
+  {
+    name: 'icon-2',
+    url: 'https://example.com/icon2.png'
+  }
+]).then(() => {
+  console.log('图标加载完成');
 });
 
-const switchData = reactive({
-  layers: [{
-    name: "tdt-vec",
-    label: "标准地图",
-    iconName: "vector",
-    checked: true
-  }, {
-    name: "tdt-img",
-    label: "卫星影像",
-    iconName: "satellite",
-    checked: false
-  }],
-  extensions: [{
-    name: "tdt-cia",
-    label: "注记",
-    checked: true,
-  }]
+// 加载单个图标
+iconManager.value?.loadOne({
+  name: 'single-icon',
+  url: 'https://example.com/single.png'
+}).then(() => {
+  console.log('单个图标加载完成');
 });
 
-const layerData = ref([]);
-const toolsData = ref([]);
-const searchData = ref([]);
-
-let map: GSMap;
-const onMapLoad = (_map: GSMap) => {
-  map = _map;
-  // 地图加载完成后的操作
-  map.pubsub.on('layer:click', ({ templateId, feature }: { templateId: string, feature: any }) => {
-    const template = map.manager?.templateManager?.renderHtml(templateId, feature.properties);
-    if (template) {
-      map.manager?.popupManager.show({
-        position: feature.geometry.coordinates,
-        html: template,
-      });
-    }
-  });
-};
+// 检查图标是否已加载
+if (iconManager.value?.hasIcon('marker-icon')) {
+  console.log('图标已加载');
+}
 
-// 初始化数据
-onMounted(() => {
-  // 这里可以加载图层数据、工具数据和搜索数据
-});
-</script>
+// 移除图标
+iconManager.value?.removeIcon('marker-icon');
+
+// 清除所有图标记录
+iconManager.value?.clear();
 ```
 
-## 开发指南
+## 高级功能
 
-### 本地开发
+### 1. 自定义适配器
 
-1. 克隆仓库
+您可以通过实现 `MapAdapter` 或 `VectorTileAdapter` 接口来创建自定义适配器，支持其他地图引擎。
 
-```bash
-git clone <repository-url>
-cd gismap
-```
+```typescript
+import type { MapAdapter, MapInitOptions, MapViewState } from 'gismap';
 
-2. 安装依赖
+export class MyCustomAdapter implements MapAdapter {
+  private map: any = null;
 
-```bash
-npm install
+  async initialize(container: HTMLElement, options: MapInitOptions): Promise<void> {
+    // 初始化您的地图引擎
+    // this.map = new MyMapEngine(container, options);
+  }
+
+  dispose(): void {
+    // 清理资源
+  }
+
+  getMap(): any {
+    return this.map;
+  }
+
+  // 实现其他必要的方法...
+}
+
+// 使用自定义适配器
+<GisMapContainer :adapter="new MyCustomAdapter()" />
 ```
 
-3. 启动开发服务器
+### 2. 扩展管理器
 
-```bash
-npm run dev
+您可以通过继承现有管理器或创建新的管理器来扩展功能。
+
+```typescript
+import { VectorTileAdapter } from 'gismap';
+
+export class CustomManager {
+  private adapter: VectorTileAdapter;
+
+  constructor(adapter: VectorTileAdapter) {
+    this.adapter = adapter;
+  }
+
+  // 实现您的自定义功能
+  doSomething() {
+    // 使用 this.adapter 操作地图
+  }
+}
 ```
 
-4. 构建生产版本
+### 3. 事件系统
 
-```bash
-npm run build
+GISMap 提供了完善的事件系统，您可以监听各种地图事件。
+
+```typescript
+import { useMapEvent } from 'gismap';
+
+// 监听地图点击事件
+useMapEvent('click', (event) => {
+  console.log('地图点击:', event.coordinates);
+});
+
+// 监听视图变化事件
+useMapEvent('viewChange', (view) => {
+  console.log('视图变化:', view);
+});
 ```
 
-### 发布版本
+## 项目结构
 
-```bash
-# 更新版本号
-npm version patch
-# 构建
-npm run build
-# 发布
-npm publish
+```
+src/
+├── adapters/          # 地图适配器
+│   ├── mapbox/        # Mapbox GL 适配器
+│   ├── types.ts       # 适配器类型定义
+│   └── index.ts       # 适配器统一导出
+├── components/        # Vue 组件
+│   ├── MapContainer/  # 地图容器组件
+│   └── ...
+├── composables/       # 组合式函数
+│   ├── useMap.ts      # 地图核心组合式函数
+│   ├── useLayer.ts    # 图层组合式函数
+│   └── ...
+├── core/              # 核心功能
+│   ├── event.ts       # 事件系统
+│   ├── StateStore.ts  # 状态管理
+│   └── ...
+├── domain/            # 领域服务
+│   ├── LayerService.ts    # 图层服务
+│   ├── MarkerService.ts   # 标记服务
+│   └── ...
+├── manager/           # 管理器
+│   ├── mapbox/        # Mapbox 专用管理器
+│   ├── layer/         # 图层相关
+│   ├── LayerManager.ts    # 图层管理器
+│   ├── RadarManager.ts    # 雷达管理器
+│   └── ...
+├── services/          # 服务
+│   ├── MapContext.ts  # 地图上下文
+│   └── ...
+└── index.ts           # 主入口
 ```
 
 ## 浏览器兼容性
 
-- Chrome (最新版本)
-- Firefox (最新版本)
-- Safari (最新版本)
-- Edge (最新版本)
+- Chrome/Edge >= 88
+- Firefox >= 85
+- Safari >= 14
 
 ## 许可证
 
 MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 联系方式
+
+- 项目地址：https://github.com/your-username/gismap
+- 问题反馈：https://github.com/your-username/gismap/issues