my-openlayer 2.5.5 → 3.0.1

package/core/map/MapBaseLayers.js

@@ -183,6 +183,15 @@ export default class MapBaseLayers {
     getCurrentBaseLayerType() {
         return this.currentBaseLayerType;
     }
+    /**
+     * 获取当前可见底图对应的 BaseLayer 数组（多 layer 的底图类型会返回多个）。
+     * 用于 MapTools.setMapClip 等需要直接操作底图实例的场景。
+     */
+    getCurrentBaseLayers() {
+        if (!this.currentBaseLayerType)
+            return [];
+        return (this.layers[this.currentBaseLayerType] ?? []);
+    }
     /**
      * 获取默认底图类型
      * @private

package/core/map/MapTools.d.ts

@@ -34,6 +34,21 @@ export default class MapTools {
      * 注意：此方法会修改 baseLayer 的 prerender 和 postrender 事件
      */
     static setMapClip(baseLayer: BaseLayer, data: MapJSONData): BaseLayer;
+    /**
+     * 用 GeoJSON 区域裁剪地图上**所有**图层（底图 + 注记 + 用户 vector 层）。
+     *
+     * 每个图层都会绑定 prerender/postrender 进行 canvas clip。这是 setMapClip
+     * 的批量版本，用于"整张地图只在某区域内可见"的需求（例如行政区聚焦）。
+     *
+     * 实例方法 mapTools.clipMap(data) 会自动用当前 map。
+     */
+    clipMap(data: MapJSONData): void;
+    /**
+     * 用 GeoJSON 区域裁剪地图上所有图层（静态版本）。
+     * @param map 地图实例
+     * @param data 裁剪边界 GeoJSON
+     */
+    static clipMap(map: Map, data: MapJSONData): void;
     /**
      * 移除图层
      * @param layerName 图层名称
@@ -68,6 +83,7 @@ export default class MapTools {
      * @param lttd 纬度
      * @param zoom 缩放级别
      * @param duration 动画时长
+     * @param projection
      * @returns 定位是否成功
      */
     locationAction(lgtd: number, lttd: number, zoom?: number, duration?: number, projection?: {

package/core/map/MapTools.js

@@ -1,6 +1,7 @@
 "use strict";
 import VectorSource from "ol/source/Vector";
 import GeoJSON from "ol/format/GeoJSON";
+import ImageStatic from "ol/source/ImageStatic";
 import { ErrorHandler, ErrorType } from "../../utils/ErrorHandler";
 import ValidationUtils from "../../utils/ValidationUtils";
 import ProjectionUtils from "../../utils/ProjectionUtils";
@@ -133,6 +134,38 @@ class MapTools {
         });
         return baseLayer;
     }
+    /**
+     * 用 GeoJSON 区域裁剪地图上**所有**图层（底图 + 注记 + 用户 vector 层）。
+     *
+     * 每个图层都会绑定 prerender/postrender 进行 canvas clip。这是 setMapClip
+     * 的批量版本，用于"整张地图只在某区域内可见"的需求（例如行政区聚焦）。
+     *
+     * 实例方法 mapTools.clipMap(data) 会自动用当前 map。
+     */
+    clipMap(data) {
+        if (!this.map) {
+            throw new Error('Map instance is not available');
+        }
+        MapTools.clipMap(this.map, data);
+    }
+    /**
+     * 用 GeoJSON 区域裁剪地图上所有图层（静态版本）。
+     * @param map 地图实例
+     * @param data 裁剪边界 GeoJSON
+     */
+    static clipMap(map, data) {
+        if (!map) {
+            throw new Error('Map instance is required');
+        }
+        map.getLayers().getArray().forEach(layer => {
+            try {
+                MapTools.setMapClip(layer, data);
+            }
+            catch (error) {
+                ErrorHandler.getInstance().warn('clipMap: 单层裁剪失败，跳过', { layer, error });
+            }
+        });
+    }
     /**
      * 移除图层
      * @param layerName 图层名称
@@ -183,6 +216,7 @@ class MapTools {
      * @param lttd 纬度
      * @param zoom 缩放级别
      * @param duration 动画时长
+     * @param projection
      * @returns 定位是否成功
      */
     locationAction(lgtd, lttd, zoom = 20, duration = 3000, projection) {
@@ -286,7 +320,7 @@ class MapTools {
         layers.forEach((layer) => {
             try {
                 const source = layer?.getSource?.();
-                const extent = source?.getExtent?.();
+                const extent = source?.getExtent?.() ?? (source instanceof ImageStatic ? source.getImageExtent() : undefined);
                 if (extent && !isEmpty(extent)) {
                     extend(overallExtent, extent);
                     hasValidExtent = true;

package/core/point/Point.d.ts

@@ -1,7 +1,8 @@
 import Map from "ol/Map";
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
-import { PointOptions, ClusterOptions, PointData, VueTemplatePointInstance, TwinkleItem, PulsePointOptions, PulsePointLayerHandle } from '../../types';
+import Overlay from 'ol/Overlay';
+import { PointOptions, ClusterOptions, PointData, VueTemplatePointInstance, TwinkleItem, PulsePointOptions, PulsePointLayerHandle, LayerHandle, ControlHandle } from '../../types';
 export default class Point {
     private map;
     /** 由本实例创建的纯图层（addPoint / addClusterPoint）。destroyAll 时统一移除。 */
@@ -66,40 +67,65 @@ export default class Point {
      *   img: String 图标
      * }
      */
-    addPoint(pointData: PointData[], options: PointOptions): VectorLayer<VectorSource> | null;
-    addClusterPoint(pointData: PointData[], options: ClusterOptions): VectorLayer<VectorSource> | null;
+    /** *********************创建普通点图层*********************/
+    private createPointLayer;
+    /** *********************创建聚合点图层*********************/
+    private createClusterPointLayer;
+    /** *********************添加普通点*********************/
+    addPoint(pointData: PointData[], options: PointOptions & {
+        layerName: string;
+    }): LayerHandle<VectorLayer<VectorSource>> | null;
+    /** *********************添加聚合点*********************/
+    addClusterPoint(pointData: PointData[], options: ClusterOptions & {
+        layerName: string;
+    }): LayerHandle<VectorLayer<VectorSource>> | null;
+    /** @internal 把 VectorLayer 包成 LayerHandle 的内部工具。 */
+    private toLayerHandle;
     /**
      * 添加高性能闪烁点图层。
      *
      * 与 addDomPoint 不同，该方法使用 VectorLayer 批量渲染点位，并通过单个
      * requestAnimationFrame 驱动闪烁圈，适合村庄预警等大量点位场景。
      */
-    addPulsePointLayer(pointData: PointData[], options: PulsePointOptions): PulsePointLayerHandle | null;
+    addPulsePointLayer(pointData: PointData[], options: PulsePointOptions & {
+        layerName: string;
+    }): PulsePointLayerHandle | null;
+    /**
+     * P1-2：从 URL 加载点位数据并添加为静态点图层。
+     *
+     * 期望 URL 返回 `PointData[]` 形态的 JSON 数组（含 lgtd / lttd）或 FeatureCollection。
+     * features 加载/解析完成后 Promise resolve 为 LayerHandle。
+     */
+    addPointByUrl(url: string, options: PointOptions & {
+        layerName: string;
+    }): Promise<LayerHandle<VectorLayer<VectorSource>> | null>;
+    /**
+     * P1-2：从 URL 加载点位数据并添加为高性能闪烁点图层。
+     */
+    addPulsePointLayerByUrl(url: string, options: PulsePointOptions & {
+        layerName: string;
+    }): Promise<PulsePointLayerHandle | null>;
     /**
      * 添加闪烁点
      * @param twinkleList 闪烁点数据
      * @param callback
      */
-    addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
-        anchors: import('ol/Overlay').default[];
-        remove: () => void;
-        setVisible: (visible: boolean) => void;
+    addDomPoint(twinkleList: TwinkleItem[], callback?: Function): ControlHandle<Overlay[]> & {
+        anchors: Overlay[];
     };
     /**
      * 添加vue组件为点位
      * @param pointDataList 点位信息列表
      * @param template vue组件模板
-     * @param Vue Vue实例
+     * @param options
      * @returns 返回控制对象，包含显示、隐藏、移除方法
      * @throws 当参数无效时抛出错误
      */
-    addVueTemplatePoint(pointDataList: PointData[], template: any, options?: {
+    addVueTemplatePoint(pointDataList: PointData[], template: object, options?: {
         positioning?: 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center-left' | 'center-center' | 'center-right' | 'top-left' | 'top-center' | 'top-right';
         stopEvent?: boolean;
-    }): {
-        setVisible: (visible: boolean) => void;
-        setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void;
-        remove: () => void;
+    }): ControlHandle<VueTemplatePointInstance[]> & {
+        setOneVisibleByProp: (propName: string, propValue: unknown, visible: boolean) => void;
         getPoints: () => VueTemplatePointInstance[];
     };
     /**

package/core/point/Point.js

@@ -102,7 +102,7 @@ export default class Point {
     createPointStyle(options, item) {
         const style = {};
         if (options.textKey && item) {
-            style.text = this.createTextStyle(options, item[options.textKey]);
+            style.text = this.createTextStyle(options, String(item[options.textKey] ?? ''));
         }
         if (options.img) {
             style.image = this.createIconStyle(options);
@@ -145,7 +145,8 @@ export default class Point {
      *   img: String 图标
      * }
      */
-    addPoint(pointData, options) {
+    /** *********************创建普通点图层*********************/
+    createPointLayer(pointData, options) {
         if (!ValidationUtils.validatePointData(pointData)) {
             return null;
         }
@@ -187,7 +188,8 @@ export default class Point {
         this.trackLayer(PointVectorLayer);
         return PointVectorLayer;
     }
-    addClusterPoint(pointData, options) {
+    /** *********************创建聚合点图层*********************/
+    createClusterPointLayer(pointData, options) {
         if (!ValidationUtils.validatePointData(pointData)) {
             return null;
         }
@@ -197,6 +199,33 @@ export default class Point {
         }
         return layer;
     }
+    /** *********************添加普通点*********************/
+    addPoint(pointData, options) {
+        const layer = this.createPointLayer(pointData, options);
+        if (!layer)
+            return null;
+        return this.toLayerHandle(layer);
+    }
+    /** *********************添加聚合点*********************/
+    addClusterPoint(pointData, options) {
+        const layer = this.createClusterPointLayer(pointData, options);
+        if (!layer)
+            return null;
+        return this.toLayerHandle(layer);
+    }
+    /** @internal 把 VectorLayer 包成 LayerHandle 的内部工具。 */
+    toLayerHandle(layer) {
+        const map = this.map;
+        const managedLayers = this.managedLayers;
+        return {
+            layer,
+            setVisible(visible) { layer.setVisible(visible); },
+            remove() {
+                managedLayers.delete(layer);
+                map.removeLayer(layer);
+            }
+        };
+    }
     /**
      * 添加高性能闪烁点图层。
      *
@@ -211,6 +240,43 @@ export default class Point {
         this.trackDisposable(handle);
         return handle;
     }
+    /**
+     * P1-2：从 URL 加载点位数据并添加为静态点图层。
+     *
+     * 期望 URL 返回 `PointData[]` 形态的 JSON 数组（含 lgtd / lttd）或 FeatureCollection。
+     * features 加载/解析完成后 Promise resolve 为 LayerHandle。
+     */
+    async addPointByUrl(url, options) {
+        ValidationUtils.validateNonEmptyString(url, 'Point url is required');
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch point data: ${response.status}`);
+        }
+        const json = await response.json();
+        const pointData = Array.isArray(json) ? json : (json?.features ?? []).map((f) => ({
+            ...f.properties,
+            lgtd: f.geometry?.coordinates?.[0],
+            lttd: f.geometry?.coordinates?.[1]
+        }));
+        return this.addPoint(pointData, options);
+    }
+    /**
+     * P1-2：从 URL 加载点位数据并添加为高性能闪烁点图层。
+     */
+    async addPulsePointLayerByUrl(url, options) {
+        ValidationUtils.validateNonEmptyString(url, 'Pulse point url is required');
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch pulse point data: ${response.status}`);
+        }
+        const json = await response.json();
+        const pointData = Array.isArray(json) ? json : (json?.features ?? []).map((f) => ({
+            ...f.properties,
+            lgtd: f.geometry?.coordinates?.[0],
+            lttd: f.geometry?.coordinates?.[1]
+        }));
+        return this.addPulsePointLayer(pointData, options);
+    }
     /**
      * 添加闪烁点
      * @param twinkleList 闪烁点数据
@@ -225,7 +291,7 @@ export default class Point {
      * 添加vue组件为点位
      * @param pointDataList 点位信息列表
      * @param template vue组件模板
-     * @param Vue Vue实例
+     * @param options
      * @returns 返回控制对象，包含显示、隐藏、移除方法
      * @throws 当参数无效时抛出错误
      */

package/core/point/PointOverlay.d.ts

@@ -1,13 +1,11 @@
 import Overlay from 'ol/Overlay';
 import Map from 'ol/Map';
-import type { TwinkleItem } from '../../types';
+import type { ControlHandle, TwinkleItem } from '../../types';
 /**
  * DOM 点位覆盖物构建器。
  */
 export default class PointOverlay {
-    static create(map: Map, twinkleList: TwinkleItem[], callback?: Function): {
+    static create(map: Map, twinkleList: TwinkleItem[], callback?: Function): ControlHandle<Overlay[]> & {
         anchors: Overlay[];
-        remove: () => void;
-        setVisible: (visible: boolean) => void;
     };
 }

package/core/point/PointOverlay.js

@@ -36,13 +36,14 @@ export default class PointOverlay {
             anchors.push(anchor);
         });
         return {
+            target: anchors,
             anchors,
             remove: () => {
                 anchors.forEach(anchor => {
                     anchor.getElement()?.remove();
                     map.removeOverlay(anchor);
                 });
-                anchors = [];
+                anchors.splice(0, anchors.length);
             },
             setVisible: (visible) => {
                 anchors.forEach(anchor => {

package/core/point/PointPulseLayer.js

@@ -84,7 +84,7 @@ export default class PointPulseLayer {
         });
         const createStyles = (feature) => {
             const rawData = feature.get('rawData');
-            const level = rawData?.[levelKey] ?? 'default';
+            const level = String(rawData?.[levelKey] ?? 'default');
             const progress = frameIndex / Math.max(1, pulseOptions.frameCount - 1);
             const [minRadius, maxRadius] = pulseOptions.radius;
             const radius = minRadius + (maxRadius - minRadius) * progress;
@@ -110,9 +110,11 @@ export default class PointPulseLayer {
                 }
                 styles.push(pulseStyle);
             }
-            const text = options.textVisible && options.textKey && rawData ? rawData[options.textKey] ?? '' : '';
+            const text = options.textVisible && options.textKey && rawData ? String(rawData[options.textKey] ?? '') : '';
+            // P1-4: icon.img 是新名，icon.src 保留兼容（@deprecated）
+            const iconImg = options.icon?.img ?? options.icon?.src;
             const staticCacheKey = [
-                options.img ?? options.icon?.src ?? '',
+                options.img ?? iconImg ?? '',
                 options.scale ?? options.icon?.scale ?? ConfigManager.DEFAULT_POINT_ICON_SCALE,
                 options.iconColor ?? options.icon?.color ?? '',
                 text
@@ -123,7 +125,7 @@ export default class PointPulseLayer {
                 return styles;
             }
             const pointStyleOptions = {};
-            const iconSrc = options.img ?? options.icon?.src;
+            const iconSrc = options.img ?? iconImg;
             if (iconSrc) {
                 pointStyleOptions.image = new Icon({
                     src: iconSrc,

package/core/polygon/Polygon.d.ts

@@ -3,7 +3,7 @@ import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import { Image as ImageLayer } from "ol/layer";
 import Feature from "ol/Feature";
-import { PolygonOptions, MapJSONData, PointData, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions } from '../../types';
+import { PolygonOptions, MapJSONData, PointData, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions, LayerHandle } from '../../types';
 /**
  * Polygon 类用于处理地图上的面要素操作
  * 包括添加多边形、边框、图片图层、热力图等功能
@@ -24,6 +24,8 @@ export default class Polygon {
      * @internal
      */
     private trackLayer;
+    /** *********************统一句柄：OL 图层*********************/
+    private toLayerHandle;
     /**
      * 销毁本实例创建的所有图层。供 MyOl.destroy 调用。
      */
@@ -35,7 +37,7 @@ export default class Polygon {
      * @returns 创建的图层实例
      * @throws 当数据格式无效时抛出错误
      */
-    addBorderPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>;
+    addBorderPolygon(data: MapJSONData, options?: PolygonOptions): LayerHandle<VectorLayer<VectorSource>>;
     /**
      * 从URL添加地图边框图层
      * @param url 数据URL
@@ -43,7 +45,7 @@ export default class Polygon {
      * @returns 创建的图层实例
      * @throws 当数据格式无效时抛出错误
      */
-    addBorderPolygonByUrl(url: string, options?: PolygonOptions): VectorLayer<VectorSource>;
+    addBorderPolygonByUrl(url: string, options?: PolygonOptions): Promise<LayerHandle<VectorLayer<VectorSource>>>;
     /**
      * 添加多边形图层
      * @param dataJSON GeoJSON 数据
@@ -51,15 +53,16 @@ export default class Polygon {
      * @returns 创建的矢量图层
      * @throws 当数据格式无效时抛出错误
      */
-    addPolygon(dataJSON: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>;
-    /**
-     * 从URL添加多边形图层
-     * @param url 数据URL
-     * @param options 图层配置选项
-     * @returns 创建的矢量图层
-     * @throws 当数据格式无效时抛出错误
-     */
-    addPolygonByUrl(url: string, options?: PolygonOptions): VectorLayer<VectorSource>;
+    /** *********************创建多边形图层*********************/
+    private createPolygonLayer;
+    /** *********************添加多边形图层*********************/
+    addPolygon(dataJSON: MapJSONData, options: PolygonOptions & {
+        layerName: string;
+    }): LayerHandle<VectorLayer<VectorSource>>;
+    /** *********************从 URL 添加多边形图层*********************/
+    addPolygonByUrl(url: string, options: PolygonOptions & {
+        layerName: string;
+    }): Promise<LayerHandle<VectorLayer<VectorSource>>>;
     /**
      * 适应图层视图
      * @param layer 图层对象
@@ -85,7 +88,7 @@ export default class Polygon {
      */
     setOutLayer(data: MapJSONData, options?: {
         layerName?: string;
-        extent?: any;
+        extent?: number[];
         fillColor?: string;
         strokeWidth?: number;
         strokeColor?: string;
@@ -98,13 +101,13 @@ export default class Polygon {
      * @returns 创建的图片图层
      * @throws 当数据格式无效时抛出错误
      */
-    addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): ImageLayer<any>;
+    addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): LayerHandle<ImageLayer<any>>;
     /**
      * 添加热力图图层
      * @param pointData 点数据数组
      * @param options 热力图配置
      */
-    addHeatmap(pointData: PointData[], options?: HeatMapOptions): import("ol/layer").Heatmap<Feature<import("ol/geom").Geometry>, VectorSource<Feature<import("ol/geom").Geometry>>>;
+    addHeatmap(pointData: PointData[], options?: HeatMapOptions): LayerHandle<import("ol/layer").Heatmap<Feature<import("ol/geom").Geometry>, VectorSource<Feature<import("ol/geom").Geometry>>>>;
     /**
      * 添加遮罩图层
      * @param data GeoJSON格式的遮罩数据
@@ -112,6 +115,6 @@ export default class Polygon {
      * @returns 创建的遮罩图层
      * @throws 当数据格式无效时抛出错误
      */
-    addMaskLayer(data: any, options?: MaskLayerOptions): VectorLayer<VectorSource>;
+    addMaskLayer(data: MapJSONData, options?: MaskLayerOptions): LayerHandle<VectorLayer<VectorSource>>;
     removePolygonLayer(layerName: string): void;
 }

package/core/polygon/Polygon.js

@@ -2,7 +2,7 @@
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import GeoJSON from "ol/format/GeoJSON";
-import { ErrorHandler } from '../../utils/ErrorHandler';
+import { ErrorHandler, InvalidGeoJSONError, LayerNotFoundError } from '../../utils/ErrorHandler';
 import ProjectionUtils from '../../utils/ProjectionUtils';
 import ValidationUtils from '../../utils/ValidationUtils';
 import { ConfigManager, MapTools } from "../map";
@@ -37,6 +37,19 @@ export default class Polygon {
         this.managedLayers.add(layer);
         return layer;
     }
+    /** *********************统一句柄：OL 图层*********************/
+    toLayerHandle(layer) {
+        const map = this.map;
+        const managedLayers = this.managedLayers;
+        return {
+            layer,
+            setVisible(visible) { layer.setVisible(visible); },
+            remove() {
+                managedLayers.delete(layer);
+                map.removeLayer(layer);
+            }
+        };
+    }
     /**
      * 销毁本实例创建的所有图层。供 MyOl.destroy 调用。
      */
@@ -62,13 +75,14 @@ export default class Polygon {
         ValidationUtils.validateGeoJSONData(data);
         const mergedOptions = {
             fillColor: 'rgba(255, 255, 255, 0)',
-            ...options
+            ...options,
+            layerName: options?.layerName ?? 'border'
         };
-        const layer = this.addPolygon(data, mergedOptions);
+        const handle = this.addPolygon(data, mergedOptions);
         if (mergedOptions.mask) {
             this.setOutLayer(data);
         }
-        return layer;
+        return handle;
     }
     /**
      * 从URL添加地图边框图层
@@ -77,14 +91,13 @@ export default class Polygon {
      * @returns 创建的图层实例
      * @throws 当数据格式无效时抛出错误
      */
-    addBorderPolygonByUrl(url, options) {
+    async addBorderPolygonByUrl(url, options) {
         const mergedOptions = {
-            layerName: 'border',
             fillColor: 'rgba(255, 255, 255, 0)',
-            ...options
+            ...options,
+            layerName: options?.layerName ?? 'border'
         };
-        const layer = this.addPolygonByUrl(url, mergedOptions);
-        return layer;
+        return this.addPolygonByUrl(url, mergedOptions);
     }
     /**
      * 添加多边形图层
@@ -93,7 +106,8 @@ export default class Polygon {
      * @returns 创建的矢量图层
      * @throws 当数据格式无效时抛出错误
      */
-    addPolygon(dataJSON, options) {
+    /** *********************创建多边形图层*********************/
+    createPolygonLayer(dataJSON, options) {
         ValidationUtils.validateGeoJSONData(dataJSON);
         const mergedOptions = {
             ...ConfigManager.DEFAULT_POLYGON_OPTIONS,
@@ -118,7 +132,7 @@ export default class Polygon {
             features = format.readFeatures(dataJSON, ProjectionUtils.getGeoJSONReadOptions(mergedOptions));
         }
         catch (error) {
-            throw new Error(`Failed to parse GeoJSON data: ${error}`);
+            throw new InvalidGeoJSONError(error instanceof Error ? error.message : String(error), { layerName: mergedOptions.layerName });
         }
         const layer = new VectorLayer({
             properties: {
@@ -138,55 +152,19 @@ export default class Polygon {
         }
         return layer;
     }
-    /**
-     * 从URL添加多边形图层
-     * @param url 数据URL
-     * @param options 图层配置选项
-     * @returns 创建的矢量图层
-     * @throws 当数据格式无效时抛出错误
-     */
-    addPolygonByUrl(url, options) {
-        const mergedOptions = {
-            ...ConfigManager.DEFAULT_POLYGON_OPTIONS,
-            ...options
-        };
-        // 如果指定了图层名称，先移除同名图层
-        if (mergedOptions.layerName) {
-            new MapTools(this.map).removeLayer(mergedOptions.layerName);
-        }
-        const format = new GeoJSON(ProjectionUtils.getGeoJSONReadOptions(mergedOptions));
-        // 优化：在解析 Feature 时直接注入 layerName，利用解析过程的遍历，避免解析后的二次循环
-        if (mergedOptions.layerName) {
-            const originalReadFeatureFromObject = format.readFeatureFromObject;
-            format.readFeatureFromObject = function (object, options) {
-                const feature = originalReadFeatureFromObject.call(this, object, options);
-                feature.set('layerName', mergedOptions.layerName, true); // true 表示静默设置，不触发事件
-                return feature;
-            };
-        }
-        const source = new VectorSource({
-            url,
-            format
-        });
-        const layer = new VectorLayer({
-            properties: {
-                name: mergedOptions.layerName,
-                layerName: mergedOptions.layerName
-            },
-            source,
-            style: PolygonStyleFactory.createStyle(mergedOptions),
-            zIndex: mergedOptions.zIndex
-        });
-        layer.setVisible(mergedOptions.visible);
-        this.map.addLayer(layer);
-        this.trackLayer(layer);
-        // 如果需要适应视图
-        if (mergedOptions.fitView) {
-            source.once('featuresloadend', () => {
-                this.fitViewToLayer(layer);
-            });
+    /** *********************添加多边形图层*********************/
+    addPolygon(dataJSON, options) {
+        return this.toLayerHandle(this.createPolygonLayer(dataJSON, options));
+    }
+    /** *********************从 URL 添加多边形图层*********************/
+    async addPolygonByUrl(url, options) {
+        ValidationUtils.validateNonEmptyString(url, 'Polygon url is required');
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch polygon GeoJSON: ${response.status}`);
         }
-        return layer;
+        const json = await response.json();
+        return this.addPolygon(json, options);
     }
     /**
      * 适应图层视图
@@ -209,7 +187,7 @@ export default class Polygon {
         ValidationUtils.validateLayerName(layerName);
         const layers = MapTools.getLayerByLayerName(this.map, layerName);
         if (layers.length === 0) {
-            throw new Error(`Layer with name '${layerName}' not found`);
+            throw new LayerNotFoundError(layerName, { method: 'updateFeatureColor' });
         }
         const layer = layers[0];
         if (!(layer instanceof VectorLayer)) {
@@ -255,7 +233,7 @@ export default class Polygon {
     addImageLayer(imageData, options) {
         const layer = PolygonImageLayer.addImageLayer(this.map, imageData, options);
         this.trackLayer(layer);
-        return layer;
+        return this.toLayerHandle(layer);
     }
     /**
      * 添加热力图图层
@@ -267,7 +245,7 @@ export default class Polygon {
         if (layer) {
             this.trackLayer(layer);
         }
-        return layer;
+        return this.toLayerHandle(layer);
     }
     /**
      * 添加遮罩图层
@@ -279,7 +257,7 @@ export default class Polygon {
     addMaskLayer(data, options) {
         const layer = PolygonMaskLayer.addMaskLayer(this.map, data, options);
         this.trackLayer(layer);
-        return layer;
+        return this.toLayerHandle(layer);
     }
     removePolygonLayer(layerName) {
         new MapTools(this.map).removeLayer(layerName);