my-openlayer 2.5.4 → 3.0.1

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";
@@ -20,11 +20,50 @@ export default class Polygon {
      * @param map OpenLayers 地图实例
      */
     constructor(map) {
+        /**
+         * 由本实例创建的所有图层句柄（含 mask 子图层等）。destroyAll 时统一回收，避免地图销毁后图层泄漏。
+         */
+        this.managedLayers = new Set();
         if (!map) {
             throw new Error('Map instance is required');
         }
         this.map = map;
     }
+    /**
+     * 跟踪一个本实例创建的图层，便于销毁阶段统一清理。
+     * @internal
+     */
+    trackLayer(layer) {
+        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 调用。
+     */
+    destroyAll() {
+        this.managedLayers.forEach(layer => {
+            try {
+                this.map.removeLayer(layer);
+            }
+            catch {
+                // ignore
+            }
+        });
+        this.managedLayers.clear();
+    }
     /**
      * 添加地图边框图层
      * @param data 图层数据，必须是有效的 GeoJSON 格式
@@ -36,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添加地图边框图层
@@ -51,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);
     }
     /**
      * 添加多边形图层
@@ -67,7 +106,8 @@ export default class Polygon {
      * @returns 创建的矢量图层
      * @throws 当数据格式无效时抛出错误
      */
-    addPolygon(dataJSON, options) {
+    /** *********************创建多边形图层*********************/
+    createPolygonLayer(dataJSON, options) {
         ValidationUtils.validateGeoJSONData(dataJSON);
         const mergedOptions = {
             ...ConfigManager.DEFAULT_POLYGON_OPTIONS,
@@ -92,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: {
@@ -105,60 +145,26 @@ export default class Polygon {
         });
         layer.setVisible(mergedOptions.visible);
         this.map.addLayer(layer);
+        this.trackLayer(layer);
         // 如果需要适应视图
         if (mergedOptions.fitView) {
             this.fitViewToLayer(layer);
         }
         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);
-        // 如果需要适应视图
-        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);
     }
     /**
      * 适应图层视图
@@ -181,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)) {
@@ -211,7 +217,11 @@ export default class Polygon {
      * @param options
      */
     setOutLayer(data, options) {
-        return PolygonMaskLayer.setOutLayer(this.map, data, options);
+        const layer = PolygonMaskLayer.setOutLayer(this.map, data, options);
+        if (layer) {
+            this.trackLayer(layer);
+        }
+        return layer;
     }
     /**
      * 添加图片图层
@@ -221,7 +231,9 @@ export default class Polygon {
      * @throws 当数据格式无效时抛出错误
      */
     addImageLayer(imageData, options) {
-        return PolygonImageLayer.addImageLayer(this.map, imageData, options);
+        const layer = PolygonImageLayer.addImageLayer(this.map, imageData, options);
+        this.trackLayer(layer);
+        return this.toLayerHandle(layer);
     }
     /**
      * 添加热力图图层
@@ -229,7 +241,11 @@ export default class Polygon {
      * @param options 热力图配置
      */
     addHeatmap(pointData, options) {
-        return PolygonHeatmapLayer.addHeatmap(this.map, pointData, options);
+        const layer = PolygonHeatmapLayer.addHeatmap(this.map, pointData, options);
+        if (layer) {
+            this.trackLayer(layer);
+        }
+        return this.toLayerHandle(layer);
     }
     /**
      * 添加遮罩图层
@@ -239,10 +255,17 @@ export default class Polygon {
      * @throws 当数据格式无效时抛出错误
      */
     addMaskLayer(data, options) {
-        return PolygonMaskLayer.addMaskLayer(this.map, data, options);
+        const layer = PolygonMaskLayer.addMaskLayer(this.map, data, options);
+        this.trackLayer(layer);
+        return this.toLayerHandle(layer);
     }
     removePolygonLayer(layerName) {
         new MapTools(this.map).removeLayer(layerName);
-        this[layerName] = null;
+        // 从 managedLayers 中也移除对应记录
+        this.managedLayers.forEach(layer => {
+            if (layer.get('layerName') === layerName || layer.get('name') === layerName) {
+                this.managedLayers.delete(layer);
+            }
+        });
     }
 }

package/core/polygon/PolygonHeatmapLayer.js

@@ -3,6 +3,7 @@ import { Point } from "ol/geom";
 import { Heatmap } from "ol/layer";
 import VectorSource from "ol/source/Vector";
 import { ConfigManager, MapTools } from "../map";
+import { ErrorHandler } from "../../utils/ErrorHandler";
 /**
  * 面热力图辅助类。
  */
@@ -28,11 +29,23 @@ export default class PolygonHeatmapLayer {
         }
         map.addLayer(heatmapLayer);
         const valueKey = mergedOptions.valueKey || ConfigManager.DEFAULT_HEATMAP_VALUE_KEY;
-        const max = Math.max(...pointData.map(item => item[valueKey]));
+        // 计算归一化最大值。当数据里没有 valueKey 或值全为非数字时，max 是 NaN/-Infinity，
+        // 会导致 weight = value/max = NaN，OL 热力图整层不渲染。
+        // 此时回退到等权重 1（让用户至少看到热力图，再去补 valueKey）。
+        const numericValues = pointData
+            .map(item => Number(item[valueKey]))
+            .filter(v => Number.isFinite(v));
+        const max = numericValues.length > 0 ? Math.max(...numericValues) : 0;
+        const useFallbackWeight = max <= 0;
+        if (useFallbackWeight) {
+            ErrorHandler.getInstance().warn(`[Heatmap] 数据中未找到有效的 "${valueKey}" 字段，已回退为等权重渲染。请通过 options.valueKey 指定正确字段。`);
+        }
         pointData.forEach(item => {
+            const raw = Number(item[valueKey]);
+            const weight = useFallbackWeight || !Number.isFinite(raw) ? 1 : raw / max;
             heatmapLayer.getSource().addFeature(new Feature({
                 geometry: new Point([item.lgtd, item.lttd]),
-                weight: item[valueKey] / max
+                weight
             }));
         });
         return heatmapLayer;

package/core/polygon/PolygonMaskLayer.d.ts

@@ -10,11 +10,11 @@ import type { MapJSONData, MaskLayerOptions } from "../../types";
 export default class PolygonMaskLayer {
     static setOutLayer(map: Map, data: MapJSONData, options?: {
         layerName?: string;
-        extent?: any;
+        extent?: number[];
         fillColor?: string;
         strokeWidth?: number;
         strokeColor?: string;
         zIndex?: number;
     }): VectorLayer<VectorSource<Feature<Geometry>>, Feature<Geometry>>;
-    static addMaskLayer(map: Map, data: any, options?: MaskLayerOptions): VectorLayer<VectorSource>;
+    static addMaskLayer(map: Map, data: MapJSONData, options?: MaskLayerOptions): VectorLayer<VectorSource>;
 }

package/core/polygon/PolygonMaskLayer.js

@@ -98,7 +98,9 @@ export default class PolygonMaskLayer {
                 }) : undefined
             }),
             opacity: mergedOptions.opacity,
-            visible: mergedOptions.visible
+            visible: mergedOptions.visible,
+            // 显式传 zIndex，否则被天地图底图（zIndex 9）盖住，用户看不到 mask
+            zIndex: mergedOptions.zIndex
         });
         maskLayer.set('layerName', mergedOptions.layerName);
         map.addLayer(maskLayer);

package/core/polygon/PolygonStyleFactory.d.ts

@@ -1,11 +1,12 @@
-import Feature from "ol/Feature";
+import Feature, { type FeatureLike } from "ol/Feature";
+import { Style } from "ol/style";
 import type { FeatureColorUpdateOptions, PolygonOptions } from "../../types";
 /**
  * 面图层样式工厂。
  */
 export default class PolygonStyleFactory {
-    static getFeatureText(feature: Feature, options: PolygonOptions | FeatureColorUpdateOptions): string;
-    static createStyle(options: PolygonOptions): any;
+    static getFeatureText(feature: FeatureLike, options: PolygonOptions | FeatureColorUpdateOptions): string;
+    static createStyle(options: PolygonOptions): Style | Style[] | ((feature: FeatureLike) => Style | Style[]);
     static updateSingleFeatureColor(feature: Feature, colorObj?: {
         [propName: string]: string;
     }, options?: FeatureColorUpdateOptions): void;

package/core/projection/ProjectionManager.d.ts

@@ -0,0 +1,66 @@
+import { Projection as olProjProjection } from "ol/proj";
+import type { Units } from "ol/proj/Units";
+import type { MapInitType } from "../../types";
+/**
+ * 项目内置 EPSG 编码。
+ */
+export declare const PROJECTIONS: {
+    readonly WGS84: "EPSG:4326";
+    readonly CGCS2000: "EPSG:4490";
+    readonly CGCS2000_3_DEGREE: "EPSG:4549";
+};
+/**
+ * 自定义投影注册元数据。
+ */
+export interface CustomProjectionRegistration {
+    /** EPSG 编码，例如 "EPSG:4528" */
+    code: string;
+    /** proj4 定义字符串 */
+    def: string;
+    /** 投影范围 [minX, minY, maxX, maxY] */
+    extent?: number[];
+    /** 世界范围 [minX, minY, maxX, maxY] */
+    worldExtent?: number[];
+    /** OL 投影单位（degrees / m / ft 等），未提供时从 proj4 定义自动推导 */
+    units?: Units;
+}
+export default class ProjectionManager {
+    /** 项目内置 EPSG 编码常量。 */
+    static readonly PROJECTIONS: {
+        readonly WGS84: "EPSG:4326";
+        readonly CGCS2000: "EPSG:4490";
+        readonly CGCS2000_3_DEGREE: "EPSG:4549";
+    };
+    /** 默认投影 = EPSG:4490 (CGCS2000)。 */
+    static readonly DEFAULT_PROJECTION: "EPSG:4490";
+    /**
+     * 注册内置投影 + 应用 options.projection 自定义投影。
+     *
+     * 幂等：重复调用安全。被 MyOl 构造函数和 MyOl.createView 都会调，外部一般无需直接调用。
+     */
+    static initialize(options?: MapInitType): void;
+    /**
+     * 注册一个任意 EPSG 投影到 proj4 + OL。
+     *
+     * 这是 MyOl 之外的便利入口。units 未提供时由 proj4 自动推导。
+     */
+    static register(registration: CustomProjectionRegistration): void;
+    /**
+     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
+     *
+     * 仅当 options 显式覆盖 extent / worldExtent / units 之一时才新建 Projection 实例。
+     */
+    static resolveViewProjection(options: MapInitType, code: string): olProjProjection;
+    /**
+     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
+     */
+    private static ensureProj4Definition;
+    /**
+     * 应用用户显式提供的投影元数据。
+     *
+     * - 提供 units：以用户输入为权威，覆盖已注册投影
+     * - 未提供 units 但已注册：仅刷新 extent / worldExtent
+     * - 未提供 units 且未注册：新建 Projection（OL 会从 proj4 推导单位）
+     */
+    private static applyCustomProjectionMetadata;
+}

package/core/projection/ProjectionManager.js

@@ -0,0 +1,144 @@
+/**
+ * 投影管理器
+ *
+ * 集中管理所有投影注册与解析逻辑，对外暴露内置常量（EPSG:4326 / 4490 / 4549）以及
+ * 自定义投影注册入口。MyOl 内部委托此类初始化投影，使用户也可以在 MyOl 实例之外
+ * 主动注册新的 EPSG。
+ */
+import proj4 from "proj4";
+import { register as olProj4Register } from "ol/proj/proj4";
+import { Projection as olProjProjection, addProjection as olProjAddProjection, get as olProjGetProjection } from "ol/proj";
+/**
+ * 项目内置 EPSG 编码。
+ */
+export const PROJECTIONS = {
+    WGS84: "EPSG:4326",
+    CGCS2000: "EPSG:4490",
+    CGCS2000_3_DEGREE: "EPSG:4549"
+};
+/**
+ * 内置 EPSG 的 proj4 定义字符串。
+ */
+const PROJECTION_DEFINITIONS = {
+    [PROJECTIONS.WGS84]: "+title=WGS 84 (long/lat) +proj=longlat +ellps=WGS84 +datum=WGS84 +units=degrees",
+    [PROJECTIONS.CGCS2000]: "+proj=longlat +ellps=GRS80 +no_defs",
+    [PROJECTIONS.CGCS2000_3_DEGREE]: "+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=500000 +y_0=0 +ellps=GRS80 +units=m +no_defs"
+};
+class ProjectionManager {
+    /**
+     * 注册内置投影 + 应用 options.projection 自定义投影。
+     *
+     * 幂等：重复调用安全。被 MyOl 构造函数和 MyOl.createView 都会调，外部一般无需直接调用。
+     */
+    static initialize(options) {
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.WGS84, PROJECTION_DEFINITIONS[PROJECTIONS.WGS84]);
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.CGCS2000, PROJECTION_DEFINITIONS[PROJECTIONS.CGCS2000]);
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.CGCS2000_3_DEGREE, PROJECTION_DEFINITIONS[PROJECTIONS.CGCS2000_3_DEGREE]);
+        // 用户自定义投影的 proj4 定义优先注入
+        if (options?.projection?.code && options.projection.def) {
+            proj4.defs(options.projection.code, options.projection.def);
+        }
+        // 注入 proj4 → OpenLayers
+        olProj4Register(proj4);
+        // 注册 CGCS2000 OL Projection（带 degrees 单位）
+        olProjAddProjection(new olProjProjection({
+            code: PROJECTIONS.CGCS2000,
+            extent: [-180, -90, 180, 90],
+            worldExtent: [-180, -90, 180, 90],
+            units: "degrees"
+        }));
+        if (options?.projection?.code) {
+            ProjectionManager.applyCustomProjectionMetadata(options.projection);
+        }
+    }
+    /**
+     * 注册一个任意 EPSG 投影到 proj4 + OL。
+     *
+     * 这是 MyOl 之外的便利入口。units 未提供时由 proj4 自动推导。
+     */
+    static register(registration) {
+        const { code, def, extent, worldExtent, units } = registration;
+        ProjectionManager.ensureProj4Definition(code, def);
+        olProj4Register(proj4);
+        ProjectionManager.applyCustomProjectionMetadata({
+            code,
+            def,
+            extent,
+            worldExtent,
+            units
+        });
+    }
+    /**
+     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
+     *
+     * 仅当 options 显式覆盖 extent / worldExtent / units 之一时才新建 Projection 实例。
+     */
+    static resolveViewProjection(options, code) {
+        const registeredProjection = olProjGetProjection(code);
+        if (registeredProjection
+            && !options.projection?.extent
+            && !options.projection?.worldExtent
+            && !options.projection?.units) {
+            return registeredProjection;
+        }
+        return new olProjProjection({
+            code,
+            extent: options.projection?.extent
+                ?? registeredProjection?.getExtent()
+                ?? [-180, -90, 180, 90],
+            worldExtent: options.projection?.worldExtent
+                ?? registeredProjection?.getWorldExtent()
+                ?? [-180, -90, 180, 90],
+            units: options.projection?.units
+                ?? registeredProjection?.getUnits()
+                ?? "degrees"
+        });
+    }
+    /**
+     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
+     */
+    static ensureProj4Definition(code, definition) {
+        if (!proj4.defs(code)) {
+            proj4.defs(code, definition);
+        }
+    }
+    /**
+     * 应用用户显式提供的投影元数据。
+     *
+     * - 提供 units：以用户输入为权威，覆盖已注册投影
+     * - 未提供 units 但已注册：仅刷新 extent / worldExtent
+     * - 未提供 units 且未注册：新建 Projection（OL 会从 proj4 推导单位）
+     */
+    static applyCustomProjectionMetadata(projection) {
+        const { code, extent, worldExtent, units } = projection;
+        const registeredProjection = olProjGetProjection(code);
+        if (units) {
+            olProjAddProjection(new olProjProjection({
+                code,
+                extent: extent ?? registeredProjection?.getExtent(),
+                worldExtent: worldExtent ?? registeredProjection?.getWorldExtent(),
+                units
+            }));
+            return;
+        }
+        if (registeredProjection) {
+            if (extent)
+                registeredProjection.setExtent(extent);
+            if (worldExtent)
+                registeredProjection.setWorldExtent(worldExtent);
+            return;
+        }
+        if (extent || worldExtent) {
+            olProjAddProjection(new olProjProjection({
+                code,
+                extent,
+                worldExtent
+            }));
+        }
+    }
+}
+/** 项目内置 EPSG 编码常量。 */
+ProjectionManager.PROJECTIONS = PROJECTIONS;
+/** 默认投影 = EPSG:4490 (CGCS2000)。 */
+ProjectionManager.DEFAULT_PROJECTION = PROJECTIONS.CGCS2000;
+export default ProjectionManager;

package/core/projection/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ProjectionManager, PROJECTIONS } from './ProjectionManager';
+export type { CustomProjectionRegistration } from './ProjectionManager';

package/core/projection/index.js

@@ -0,0 +1 @@
+export { default as ProjectionManager, PROJECTIONS } from './ProjectionManager';

package/core/select/SelectHandler.d.ts

@@ -64,7 +64,7 @@ export default class SelectHandler {
     /**
      * 通过属性选择要素
      */
-    selectByProperty(propertyName: string, propertyValue: any, options?: ProgrammaticSelectOptions): this;
+    selectByProperty(propertyName: string, propertyValue: unknown, options?: ProgrammaticSelectOptions): this;
     /**
      * 应用选择（编程式）
      */

package/core/vue-template-point/VueTemplatePoint.d.ts

@@ -1,5 +1,5 @@
 import { Map as OLMap } from 'ol';
-import { VueTemplatePointInstance } from '../../types';
+import { ControlHandle, VueTemplatePointInstance } from '../../types';
 /**
  * Vue模板点位管理类
  * 用于在地图上添加和管理Vue组件覆盖物
@@ -23,10 +23,8 @@ export default class VueTemplatePoint {
     addVueTemplatePoint(pointDataList: any[], template: any, 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;
+    }): ControlHandle<VueTemplatePointInstance[]> & {
         setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void;
-        remove: () => void;
         getPoints: () => VueTemplatePointInstance[];
     };
     /**

package/core/vue-template-point/VueTemplatePoint.js

@@ -113,6 +113,7 @@ export default class VueTemplatePoint {
                 this.vuePoints.set(instance.id, instance);
             });
             return {
+                target: instances,
                 setVisible: (visible) => {
                     instances.forEach((instance) => {
                         instance.setVisible(visible);
@@ -378,9 +379,22 @@ class VueTemplatePointInstanceImpl {
             throw new Error('Cannot update props on destroyed DOM point');
         }
         try {
-            // 重新创建Vue应用实例
+            // 重新创建Vue应用实例。
+            // 注意：createVueApp 把 options.props 当 Vue 组件的 props 声明（非传值），
+            // 根组件没有父组件传值，因此必须把每个值包成 { default: value } 才能被
+            // Vue 当 prop 默认值消费，render 里才能读到。
             this.destroyVueApp();
-            this.options.props = { ...this.options.props, ...newProps };
+            const normalized = { ...this.options.props };
+            for (const key of Object.keys(newProps)) {
+                const value = newProps[key];
+                // 已经是 { type, default } 形式则原样合并，否则包装为默认值
+                const isAlreadyDeclaration = value !== null
+                    && typeof value === 'object'
+                    && (Object.prototype.hasOwnProperty.call(value, 'default')
+                        || Object.prototype.hasOwnProperty.call(value, 'type'));
+                normalized[key] = isAlreadyDeclaration ? value : { default: value };
+            }
+            this.options.props = normalized;
             this.createVueApp();
         }
         catch (error) {

package/docs/.vitepress/config.mts

@@ -10,6 +10,7 @@ export default defineConfig({
       { text: '首页', link: '/' },
       { text: '指南', link: '/MyOl' },
       { text: 'API', link: '/MyOl' },
+      { text: 'Demo', link: '/demo/' },
       { text: 'GitHub', link: 'https://github.com/cuteyuchen/my-openlayer' }
     ],
 

package/docs/Line.md

@@ -65,18 +65,18 @@ interface FlowLineLayerHandle {
 ### addLine
 
 ```typescript
-addLine(data: MapJSONData, options?: LineOptions): VectorLayer<VectorSource>
+addLine(data: MapJSONData, options: LineOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>>
 ```
 
-添加静态线图层。
+添加静态线图层，返回统一 `LayerHandle`。
 
 ### addLineByUrl
 
 ```typescript
-addLineByUrl(url: string, options?: LineOptions): VectorLayer<VectorSource>
+addLineByUrl(url: string, options: LineOptions & { layerName: string }): Promise<LayerHandle<VectorLayer<VectorSource>>>
 ```
 
-从 URL 加载并添加静态线图层。
+从 URL 加载 GeoJSON 后添加静态线图层，await 后返回完整 `LayerHandle`。
 
 ### removeLineLayer