my-openlayer 2.3.0 → 2.3.2

package/core/MapBaseLayers.d.ts

@@ -58,20 +58,16 @@ export default class MapBaseLayers {
     constructor(map: Map, options: MapLayersOptions);
     /**
      * 验证构造函数参数
-     * @param map 地图实例
-     * @param options 配置选项
      * @private
      */
     private validateConstructorParams;
     /**
      * 合并默认配置选项
-     * @param options 用户配置选项
-     * @returns 合并后的配置选项
      * @private
      */
     private mergeDefaultOptions;
     /**
-     * 初始化图层
+     * 初始化图层数据结构
      * @private
      */
     private initializeLayers;
@@ -80,156 +76,158 @@ export default class MapBaseLayers {
      * @private
      */
     private initTiandituLayers;
+    /**
+     * 初始化注记图层
+     * @private
+     */
+    private initAnnotationLayer;
+    /**
+     * 设置初始图层状态（默认显示的底图）
+     * @private
+     */
+    private setupInitialState;
+    /**
+     * 切换底图图层
+     * @param type 图层类型
+     */
+    switchBaseLayer(type: TiandituType | string): this;
+    /**
+     * 验证是否可以切换到底图
+     * @private
+     */
+    private validateSwitchBaseLayer;
+    /**
+     * 获取当前底图类型
+     */
+    getCurrentBaseLayerType(): string | null;
+    /**
+     * 获取默认底图类型
+     * @private
+     */
     private getDefaultBaseLayerType;
     /**
-     * 加载默认注记图层（cia_c）
-     * @param token 天地图token
-     * @param baseZIndex 基础层级
+     * 设置所有底图的可见性
      * @private
      */
-    private loadDefaultAnnotationLayer;
+    private setAllBaseLayersVisible;
+    /**
+     * 设置指定类型图层的可见性
+     * @private
+     */
+    private setLayerTypeVisible;
     /**
      * 切换注记类别
      * @param annotationType 注记类型 ('cva_c' | 'cia_c' | 'cta_c')
      */
-    switchAnnotationLayer(annotationType: AnnotationType): void;
+    switchAnnotationLayer(annotationType: AnnotationType): this;
     /**
-     * 设置注记图层（私有方法，用于消除代码重复）
-     * @param annotationType 注记类型
-     * @param token 天地图token
-     * @param baseZIndex 基础层级
+     * 设置注记图层（核心实现）
      * @private
      */
     private setAnnotationLayer;
+    /**
+     * 移除当前注记图层
+     * @private
+     */
+    private removeCurrentAnnotationLayer;
+    /**
+     * 更新注记图层层级
+     * @private
+     */
+    private updateAnnotationLayerZIndex;
+    /**
+     * 加载默认注记图层（cia_c）
+     * @private
+     */
+    private loadDefaultAnnotationLayer;
     /**
      * 获取当前注记类型
-     * @returns 当前注记类型
      */
     getCurrentAnnotationType(): string | null;
     /**
      * 显示/隐藏注记图层
-     * @param visible 是否可见
      */
-    setAnnotationVisible(visible: boolean): void;
+    setAnnotationVisible(visible: boolean): this;
     /**
      * 检查注记图层是否可见
-     * @returns 是否可见
      */
     isAnnotationVisible(): boolean;
     /**
-     * 切换底图图层
-     * @param type 图层类型
+     * 添加注记图层（实例方法）
      */
-    switchBaseLayer(type: TiandituType | string): void;
+    addAnnotationLayer(options: Omit<AnnotationLayerOptions, 'token'>): TileLayer<XYZ>;
     /**
-     * 获取当前底图类型
-     * @returns 当前底图类型
+     * 添加GeoServer图层
      */
-    getCurrentBaseLayerType(): string | null;
+    addGeoServerLayer(url: string, layerName: string, options?: GeoServerLayerOptions): TileLayer<TileWMS>;
+    /**
+     * 移除指定类型的图层
+     */
+    removeLayersByType(type: string): this;
+    /**
+     * 清除所有图层
+     */
+    clearAllLayers(): this;
+    /**
+     * 获取图层数量统计
+     */
+    getLayerStats(): {
+        totalTypes: number;
+        totalLayers: number;
+        layersByType: Record<string, number>;
+    };
     /**
      * 获取可用的图层类型列表
-     * @returns 图层类型数组
      */
     getAvailableLayerTypes(): string[];
     /**
      * 检查指定图层类型是否存在
-     * @param type 图层类型
-     * @returns 是否存在
      */
     hasLayerType(type: string): boolean;
     /**
-     * 添加注记图层（实例方法）
-     * @param options 注记图层选项（不包含token）
-     * @returns 创建的图层
-     */
-    addAnnotationLayer(options: Omit<AnnotationLayerOptions, 'token'>): TileLayer<XYZ>;
-    /**
-     * 添加注记图层（静态方法）
-     * @param map 地图实例
-     * @param options 注记图层选项
-     * @returns 创建的图层
+     * 销毁实例，清理资源
      */
-    static addAnnotationLayer(map: Map, options: AnnotationLayerOptions): TileLayer<XYZ>;
+    destroy(): this;
     /**
-     * 将所有图层添加到地图
+     * 将所有初始化好的图层添加到地图
      * @private
      */
     private addMapLayer;
     /**
      * 处理图层（应用裁剪等）
-     * @param layer 原始图层
-     * @returns 处理后的图层
      * @private
      */
     private processLayer;
-    /**
-     * 添加GeoServer图层
-     * @param url GeoServer服务URL
-     * @param layerName 图层名称
-     * @param options 图层选项
-     * @returns 创建的WMS图层
-     */
-    addGeoServerLayer(url: string, layerName: string, options?: GeoServerLayerOptions): TileLayer<TileWMS>;
     /**
      * 创建天地图图层（实例方法）
-     * @param options 天地图图层选项
-     * @returns 创建的图层
      * @private
      */
     private createTiandituLayer;
     /**
      * 创建注记图层（实例方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
      * @private
      */
     private createAnnotationLayer;
     /**
-     * 创建天地图底图图层（静态方法）
-     * @param options 天地图图层选项
-     * @returns 创建的图层
+     * 创建天地图底图图层
      */
     static getTiandiTuLayer(options: TiandituLayerOptions): TileLayer<XYZ>;
     /**
-     * 创建天地图注记图层（静态方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
+     * 创建天地图注记图层
      */
     static createAnnotationLayer(options: AnnotationLayerOptions): TileLayer<XYZ>;
+    /**
+     * 添加注记图层到地图（静态方法）
+     */
+    static addAnnotationLayer(map: Map, options: AnnotationLayerOptions): TileLayer<XYZ>;
     /**
      * 获取天地图注记图层（向后兼容的静态方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
      * @deprecated 使用 createAnnotationLayer 替代
      */
     static getAnnotationLayer(options: AnnotationLayerOptions): TileLayer<XYZ>;
     /**
      * 创建WMTS瓦片网格
-     * @param length 层级数量
-     * @returns WMTS瓦片网格
      */
     static getTileGrid(length: number): WMTSTileGrid;
-    /**
-     * 移除指定类型的图层
-     * @param type 图层类型
-     */
-    removeLayersByType(type: string): void;
-    /**
-     * 清除所有图层
-     */
-    clearAllLayers(): void;
-    /**
-     * 获取图层数量统计
-     * @returns 图层统计信息
-     */
-    getLayerStats(): {
-        totalTypes: number;
-        totalLayers: number;
-        layersByType: Record<string, number>;
-    };
-    /**
-     * 销毁实例，清理资源
-     */
-    destroy(): void;
 }
 export {};

package/core/MapBaseLayers.js

@@ -19,6 +19,7 @@ const CUSTOM_LAYER_KEY = '__custom__';
  * 地图底图图层管理类
  */
 export default class MapBaseLayers {
+    //************* Constructor & Initialization *************
     /**
      * 构造函数
      * @param map OpenLayers地图实例
@@ -31,21 +32,16 @@ export default class MapBaseLayers {
         this.currentAnnotationType = null;
         this.errorHandler = ErrorHandler.getInstance();
         try {
-            // 参数验证
+            // 1. 参数验证
             this.validateConstructorParams(map, options);
             this.map = map;
             this.options = this.mergeDefaultOptions(options);
-            // 初始化图层
+            // 2. 初始化图层列表（准备数据）
             this.initializeLayers();
-            if (this.layers && Object.keys(this.layers).length > 0) {
-                this.addMapLayer();
-                if (!Array.isArray(this.options.layers)) {
-                    const defaultType = this.getDefaultBaseLayerType();
-                    if (defaultType) {
-                        this.switchBaseLayer(defaultType);
-                    }
-                }
-            }
+            // 3. 将图层添加到地图（执行操作）
+            this.addMapLayer();
+            // 4. 设置初始状态
+            this.setupInitialState();
         }
         catch (error) {
             this.errorHandler.createAndHandleError(`Failed to initialize MapBaseLayers: ${error}`, ErrorType.MAP_ERROR, { map, options, error });
@@ -54,8 +50,6 @@ export default class MapBaseLayers {
     }
     /**
      * 验证构造函数参数
-     * @param map 地图实例
-     * @param options 配置选项
      * @private
      */
     validateConstructorParams(map, options) {
@@ -64,39 +58,36 @@ export default class MapBaseLayers {
     }
     /**
      * 合并默认配置选项
-     * @param options 用户配置选项
-     * @returns 合并后的配置选项
      * @private
      */
     mergeDefaultOptions(options) {
         return { ...ConfigManager.DEFAULT_MAP_LAYERS_OPTIONS, ...options };
     }
     /**
-     * 初始化图层
+     * 初始化图层数据结构
      * @private
      */
     initializeLayers() {
-        const { layers, token } = this.options;
+        const { layers, token, annotation } = this.options;
+        // 初始化底图配置
         if (Array.isArray(layers)) {
             this.layers = { [CUSTOM_LAYER_KEY]: layers };
         }
         else if (layers && Object.keys(layers).length > 0) {
             this.layers = layers;
         }
+        else if (token) {
+            // 如果没有提供layers但提供了token，则初始化标准天地图
+            this.initTiandituLayers();
+        }
         else {
             this.layers = {};
-            if (token) {
-                this.initTiandituLayers();
-            }
         }
-        // 添加注记图层
-        if (this.options.annotation) {
-            if (!this.options.token) {
-                throw new Error('请配置token后才能使用天地图注记');
-            }
-            const { token, zIndex = ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX } = this.options;
-            this.loadDefaultAnnotationLayer(token, zIndex);
+        // 初始化注记配置
+        if (annotation) {
+            this.initAnnotationLayer();
         }
+        return this;
     }
     /**
      * 初始化天地图图层
@@ -108,7 +99,6 @@ export default class MapBaseLayers {
         }
         const { token, zIndex = ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX } = this.options;
         try {
-            // 创建基础图层
             this.layers.vec_c = [this.createTiandituLayer({ type: 'vec_c', token, zIndex, visible: false })];
             this.layers.img_c = [this.createTiandituLayer({ type: 'img_c', token, zIndex, visible: false })];
             this.layers.ter_c = [this.createTiandituLayer({ type: 'ter_c', token, zIndex, visible: false })];
@@ -117,26 +107,113 @@ export default class MapBaseLayers {
             this.errorHandler.createAndHandleError(`Failed to initialize Tianditu layers: ${error}`, ErrorType.LAYER_ERROR, { token, zIndex, error });
             throw error;
         }
+        return this;
+    }
+    /**
+     * 初始化注记图层
+     * @private
+     */
+    initAnnotationLayer() {
+        if (!this.options.token) {
+            throw new Error('请配置token后才能使用天地图注记');
+        }
+        const { token, zIndex = ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX } = this.options;
+        this.loadDefaultAnnotationLayer(token, zIndex);
+    }
+    /**
+     * 设置初始图层状态（默认显示的底图）
+     * @private
+     */
+    setupInitialState() {
+        if (this.layers && Object.keys(this.layers).length > 0) {
+            // 如果是自定义数组图层，默认已经添加并显示了（取决于配置）
+            // 如果是键值对配置的图层（包括天地图），需要选择一个默认显示
+            if (!Array.isArray(this.options.layers)) {
+                const defaultType = this.getDefaultBaseLayerType();
+                if (defaultType) {
+                    this.switchBaseLayer(defaultType);
+                }
+            }
+        }
+    }
+    //************* Base Layer Management *************
+    /**
+     * 切换底图图层
+     * @param type 图层类型
+     */
+    switchBaseLayer(type) {
+        try {
+            if (!this.validateSwitchBaseLayer(type)) {
+                return this;
+            }
+            // 1. 隐藏所有底图
+            this.setAllBaseLayersVisible(false);
+            // 2. 显示目标底图
+            this.setLayerTypeVisible(type, true);
+            // 3. 更新当前状态
+            this.currentBaseLayerType = type;
+            // 4. 调整注记图层层级（保持在底图之上）
+            this.updateAnnotationLayerZIndex();
+        }
+        catch (error) {
+            this.errorHandler.createAndHandleError(`Failed to switch base layer to '${type}': ${error}`, ErrorType.LAYER_ERROR, { type, error });
+        }
+        return this;
+    }
+    /**
+     * 验证是否可以切换到底图
+     * @private
+     */
+    validateSwitchBaseLayer(type) {
+        if (Array.isArray(this.options.layers)) {
+            this.errorHandler.createAndHandleError('需要按照键值对的方式配置底图才可使用切换底图功能', ErrorType.LAYER_ERROR, { layersType: 'array', requestedType: type });
+            return false;
+        }
+        if (TIANDITU_TYPES.includes(type) && !this.options.token) {
+            this.errorHandler.createAndHandleError('请配置token后才能使用天地图底图', ErrorType.LAYER_ERROR, { requestedType: type });
+            return false;
+        }
+        if (!this.layers[type]) {
+            this.errorHandler.createAndHandleError(`图层类型 '${type}' 不存在`, ErrorType.LAYER_ERROR, { availableTypes: Object.keys(this.layers), requestedType: type });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 获取当前底图类型
+     */
+    getCurrentBaseLayerType() {
+        return this.currentBaseLayerType;
     }
+    /**
+     * 获取默认底图类型
+     * @private
+     */
     getDefaultBaseLayerType() {
         const types = Object.keys(this.layers);
-        if (types.length === 0) {
+        if (types.length === 0)
             return null;
+        return this.layers.vec_c ? 'vec_c' : types[0];
+    }
+    /**
+     * 设置所有底图的可见性
+     * @private
+     */
+    setAllBaseLayersVisible(visible) {
+        for (const key in this.layers) {
+            this.setLayerTypeVisible(key, visible);
         }
-        if (this.layers.vec_c) {
-            return 'vec_c';
-        }
-        return types[0];
     }
     /**
-     * 加载默认注记图层（cia_c）
-     * @param token 天地图token
-     * @param baseZIndex 基础层级
+     * 设置指定类型图层的可见性
      * @private
      */
-    loadDefaultAnnotationLayer(token, baseZIndex) {
-        this.setAnnotationLayer('cia_c', token, baseZIndex);
+    setLayerTypeVisible(type, visible) {
+        this.layers[type]?.forEach((layer) => {
+            layer.setVisible(visible);
+        });
     }
+    //************* Annotation Layer Management *************
     /**
      * 切换注记类别
      * @param annotationType 注记类型 ('cva_c' | 'cia_c' | 'cta_c')
@@ -155,181 +232,234 @@ export default class MapBaseLayers {
         catch (error) {
             this.errorHandler.createAndHandleError(`Failed to switch annotation layer to '${annotationType}': ${error}`, ErrorType.LAYER_ERROR, { annotationType, error });
         }
+        return this;
     }
     /**
-     * 设置注记图层（私有方法，用于消除代码重复）
-     * @param annotationType 注记类型
-     * @param token 天地图token
-     * @param baseZIndex 基础层级
+     * 设置注记图层（核心实现）
      * @private
      */
     setAnnotationLayer(annotationType, token, baseZIndex) {
-        // 移除当前注记图层
-        if (this.currentAnnotationLayer) {
-            this.map.removeLayer(this.currentAnnotationLayer);
-        }
-        // 创建新的注记图层，确保层级在基本图层之上
+        // 1. 移除旧图层
+        this.removeCurrentAnnotationLayer();
+        // 2. 计算新层级
         const annotationZIndex = baseZIndex + ConfigManager.TIANDITU_CONFIG.ANNOTATION_ZINDEX_OFFSET;
+        // 3. 创建新图层
         let annotationLayer = this.createAnnotationLayer({
             type: annotationType,
             token,
             zIndex: annotationZIndex,
             visible: true
         });
-        // 应用剪切处理
+        // 4. 应用剪切
         annotationLayer = this.processLayer(annotationLayer);
+        // 5. 添加到地图并更新状态
         this.currentAnnotationLayer = annotationLayer;
         this.currentAnnotationType = annotationType;
         this.map.addLayer(this.currentAnnotationLayer);
+        return this;
+    }
+    /**
+     * 移除当前注记图层
+     * @private
+     */
+    removeCurrentAnnotationLayer() {
+        if (this.currentAnnotationLayer) {
+            this.map.removeLayer(this.currentAnnotationLayer);
+            this.currentAnnotationLayer = null;
+            // 注意：这里不清除 currentAnnotationType，因为可能只是临时移除
+        }
+    }
+    /**
+     * 更新注记图层层级
+     * @private
+     */
+    updateAnnotationLayerZIndex() {
+        if (this.currentAnnotationLayer && this.currentAnnotationType) {
+            const baseZIndex = this.options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX;
+            const annotationZIndex = baseZIndex + ConfigManager.TIANDITU_CONFIG.ANNOTATION_ZINDEX_OFFSET;
+            this.currentAnnotationLayer.setZIndex(annotationZIndex);
+        }
+    }
+    /**
+     * 加载默认注记图层（cia_c）
+     * @private
+     */
+    loadDefaultAnnotationLayer(token, baseZIndex) {
+        this.setAnnotationLayer('cia_c', token, baseZIndex);
+        return this;
     }
     /**
      * 获取当前注记类型
-     * @returns 当前注记类型
      */
     getCurrentAnnotationType() {
         return this.currentAnnotationType;
     }
     /**
      * 显示/隐藏注记图层
-     * @param visible 是否可见
      */
     setAnnotationVisible(visible) {
         if (this.currentAnnotationLayer) {
             this.currentAnnotationLayer.setVisible(visible);
         }
+        return this;
     }
     /**
      * 检查注记图层是否可见
-     * @returns 是否可见
      */
     isAnnotationVisible() {
         return this.currentAnnotationLayer ? this.currentAnnotationLayer.getVisible() : false;
     }
     /**
-     * 切换底图图层
-     * @param type 图层类型
+     * 添加注记图层（实例方法）
      */
-    switchBaseLayer(type) {
+    addAnnotationLayer(options) {
         try {
-            if (Array.isArray(this.options.layers)) {
-                this.errorHandler.createAndHandleError('需要按照键值对的方式配置底图才可使用切换底图功能', ErrorType.LAYER_ERROR, { layersType: 'array', requestedType: type });
-                return;
-            }
-            if (TIANDITU_TYPES.includes(type) && !this.options.token) {
-                this.errorHandler.createAndHandleError('请配置token后才能使用天地图底图', ErrorType.LAYER_ERROR, { requestedType: type });
-                return;
+            if (!this.options.token) {
+                throw new Error('Token is required for annotation layer');
             }
+            return MapBaseLayers.addAnnotationLayer(this.map, {
+                ...options,
+                token: this.options.token
+            });
+        }
+        catch (error) {
+            this.errorHandler.createAndHandleError(`Failed to add annotation layer: ${error}`, ErrorType.LAYER_ERROR, { options, error });
+            throw error;
+        }
+    }
+    //************* Layer Operations *************
+    /**
+     * 添加GeoServer图层
+     */
+    addGeoServerLayer(url, layerName, options = {}) {
+        try {
+            ValidationUtils.validateNonEmptyString(url, 'Valid URL is required for GeoServer layer');
+            ValidationUtils.validateNonEmptyString(layerName, 'Valid layer name is required for GeoServer layer');
+            const wmsLayer = new TileLayer({
+                source: new TileWMS({
+                    url: url,
+                    params: {
+                        'LAYERS': layerName,
+                        'TILED': true,
+                        'VERSION': options.version || '1.1.1',
+                        ...options.params
+                    },
+                    serverType: 'geoserver',
+                    crossOrigin: options.crossOrigin || 'anonymous',
+                }),
+                zIndex: options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX,
+                visible: options.visible ?? true,
+            });
+            this.map.addLayer(wmsLayer);
+            return wmsLayer;
+        }
+        catch (error) {
+            this.errorHandler.createAndHandleError(`Failed to add GeoServer layer: ${error}`, ErrorType.LAYER_ERROR, { url, layerName, options, error });
+            throw error;
+        }
+    }
+    /**
+     * 移除指定类型的图层
+     */
+    removeLayersByType(type) {
+        try {
             if (!this.layers[type]) {
-                this.errorHandler.createAndHandleError(`图层类型 '${type}' 不存在`, ErrorType.LAYER_ERROR, { availableTypes: Object.keys(this.layers), requestedType: type });
-                return;
+                return this;
             }
-            // 隐藏所有图层
+            this.layers[type].forEach((layer) => {
+                this.map.removeLayer(layer);
+            });
+            delete this.layers[type];
+            if (this.currentBaseLayerType === type) {
+                this.currentBaseLayerType = null;
+            }
+        }
+        catch (error) {
+            this.errorHandler.createAndHandleError(`Failed to remove layers of type '${type}': ${error}`, ErrorType.LAYER_ERROR, { type, error });
+        }
+        return this;
+    }
+    /**
+     * 清除所有图层
+     */
+    clearAllLayers() {
+        try {
+            // 1. 清除底图
             for (const key in this.layers) {
                 this.layers[key]?.forEach((layer) => {
-                    layer.setVisible(false);
+                    this.map.removeLayer(layer);
                 });
             }
-            // 显示指定类型的图层
-            this.layers[type]?.forEach((layer) => {
-                layer.setVisible(true);
-            });
-            this.currentBaseLayerType = type;
-            // 如果存在注记图层，更新其层级确保在新的基本图层之上
-            if (this.currentAnnotationLayer && this.currentAnnotationType) {
-                const baseZIndex = this.options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX;
-                const annotationZIndex = baseZIndex + ConfigManager.TIANDITU_CONFIG.ANNOTATION_ZINDEX_OFFSET;
-                this.currentAnnotationLayer.setZIndex(annotationZIndex);
-            }
+            this.layers = {};
+            this.currentBaseLayerType = null;
+            // 2. 清除注记
+            this.removeCurrentAnnotationLayer();
+            this.currentAnnotationType = null;
         }
         catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to switch base layer to '${type}': ${error}`, ErrorType.LAYER_ERROR, { type, error });
+            this.errorHandler.createAndHandleError(`Failed to clear all layers: ${error}`, ErrorType.LAYER_ERROR, { error });
         }
+        return this;
     }
     /**
-     * 获取当前底图类型
-     * @returns 当前底图类型
+     * 获取图层数量统计
      */
-    getCurrentBaseLayerType() {
-        return this.currentBaseLayerType;
+    getLayerStats() {
+        const layersByType = {};
+        let totalLayers = 0;
+        for (const key in this.layers) {
+            const count = this.layers[key]?.length || 0;
+            layersByType[key] = count;
+            totalLayers += count;
+        }
+        return {
+            totalTypes: Object.keys(this.layers).length,
+            totalLayers,
+            layersByType
+        };
     }
     /**
      * 获取可用的图层类型列表
-     * @returns 图层类型数组
      */
     getAvailableLayerTypes() {
         return Object.keys(this.layers);
     }
     /**
      * 检查指定图层类型是否存在
-     * @param type 图层类型
-     * @returns 是否存在
      */
     hasLayerType(type) {
         return type in this.layers && this.layers[type] !== undefined;
     }
     /**
-     * 添加注记图层（实例方法）
-     * @param options 注记图层选项（不包含token）
-     * @returns 创建的图层
-     */
-    addAnnotationLayer(options) {
-        try {
-            if (!this.options.token) {
-                throw new Error('Token is required for annotation layer');
-            }
-            return MapBaseLayers.addAnnotationLayer(this.map, {
-                ...options,
-                token: this.options.token
-            });
-        }
-        catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to add annotation layer: ${error}`, ErrorType.LAYER_ERROR, { options, error });
-            throw error;
-        }
-    }
-    /**
-     * 添加注记图层（静态方法）
-     * @param map 地图实例
-     * @param options 注记图层选项
-     * @returns 创建的图层
+     * 销毁实例，清理资源
      */
-    static addAnnotationLayer(map, options) {
+    destroy() {
         try {
-            ErrorHandler.validateMap(map);
-            if (!options.token) {
-                throw new Error('Token is required for annotation layer');
-            }
-            const layer = MapBaseLayers.createAnnotationLayer({
-                type: options.type,
-                token: options.token,
-                zIndex: options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX,
-                visible: options.visible ?? true
-            });
-            map.addLayer(layer);
-            return layer;
+            this.clearAllLayers();
         }
         catch (error) {
-            const errorHandler = ErrorHandler.getInstance();
-            errorHandler.createAndHandleError(`Failed to add annotation layer: ${error}`, ErrorType.LAYER_ERROR, { options, error });
-            throw error;
+            this.errorHandler.createAndHandleError(`Failed to destroy MapBaseLayers: ${error}`, ErrorType.MAP_ERROR, { error });
         }
+        return this;
     }
+    //************* Helper Methods *************
     /**
-     * 将所有图层添加到地图
+     * 将所有初始化好的图层添加到地图
      * @private
      */
     addMapLayer() {
         try {
             if (!this.layers || Object.keys(this.layers).length === 0) {
-                return;
+                return this;
             }
             for (const key in this.layers) {
                 const layerList = this.layers[key];
-                if (!layerList || layerList.length === 0) {
+                if (!layerList || layerList.length === 0)
                     continue;
-                }
+                // 处理并更新图层列表
                 const processedLayerList = layerList.map(layer => this.processLayer(layer));
                 this.layers[key] = processedLayerList;
+                // 添加到地图
                 processedLayerList.forEach((layer) => {
                     this.map.addLayer(layer);
                 });
@@ -339,11 +469,10 @@ export default class MapBaseLayers {
             this.errorHandler.createAndHandleError(`Failed to add map layers: ${error}`, ErrorType.LAYER_ERROR, { layersCount: Object.keys(this.layers).length, error });
             throw error;
         }
+        return this;
     }
     /**
      * 处理图层（应用裁剪等）
-     * @param layer 原始图层
-     * @returns 处理后的图层
      * @private
      */
     processLayer(layer) {
@@ -359,44 +488,8 @@ export default class MapBaseLayers {
             throw error;
         }
     }
-    /**
-     * 添加GeoServer图层
-     * @param url GeoServer服务URL
-     * @param layerName 图层名称
-     * @param options 图层选项
-     * @returns 创建的WMS图层
-     */
-    addGeoServerLayer(url, layerName, options = {}) {
-        try {
-            ValidationUtils.validateNonEmptyString(url, 'Valid URL is required for GeoServer layer');
-            ValidationUtils.validateNonEmptyString(layerName, 'Valid layer name is required for GeoServer layer');
-            const wmsLayer = new TileLayer({
-                source: new TileWMS({
-                    url: url,
-                    params: {
-                        'LAYERS': layerName,
-                        'TILED': true,
-                        'VERSION': options.version || '1.1.1',
-                        ...options.params
-                    },
-                    serverType: 'geoserver',
-                    crossOrigin: options.crossOrigin || 'anonymous',
-                }),
-                zIndex: options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX,
-                visible: options.visible ?? true,
-            });
-            this.map.addLayer(wmsLayer);
-            return wmsLayer;
-        }
-        catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to add GeoServer layer: ${error}`, ErrorType.LAYER_ERROR, { url, layerName, options, error });
-            throw error;
-        }
-    }
     /**
      * 创建天地图图层（实例方法）
-     * @param options 天地图图层选项
-     * @returns 创建的图层
      * @private
      */
     createTiandituLayer(options) {
@@ -404,17 +497,14 @@ export default class MapBaseLayers {
     }
     /**
      * 创建注记图层（实例方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
      * @private
      */
     createAnnotationLayer(options) {
         return MapBaseLayers.createAnnotationLayer(options);
     }
+    //************* Static Methods *************
     /**
-     * 创建天地图底图图层（静态方法）
-     * @param options 天地图图层选项
-     * @returns 创建的图层
+     * 创建天地图底图图层
      */
     static getTiandiTuLayer(options) {
         try {
@@ -440,9 +530,7 @@ export default class MapBaseLayers {
         }
     }
     /**
-     * 创建天地图注记图层（静态方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
+     * 创建天地图注记图层
      */
     static createAnnotationLayer(options) {
         try {
@@ -467,10 +555,32 @@ export default class MapBaseLayers {
             throw error;
         }
     }
+    /**
+     * 添加注记图层到地图（静态方法）
+     */
+    static addAnnotationLayer(map, options) {
+        try {
+            ErrorHandler.validateMap(map);
+            if (!options.token) {
+                throw new Error('Token is required for annotation layer');
+            }
+            const layer = MapBaseLayers.createAnnotationLayer({
+                type: options.type,
+                token: options.token,
+                zIndex: options.zIndex ?? ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX,
+                visible: options.visible ?? true
+            });
+            map.addLayer(layer);
+            return layer;
+        }
+        catch (error) {
+            const errorHandler = ErrorHandler.getInstance();
+            errorHandler.createAndHandleError(`Failed to add annotation layer: ${error}`, ErrorType.LAYER_ERROR, { options, error });
+            throw error;
+        }
+    }
     /**
      * 获取天地图注记图层（向后兼容的静态方法）
-     * @param options 注记图层选项
-     * @returns 创建的图层
      * @deprecated 使用 createAnnotationLayer 替代
      */
     static getAnnotationLayer(options) {
@@ -478,8 +588,6 @@ export default class MapBaseLayers {
     }
     /**
      * 创建WMTS瓦片网格
-     * @param length 层级数量
-     * @returns WMTS瓦片网格
      */
     static getTileGrid(length) {
         try {
@@ -509,77 +617,4 @@ export default class MapBaseLayers {
             throw error;
         }
     }
-    /**
-     * 移除指定类型的图层
-     * @param type 图层类型
-     */
-    removeLayersByType(type) {
-        try {
-            if (!this.layers[type]) {
-                return;
-            }
-            this.layers[type].forEach((layer) => {
-                this.map.removeLayer(layer);
-            });
-            delete this.layers[type];
-            if (this.currentBaseLayerType === type) {
-                this.currentBaseLayerType = null;
-            }
-        }
-        catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to remove layers of type '${type}': ${error}`, ErrorType.LAYER_ERROR, { type, error });
-        }
-    }
-    /**
-     * 清除所有图层
-     */
-    clearAllLayers() {
-        try {
-            for (const key in this.layers) {
-                this.layers[key]?.forEach((layer) => {
-                    this.map.removeLayer(layer);
-                });
-            }
-            // 清除注记图层
-            if (this.currentAnnotationLayer) {
-                this.map.removeLayer(this.currentAnnotationLayer);
-                this.currentAnnotationLayer = null;
-                this.currentAnnotationType = null;
-            }
-            this.layers = {};
-            this.currentBaseLayerType = null;
-        }
-        catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to clear all layers: ${error}`, ErrorType.LAYER_ERROR, { error });
-        }
-    }
-    /**
-     * 获取图层数量统计
-     * @returns 图层统计信息
-     */
-    getLayerStats() {
-        const layersByType = {};
-        let totalLayers = 0;
-        for (const key in this.layers) {
-            const count = this.layers[key]?.length || 0;
-            layersByType[key] = count;
-            totalLayers += count;
-        }
-        return {
-            totalTypes: Object.keys(this.layers).length,
-            totalLayers,
-            layersByType
-        };
-    }
-    /**
-     * 销毁实例，清理资源
-     */
-    destroy() {
-        try {
-            this.clearAllLayers();
-        }
-        catch (error) {
-            this.errorHandler.createAndHandleError(`Failed to destroy MapBaseLayers: ${error}`, ErrorType.MAP_ERROR, { error });
-        }
-    }
 }

package/core/MapTools.d.ts

@@ -87,6 +87,29 @@ export default class MapTools {
         maxZoom?: number;
         duration?: number;
     }): boolean;
+    /**
+     * 根据GeoJSON数据定位地图视图
+     * @param jsonData GeoJSON格式的数据
+     * @param fitOptions fit 参数（可选）
+     * @returns true 表示已触发定位；false 表示未得到有效范围或数据无效
+     */
+    fitByData(jsonData: MapJSONData, fitOptions?: {
+        padding?: [number, number, number, number];
+        maxZoom?: number;
+        duration?: number;
+    }): boolean;
+    /**
+     * 根据GeoJSON数据定位地图视图（静态方法）
+     * @param map 地图实例
+     * @param jsonData GeoJSON格式的数据
+     * @param fitOptions fit 参数（可选）
+     * @returns true 表示已触发定位；false 表示未得到有效范围或数据无效
+     */
+    static fitByData(map: Map, jsonData: MapJSONData, fitOptions?: {
+        padding?: [number, number, number, number];
+        maxZoom?: number;
+        duration?: number;
+    }): boolean;
     /**
      * 视图自适应到指定图层集合的整体范围（overallExtent）
      * 说明：会取每个图层 source 的 extent，合并后执行 view.fit
@@ -100,4 +123,8 @@ export default class MapTools {
         maxZoom?: number;
         duration?: number;
     }): boolean;
+    /**
+     * 执行地图定位（内部辅助方法）
+     */
+    private static executeFit;
 }

package/core/MapTools.js

@@ -1,4 +1,5 @@
 "use strict";
+import VectorSource from "ol/source/Vector";
 import GeoJSON from "ol/format/GeoJSON";
 import { ErrorHandler, ErrorType } from "../utils/ErrorHandler";
 import { ValidationUtils } from "../utils/ValidationUtils";
@@ -212,6 +213,43 @@ class MapTools {
     fitToLayers(layerNameOrLayers, fitOptions) {
         return MapTools.fitToLayers(this.map, layerNameOrLayers, fitOptions);
     }
+    /**
+     * 根据GeoJSON数据定位地图视图
+     * @param jsonData GeoJSON格式的数据
+     * @param fitOptions fit 参数（可选）
+     * @returns true 表示已触发定位；false 表示未得到有效范围或数据无效
+     */
+    fitByData(jsonData, fitOptions) {
+        return MapTools.fitByData(this.map, jsonData, fitOptions);
+    }
+    /**
+     * 根据GeoJSON数据定位地图视图（静态方法）
+     * @param map 地图实例
+     * @param jsonData GeoJSON格式的数据
+     * @param fitOptions fit 参数（可选）
+     * @returns true 表示已触发定位；false 表示未得到有效范围或数据无效
+     */
+    static fitByData(map, jsonData, fitOptions) {
+        if (!map) {
+            throw new Error('Map instance is required');
+        }
+        if (!jsonData) {
+            return false;
+        }
+        try {
+            const features = new GeoJSON().readFeatures(jsonData);
+            if (!features || features.length === 0) {
+                return false;
+            }
+            const source = new VectorSource({ features });
+            const extent = source.getExtent();
+            return MapTools.executeFit(map, extent, fitOptions, 'Error fitting view to data');
+        }
+        catch (error) {
+            ErrorHandler.getInstance().error('Error fitting view to data:', error);
+            return false;
+        }
+    }
     /**
      * 视图自适应到指定图层集合的整体范围（overallExtent）
      * 说明：会取每个图层 source 的 extent，合并后执行 view.fit
@@ -249,11 +287,20 @@ class MapTools {
                 ErrorHandler.getInstance().error('Error calculating layer extent:', error);
             }
         });
-        if (!hasValidExtent || isEmpty(overallExtent)) {
+        if (!hasValidExtent) {
+            return false;
+        }
+        return MapTools.executeFit(map, overallExtent, fitOptions, 'Error fitting view to extent');
+    }
+    /**
+     * 执行地图定位（内部辅助方法）
+     */
+    static executeFit(map, extent, fitOptions, errorMessage = 'Error fitting view') {
+        if (!extent || isEmpty(extent)) {
             return false;
         }
         try {
-            map.getView().fit(overallExtent, {
+            map.getView().fit(extent, {
                 padding: fitOptions?.padding ?? [200, 200, 200, 200],
                 maxZoom: fitOptions?.maxZoom ?? 14,
                 duration: fitOptions?.duration ?? 1500,
@@ -261,7 +308,7 @@ class MapTools {
             return true;
         }
         catch (error) {
-            ErrorHandler.getInstance().error('Error fitting view to extent:', error);
+            ErrorHandler.getInstance().error(errorMessage, error);
             return false;
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "2.3.0",
+  "version": "2.3.2",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",