gdmap-utils 1.2.3 → 1.2.5

package/scripts/mergeDocs.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const path = require('path');
+
+const docsDir = path.join(__dirname, '../docs');
+const srcDir = path.join(__dirname, '../src');
+const outputFile = path.join(docsDir, 'COMPLETE_API.md');
+
+// 读取README.md作为文档头部
+const readmePath = path.join(docsDir, 'README.md');
+let readmeContent = '';
+if (fs.existsSync(readmePath)) {
+  readmeContent = fs.readFileSync(readmePath, 'utf8');
+}
+
+// 要处理的源文件
+const sourceFiles = [
+  {
+    path: path.join(srcDir, 'layers', 'baseMarkerLayer', 'index.ts'),
+    name: 'BaseMarkerLayer'
+  },
+  {
+    path: path.join(srcDir, 'layers', 'clusterMarkerLayer', 'index.ts'),
+    name: 'ClusterMarkerLayer'
+  }
+];
+
+// 从TypeScript源文件中提取文档注释
+function extractDocumentationFromSource(filePath, className) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  let documentation = '';
+  
+  // 提取类文档注释
+  const classCommentMatch = content.match(/\/\*\*[\s\S]*?\*\/\s*class\s+\w+/);
+  if (classCommentMatch) {
+    documentation += classCommentMatch[0].replace(/class\s+\w+/, '') + '\n\n';
+  }
+  
+  // 提取构造函数
+  const constructorMatch = content.match(/constructor\s*\([^)]*\)\s*\{/);
+  if (constructorMatch) {
+    let constructorStr = constructorMatch[0].replace(/\{/, '');
+    // 移除类型注解
+    constructorStr = constructorStr.replace(/:\s*[^,]+/g, '');
+    documentation += '## Constructors\n\n';
+    documentation += '### Constructor\n';
+    documentation += `> **new ${className}**${constructorStr}\n\n`;
+  }
+  
+  // 提取属性（去重）
+  const propertiesMatch = content.match(/\w+:\s*[^;]+;/g);
+  if (propertiesMatch) {
+    const uniqueProps = [...new Set(propertiesMatch.map(prop => prop.match(/\w+/)[0]))];
+    documentation += '## Properties\n\n';
+    uniqueProps.forEach(propName => {
+      documentation += `### ${propName}\n`;
+      documentation += `> **${propName}**\n\n`;
+    });
+  }
+  
+  // 提取方法
+  const methodMatch = content.match(/\w+\s*\([^)]*\)\s*[:{]/g);
+  if (methodMatch) {
+    documentation += '## Methods\n\n';
+    methodMatch.forEach(method => {
+      const methodName = method.match(/\w+/)[0];
+      if (methodName !== 'constructor') {
+        let methodStr = method.replace(/:\s*$/, '');
+        // 移除类型注解
+        methodStr = methodStr.replace(/:\s*[^,]+/g, '');
+        documentation += `### ${methodName}\n`;
+        documentation += `> **${methodName}**${methodStr.replace(methodName, '')}\n\n`;
+      }
+    });
+  }
+  
+  return documentation;
+}
+
+// 合并所有文档
+function mergeDocs() {
+  console.log('开始合并文档...');
+  
+  // 构建文档内容
+  let mergedContent = '';
+  
+  // 添加README内容
+  if (readmeContent) {
+    mergedContent += readmeContent + '\n\n';
+    mergedContent += '---\n\n';
+    mergedContent += '# API 文档\n\n';
+  }
+  
+  // 添加目录
+  mergedContent += '## 目录\n\n';
+  sourceFiles.forEach(file => {
+    mergedContent += `- [${file.name}](#${file.name.toLowerCase()})\n`;
+  });
+  mergedContent += '\n---\n\n';
+  
+  // 添加各个文档内容
+  sourceFiles.forEach(file => {
+    const documentation = extractDocumentationFromSource(file.path, file.name);
+    
+    mergedContent += `## ${file.name}\n\n`;
+    mergedContent += `<a id="${file.name.toLowerCase()}"></a>\n\n`;
+    mergedContent += documentation + '\n\n';
+    mergedContent += '---\n\n';
+  });
+  
+  // 移除末尾多余的分隔符
+  mergedContent = mergedContent.replace(/\n*\*\*\n*$/, '');
+  
+  // 添加生成信息
+  mergedContent += '\n\n---\n\n';
+  mergedContent += `*最后更新时间: ${new Date().toLocaleString('zh-CN')}*`;
+  
+  // 写入合并后的文档
+  fs.writeFileSync(outputFile, mergedContent, 'utf8');
+  console.log(`文档合并完成: ${outputFile}`);
+  console.log(`总字数: ${mergedContent.length}`);
+}
+
+// 执行合并
+try {
+  mergeDocs();
+} catch (error) {
+  console.error('文档合并失败:', error);
+  process.exit(1);
+}

package/src/LayerManager.ts

@@ -2,6 +2,7 @@ import type {
   BaseMarkerLayerClass,
   ClusterMarkerLayerClass,
 } from '@/layers/index.ts';
+import { MapUtils } from '@/MapUtils';
 
 type LayerIns =
   | InstanceType<BaseMarkerLayerClass>
@@ -11,7 +12,8 @@ export class LayerManager {
 
   addLayer(layer: LayerIns) {
     if (this.hasLayer(layer)) {
-      throw new Error(`Layer with name "${layer.layerName}" already exists`);
+      const errorMsg = `Layer with name "${layer.layerName}" already exists`;
+      return MapUtils.error(errorMsg);
     }
     this.layers.set(layer.layerName, layer);
   }
@@ -24,6 +26,9 @@ export class LayerManager {
     let layer = this.layers.get(LayerName);
     if (layer) {
       layer.show();
+    } else {
+      const errorMsg = `Layer with name "${LayerName}" not found`;
+      return MapUtils.error(errorMsg);
     }
   }
 
@@ -31,6 +36,9 @@ export class LayerManager {
     let layer = this.layers.get(LayerName);
     if (layer) {
       layer.hide();
+    } else {
+      const errorMsg = `Layer with name "${LayerName}" not found`;
+      return MapUtils.error(errorMsg);
     }
   }
 
@@ -53,5 +61,13 @@ export class LayerManager {
   hasLayer(layer: LayerIns): boolean {
     return this.layers.has(layer.layerName);
   }
+
+  clear() {
+    this.layers.forEach(layer => {
+      if (typeof (layer as any).destroy === 'function') {
+        (layer as any).destroy();
+      }
+    });
+  }
 }
 export default LayerManager;

package/src/MapSourceImport.ts

@@ -1,23 +1,23 @@
-import AMapLoader from '@amap/amap-jsapi-loader';
-import type { AMap, loaderOpts } from './types/amap.d.ts'; //TODO   项目配置ts自动引入，移除导入信息
-
-class MapSourceImport {
-  static async loadScript(opts: loaderOpts) {
-    // 某些API加载前必须设置秘钥
-    // window._AMapSecurityConfig = {
-    //   securityJsCode: process.env.VUE_APP_GD_MAP_CODE, // 安全密钥
-    // };
-    // 确保每次的AMap都是合法的所以不分开创建
-    return AMapLoader.load(opts)
-      .then((rawAMap: typeof AMap) => {
-        // 将 AMap 全局对象挂载到 window 上
-        return rawAMap;
-      })
-      .catch(e => {
-        console.error(e);
-        throw new Error(e);
-      });
-  }
-}
-
-export default MapSourceImport;
+import AMapLoader from '@amap/amap-jsapi-loader';
+import type { AMap, loaderOpts } from './types/amap.d.ts'; //TODO   项目配置ts自动引入，移除导入信息
+
+class MapSourceImport {
+  static async loadScript(opts: loaderOpts) {
+    // 某些API加载前必须设置秘钥
+    // window._AMapSecurityConfig = {
+    //   securityJsCode: process.env.VUE_APP_GD_MAP_CODE, // 安全密钥
+    // };
+    // 确保每次的AMap都是合法的所以不分开创建
+    return AMapLoader.load(opts)
+      .then((rawAMap: typeof AMap) => {
+        // 将 AMap 全局对象挂载到 window 上
+        return rawAMap;
+      })
+      .catch(e => {
+        console.error(e);
+        throw new Error(e);
+      });
+  }
+}
+
+export default MapSourceImport;

package/src/MapUtils.ts

@@ -9,8 +9,12 @@ import type {
   LayerOpts,
   ClusterMarkerLayerOpts,
 } from './types/index.d';
-import { BaseMarkerLayer, ClusterMarkerLayer } from './layers/index';
-import type { BaseMarkerLayerIns, ClusterMarkerLayerIns } from './layers';
+import {
+  BaseMarkerLayerIns,
+  BaseMarkerLayer,
+  ClusterMarkerLayerIns,
+  ClusterMarkerLayer,
+} from './layers/index';
 import type { SetOptional, Simplify } from 'type-fest';
 import LayerManager from './LayerManager';
 
@@ -26,18 +30,42 @@ export class MapUtils {
 
   LayerManager: LayerManager = new LayerManager();
 
+  /**
+   *@category 高德地图工具
+   */
   static createAMapMarker = MapMixin.createAMapMarker;
-
+  /**
+   *@category 高德地图工具
+   */
   static createIcon = MapMixin.createIcon;
-
+  /**
+   *@category 高德地图工具
+   */
   static Size = MapMixin.Size;
-
+  /**
+   *@category 高德地图工具
+   */
   static Pixel = MapMixin.Pixel;
-
+  /**
+   *@category 高德地图工具
+   */
   static LngLat = MapMixin.LngLat;
-
+  /**
+   *@category 高德地图工具
+   */
   static createAMapInfoWindow = MapMixin.createAMapInfoWindow;
+  /**
+   *@category 高德地图工具
+   */
+  static createAMapPolyline = MapMixin.createAMapPolyline;
+  /**
+   *@category 高德地图工具
+   */
+  static loadPlugins = MapMixin.loadPlugins;
 
+  /**
+   * @ignore
+   */
   constructor(
     opts: MapUtilsOpts[keyof MapUtilsOpts],
     AMap: Simplify<typeof gdAMap>
@@ -61,26 +89,36 @@ export class MapUtils {
         this.map = this.initMap(mountSelector, rest); //地图初始化
       }
     }
-
-    this.bindMapClickEvent();
   }
 
-  // 初始化绑定地图事件
-  bindMapClickEvent() {
-    this.map.on('click', () => {
-      // if (this.clickMapRestMarkers) {
-      //   this.overlayGroupManagerMap.forEach((overlayGroup) => {
-      //     overlayGroup.resetActiveMarker(); // 清除图层上的所有覆盖物
-      //   });
-      // }
-    });
+  /**
+   * @param {AMap.EventType} type  地图事件类型
+   * @param {(e: any) => void} fn  回调函数
+   * @param {*} [context]          事件上下文，缺省为当前实例
+   * @param {boolean} [once]       事件是否执行一次
+   * @memberof MapUtils
+   */
+  bindMapClickEvent(
+    type: AMap.EventType,
+    fn: (e: any) => void,
+    context?: any,
+    once?: boolean
+  ) {
+    this.map.on(type, fn, context, once);
   }
 
+  /**
+   * @ignore
+   */
   initMap(id: string, opts: MapOptions): mapIns {
     //参数要作检验吗
     return new window.AMap.Map(id, opts);
   }
 
+  /**
+   * @ignore
+   * @return {*}
+   */
   createBaseMarkerLayer<
     U extends {},
     T extends MarkerLayerBaseType = 'markerLayer',
@@ -91,16 +129,25 @@ export class MapUtils {
     return layer;
   }
 
+  /**
+   * 高德地图中 `MarkerCluster, MassMarks`用于渲染海量点，它们调用方式也比较接近，将其聚合为一个统一的图层管理
+   * 目前, 聚合图层只包装`MarkerCluster`
+   * @param {ClusterMarkerLayerOpts<U, T>} opts - 图层配置选项
+   */
   createClusterMarkerLayer<
     U extends {},
     T extends MarkerClusterLayerType = 'markerClusterLayer',
   >(opts: ClusterMarkerLayerOpts<U, T>) {
     const layer = new ClusterMarkerLayer<U, T>(opts, this);
-
+    // @ts-ignore
     this.LayerManager.addLayer(layer);
     return layer;
   }
 
+  /**
+   * `removeLayer`接收图层实例将其从mapUtils的关联中移除
+   * @param {(BaseMarkerLayerIns | ClusterMarkerLayerIns)} layer
+   */
   removeLayer(layer: BaseMarkerLayerIns | ClusterMarkerLayerIns) {
     const isLayerExist = this.LayerManager.hasLayer(layer);
 
@@ -122,13 +169,43 @@ export class MapUtils {
     this.map.setFitView(...opts);
   }
 
+  /**
+   * 地图弹窗关闭
+   * @memberof MapUtils
+   */
   clearInfoWindow() {
     this.map.clearInfoWindow();
   }
 
+  /**
+   * 销毁地图实例，释放资源
+   * - 清空所有图层
+   * - 销毁地图实例
+   * - 清理 LayerManager
+   * @memberof MapUtils
+   */
+  destroyMap() {
+    // 清空所有图层
+    this.LayerManager.clear();
+    // 销毁地图实例
+    this.map.destroy();
+  }
+
+  /**
+   * 地图跳转参数
+   * @typedef {Object} GotoOpts
+   * @property {number} zoom                   - 目标缩放级别
+   * @property {AMap.LngLat|[number,number]} center - 目标中心点（高德坐标实例或 [lng,lat] 数组）
+   * @property {boolean} [immediately=false]   - 是否立即跳转，默认平滑过渡
+   * @property {number} [duration]             - 过渡动画时长（毫秒）
+   */
+  /**
+   * 将地图视图切换到指定状态
+   * @param {GotoOpts} opts 跳转配置
+   */
   seZoomAndCenter(opts: {
-    zoom: number;
-    center: AMap.LngLat | [number, number];
+    zoom?: number;
+    center?: AMap.LngLat | [number, number];
     immediately?: boolean;
     duration?: number;
   }): void {
@@ -140,6 +217,47 @@ export class MapUtils {
     this.map.setZoomAndCenter(zoom, center, immediately, duration);
   }
 
+  /**
+   * 图层`layerName`显示, `layerName`为创建图层所传递的参数，用于标识图层名称。
+   * @param {string} layerName - 图层名称
+   */
+  showLayer(layerName: string): void {
+    this.LayerManager.show(layerName);
+  }
+
+  /**
+   * 图层`layerName`隐藏, `layerName`为创建图层所传递的参数，用于标识图层名称。
+   * @param {string} layerName - 图层名称
+   */
+  hideLayer(layerName: string): void {
+    this.LayerManager.hide(layerName);
+  }
+
+  /**
+   * 地图显示所有图层
+   */
+  showAllLayers(): void {
+    this.LayerManager.showAll();
+  }
+
+  /**
+   * 地图隐藏所有图层
+   */
+  hideAllLayers(): void {
+    this.LayerManager.hideAll();
+  }
+
+  /**
+   * 地图重新渲染所有图层
+   */
+  reloadLayers(): void {
+    this.LayerManager.reload();
+  }
+
+  /**
+   * @ignore
+   * @param msg
+   */
   static error(msg: string) {
     console.error(`[MapUtils Error]:${msg}`);
   }
@@ -147,6 +265,45 @@ export class MapUtils {
 
 export type { mapUtilsIns, MapUtilsConstructor };
 
+/**
+ * 
+ * `createMapUtils`功能如下: 
+ * 1. 支持将高德地图实例包装成工具函数 (为其扩展功能), 
+ * 2.  地图创建并为其扩展功能,
+ * 3.  高德地图依赖加载 ( 高德AMap函数加载 )
+ * @param {MapUtilsOpts[keyof MapUtilsOpts]} opts 
+ * - 工具函数配置选项，支持两种模式：
+ * 1. 使用现有地图实例（MapUtilsUseExistingOpts）
+ * 2. 创建新地图实例（MapUtilsCreateOpts）
+ * 
+ * [MapOptions文档地址](https://lbs.amap.com/api/javascript-api-v2/documentation#map)
+ * ```
+ * interface MapUtilsCreateOpts extends MapOptions {
+     mountSelector: string; //选择器
+   }
+
+    interface MapUtilsUseExistingOpts extends MapOptions {
+      mapIns: mapIns; //高德地图实例
+    }
+ * ```
+ * @param {loaderOpts} [loaderOPts]
+ * - 高德地图环境加载所传递的配置对象
+ * ```
+ *   type loaderOpts = {
+        key: string;
+         version: string;
+        plugins?: string[] | undefined;
+        AMapUI?: {
+            version?: string | undefined;
+            plugins?: string[] | undefined;
+        } | undefined;
+        Loca?: {
+            version?: string | undefined;
+        } | undefined;
+    }
+ * ```
+ * @return {*} 
+ */
 export async function createMapUtils(
   opts: MapUtilsOpts[keyof MapUtilsOpts],
   loaderOPts?: loaderOpts
@@ -161,7 +318,26 @@ export async function createMapUtils(
   return new MapUtils(opts, AMap);
 }
 
-// 地图拆分
+/**
+ *
+ * @param {loaderOpts} Opts
+ * - 高德地图环境加载所传递的配置对象
+ *  ```
+ * type loaderOpts = {
+        key: string;
+        version: string;
+        plugins?: string[] | undefined;
+        AMapUI?: {
+            version?: string | undefined;
+            plugins?: string[] | undefined;
+        } | undefined;
+        Loca?: {
+            version?: string | undefined;
+        } | undefined;
+    }
+ *  ```
+ * @return {*} 
+ */
 export async function initMapSource(Opts: loaderOpts) {
   return await MapSourceImport.loadScript(Opts);
 }