gdmap-utils 1.2.2 → 1.2.4

package/scripts/cleanDocs.js

@@ -0,0 +1,220 @@
+const fs = require('fs');
+const path = require('path');
+
+// 要处理的文档目录
+const docsDir = path.join(__dirname, '../docs');
+// 源代码目录
+const srcDir = path.join(__dirname, '../src');
+
+// 从TypeScript源文件中提取方法参数类型
+function extractMethodParamTypes() {
+  const paramTypes = {};
+  
+  // 递归遍历源代码文件
+  function traverseDir(dir) {
+    const files = fs.readdirSync(dir);
+    
+    files.forEach(file => {
+      const filePath = path.join(dir, file);
+      const stats = fs.statSync(filePath);
+      
+      if (stats.isDirectory()) {
+        traverseDir(filePath);
+      } else if (path.extname(file) === '.ts') {
+        const content = fs.readFileSync(filePath, 'utf8');
+        
+        // 按行读取文件内容
+        const lines = content.split('\n');
+        let currentMethod = null;
+        let currentParams = [];
+        let inMethod = false;
+        
+        lines.forEach(line => {
+          // 检查是否是方法定义的开始
+          const methodStartMatch = line.match(/(?:public|private|protected)?\s*(\w+)\s*<[^>]*>?\s*\(([^)]*)\)\s*(?::\s*([^\{]+))?\s*(?:\{|=>)/);
+          
+          if (methodStartMatch) {
+            // 如果之前有正在处理的方法，保存它
+            if (currentMethod && currentParams.length > 0) {
+              paramTypes[currentMethod] = currentParams;
+            }
+            
+            // 开始处理新方法
+            currentMethod = methodStartMatch[1];
+            currentParams = [];
+            inMethod = true;
+            
+            // 提取当前行的参数
+            const paramsStr = methodStartMatch[2];
+            if (paramsStr && paramsStr.trim() !== '') {
+              const params = paramsStr.split(',').map(param => {
+                const paramMatch = param.trim().match(/(\w+)\s*:\s*([^=]+)/);
+                if (paramMatch) {
+                  return {
+                    name: paramMatch[1],
+                    type: paramMatch[2].trim()
+                  };
+                }
+                return null;
+              }).filter(Boolean);
+              
+              currentParams = currentParams.concat(params);
+            }
+          } else if (inMethod) {
+            // 检查是否是方法定义的结束
+            if (line.trim() === '{' || line.trim() === '};') {
+              // 保存当前方法
+              if (currentMethod && currentParams.length > 0) {
+                paramTypes[currentMethod] = currentParams;
+              }
+              
+              currentMethod = null;
+              currentParams = [];
+              inMethod = false;
+            } else {
+              // 提取跨多行的参数
+              const paramMatch = line.trim().match(/(\w+)\s*:\s*([^=]+)/);
+              if (paramMatch) {
+                currentParams.push({
+                  name: paramMatch[1],
+                  type: paramMatch[2].trim()
+                });
+              }
+            }
+          }
+        });
+        
+        // 保存最后一个方法
+        if (currentMethod && currentParams.length > 0) {
+          paramTypes[currentMethod] = currentParams;
+        }
+      }
+    });
+  }
+  
+  traverseDir(srcDir);
+  
+  // 添加硬编码的参数类型映射，为那些难以通过正则表达式提取的方法提供类型信息
+  const hardcodedParamTypes = {
+    'removeLayer': [{ name: 'layer', type: 'BaseMarkerLayerIns | ClusterMarkerLayerIns' }],
+    'setFitView': [{ name: 'opts', type: 'Parameters<mapIns[\'setFitView\']>' }],
+    'seZoomAndCenter': [{ name: 'opts', type: '{ zoom: number; center: AMap.LngLat | [number, number]; immediately?: boolean; duration?: number }' }]
+  };
+  
+  // 合并硬编码的参数类型映射
+  Object.assign(paramTypes, hardcodedParamTypes);
+  
+  return paramTypes;
+}
+
+// 递归处理所有.md文件
+function processMarkdownFiles(dir) {
+  const files = fs.readdirSync(dir);
+  const paramTypes = extractMethodParamTypes();
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stats = fs.statSync(filePath);
+    
+    if (stats.isDirectory()) {
+      processMarkdownFiles(filePath);
+    } else if (path.extname(file) === '.md') {
+      processMarkdownFile(filePath, paramTypes);
+    }
+  });
+}
+
+// 在分类标题后添加描述文字
+function addCategoryDescription(content) {
+  // 定义分类描述映射
+  const categoryDescriptions = {
+    '高德地图工具': '本分类封装了高德地图（AMap）的核心功能，包括标记点、图标、折线、信息窗口等常用地图元素的创建和管理。这些静态方法提供了便捷的API，帮助开发者快速构建地图应用。'
+  };
+  
+  // 遍历所有分类，添加描述文字
+  Object.keys(categoryDescriptions).forEach(category => {
+    const regex = new RegExp(`##\\s*${category}\\s*\\n`, 'g');
+    content = content.replace(regex, `## ${category}\n\n${categoryDescriptions[category]}\n\n`);
+  });
+  
+  return content;
+}
+
+// 处理单个Markdown文件，移除Params和Return部分，并添加参数类型
+function processMarkdownFile(filePath, paramTypes) {
+  let content = fs.readFileSync(filePath, 'utf8');
+  
+  // 在分类标题后添加描述文字
+  content = addCategoryDescription(content);
+  
+  // 移除Params部分
+  content = content.replace(/#### Parameters[\s\S]*?(?=#### Returns|\*\*\*|$)/g, '');
+  
+  // 移除Returns部分
+  content = content.replace(/#### Returns[\s\S]*?(?=####|\*\*\*|$)/g, '');
+  
+  // 移除Memberof部分
+  content = content.replace(/#### Memberof[\s\S]*?(?=####|\*\*\*|$)/g, '');
+  
+  // 移除Type Parameters部分（包含#### Type Parameters标题和后续的所有参数行）
+  content = content.replace(/#### Type Parameters[\s\S]*?(?=\*\*\*|$)/g, '');
+  
+  // 移除单独的Type Parameter行（如##### U, ##### T等）
+  content = content.replace(/#####\s+\w+[\s\S]*?(?=#####|\*\*\*|$)/g, '');
+  
+  // 移除单独的Type Parameter描述行（如`U` *extends* `object`）
+  content = content.replace(/`\w+`\s*\*extends\*\s*`[^`]+`[^\n]*\n/g, '');
+  
+  // 为方法参数添加类型信息
+  content = content.replace(/(###\s+(\w+)\(\)[\s\S]*?>\s*\*\*\w+\*\*\s*)\(([^)]*)\)(:\s*`[^`]+`)/g, (match, prefix, methodName, paramsStr, returnType) => {
+    if (paramTypes[methodName]) {
+      const params = paramTypes[methodName];
+      let newParamsStr = '';
+      
+      params.forEach((param, index) => {
+        if (index > 0) {
+          newParamsStr += ', ';
+        }
+        newParamsStr += `${param.name}: ${param.type}`;
+      });
+      
+      return `${prefix}(${newParamsStr})${returnType}`;
+    }
+    return match;
+  });
+  
+  // 处理带有反引号的参数
+  content = content.replace(/###\s+(\w+)\(\)[\s\S]*?>(\s*\*\*\w+\*\*\s*)\(`([^`]+)`\)(:\s*`[^`]+`)/g, (match, methodName, prefix, paramName, returnType) => {
+    if (paramTypes[methodName]) {
+      const params = paramTypes[methodName];
+      let newParamsStr = '';
+      
+      params.forEach((param, index) => {
+        if (index > 0) {
+          newParamsStr += ', ';
+        }
+        newParamsStr += `${param.name}: ${param.type}`;
+      });
+      
+      return match.replace(/\(`[^`]+`\)/, `(${newParamsStr})`);
+    }
+    return match;
+  });
+  
+  // 移除多余的换行
+  content = content.replace(/\n{3,}/g, '\n\n');
+  
+  // 移除分隔线前的多余换行
+  content = content.replace(/\n+\*\*\*/g, '\n***');
+  
+  // 移除多余的分隔线
+  content = content.replace(/\*\*\*\n\*\*\*/g, '***');
+  
+  // 保存处理后的内容
+  fs.writeFileSync(filePath, content, 'utf8');
+  console.log(`Processed: ${filePath}`);
+}
+
+// 执行处理
+processMarkdownFiles(docsDir);
+console.log('All markdown files processed successfully!');

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

@@ -1,13 +1,19 @@
-import type { LayerManger } from './types/index.d.ts';
-import type { BaseMarkerLayerClass } from './layers/index.ts';
+import type {
+  BaseMarkerLayerClass,
+  ClusterMarkerLayerClass,
+} from '@/layers/index.ts';
+import { MapUtils } from '@/MapUtils';
 
-type LayerIns = InstanceType<BaseMarkerLayerClass>;
+type LayerIns =
+  | InstanceType<BaseMarkerLayerClass>
+  | InstanceType<ClusterMarkerLayerClass>;
 export class LayerManager {
   layers: Map<string, LayerIns> = new Map(); //组合模式
 
   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);
   }
@@ -20,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);
     }
   }
 
@@ -27,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);
     }
   }
 
@@ -39,7 +51,11 @@ export class LayerManager {
   }
 
   reload() {
-    this.layers.forEach(val => val.reload());
+    this.layers.forEach(val => {
+      if (typeof (val as any).reload === 'function') {
+        (val as any).reload();
+      }
+    });
   }
 
   hasLayer(layer: LayerIns): boolean {

package/src/MapUtils.ts

@@ -5,9 +5,16 @@ import type {
   MapUtilsOpts,
   mapIns,
   MarkerLayerBaseType,
+  MarkerClusterLayerType,
   LayerOpts,
+  ClusterMarkerLayerOpts,
 } from './types/index.d';
-import { BaseMarkerLayerIns, BaseMarkerLayer } from './layers/index';
+import {
+  BaseMarkerLayerIns,
+  BaseMarkerLayer,
+  ClusterMarkerLayerIns,
+  ClusterMarkerLayer,
+} from './layers/index';
 import type { SetOptional, Simplify } from 'type-fest';
 import LayerManager from './LayerManager';
 
@@ -23,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>
@@ -58,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',
@@ -88,7 +129,26 @@ export class MapUtils {
     return layer;
   }
 
-  removeLayer(layer: BaseMarkerLayerIns) {
+  /**
+   * 高德地图中 `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);
 
     if (isLayerExist) {
@@ -109,10 +169,26 @@ export class MapUtils {
     this.map.setFitView(...opts);
   }
 
+  /**
+   * 地图弹窗关闭
+   * @memberof MapUtils
+   */
   clearInfoWindow() {
     this.map.clearInfoWindow();
   }
 
+  /**
+   * 地图跳转参数
+   * @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];
@@ -127,6 +203,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}`);
   }
@@ -134,6 +251,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
@@ -148,7 +304,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);
 }