my-openlayer 3.1.2 → 3.1.4

package/MyOl.js

@@ -406,10 +406,10 @@ class MyOl {
             }
             if (this._line) {
                 try {
-                    this._line.destroyAllFlowLines();
+                    this._line.destroyAll();
                 }
                 catch (e) {
-                    this.errorHandler.warn('Line.destroyAllFlowLines 失败:', e);
+                    this.errorHandler.warn('Line.destroyAll 失败:', e);
                 }
             }
             if (this._point) {

package/README.md

@@ -16,10 +16,10 @@ my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地
 
 - **统一 LayerHandle** — 真实图层类 `add*` 返回 `{ layer, remove(), setVisible() }` 形态的句柄，跨 Point / Line / Polygon 复用同一套 lifecycle 模型
 - **统一 ControlHandle** — `addDomPoint` / `addVueTemplatePoint` 返回 `{ target, remove(), setVisible() }`，并保留 `anchors` / `getPoints()` 等原有能力
-- **点 API GeoJSON 直接输入** — `addPoint` / `addClusterPoint` / `addPulsePointLayer` 直接接受 `PointData[]`、GeoJSON FeatureCollection、Feature、MultiPoint geometry，内部统一标准化，`*ByUrl` 方法共享同一套解析逻辑
+- **点 API GeoJSON 直接输入** — `addPoint` / `addClusterPoint` / `addPulsePointLayer` 直接接受 `PointData[]`、GeoJSON FeatureCollection、Feature、MultiPoint geometry，内部统一标准化，创建后的 Feature 可直接通过 `feature.get('name')` / `feature.getProperties()` 读取业务字段
 - **addGeoJSON 综合渲染** — `MyOl.addGeoJSON(data, options)` 自动识别点/线/面几何类型，按分组创建图层，返回统一 `GeoJSONRenderHandle`，支持 `groupBy` 分组、`styleByProperties` 逐要素样式、数组/Record 多数据集输入
 - ***ByUrl 异步化** — `addPointByUrl` / `addLineByUrl` / `addPolygonByUrl` 统一先获取 JSON，再返回完整 Handle
-- **destroy 级联清理** — `MyOl.destroy()` 现在依次调用 `SelectHandler.destroy` / `Line.destroyAllFlowLines` / `Point.destroyAll` / `Polygon.destroyAll`，确保 rAF / Overlay / Vue 实例 / Select interaction 全部释放
+- **destroy 级联清理** — `MyOl.destroy()` 现在依次调用 `SelectHandler.destroy` / `Line.destroyAll` / `Point.destroyAll` / `Polygon.destroyAll`，确保静态线、流动线 rAF / Overlay / Vue 实例 / Select interaction 全部释放
 - **ProjectionManager** — 投影逻辑从 MyOl 内部抽取为独立类，支持 `ProjectionManager.register({ code, def })` 在 MyOl 实例之外注册任意 EPSG
 - **ConfigManager.setDefaults** — 运行时修改全局默认配置，所有未提供该字段的后续调用都生效
 - **统一错误类型** — 全部 `throw` 使用 `MyOpenLayersError` 并携带 `ErrorType`（`VALIDATION_ERROR` / `MAP_ERROR` / `LAYER_ERROR` / `COORDINATE_ERROR` / `DATA_ERROR` / `COMPONENT_ERROR`），另有 `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError` 子类，方便 `instanceof` 判别
@@ -133,6 +133,10 @@ const geoHandle = point.addPoint(
   ]},
   { layerName: 'geojson-points', textKey: 'name' }
 );
+
+const feature = geoHandle?.layer.getSource()?.getFeatures()[0];
+feature?.get('name'); // '杭州'
+// feature.get('rawData') 仅保留兼容旧代码，新代码优先读取顶层业务字段。
 ```
 
 ### 3. 添加高性能闪烁点

package/core/line/Line.d.ts

@@ -9,8 +9,15 @@ import type { FlowLineLayerHandle, FlowLineOptions, LineOptions, MapJSONData, La
 export default class Line {
     private readonly map;
     private readonly flowLineRegistry;
+    /** 由本实例创建的静态线图层。destroyAll 时统一移除，避免 MyOl.destroy 后残留。 */
+    private readonly managedLayers;
     private readonly styleFactory;
     constructor(map: Map);
+    /**
+     * 跟踪一个本实例创建的静态线图层，便于销毁阶段统一清理。
+     * @internal
+     */
+    private trackLayer;
     /**
      * 合并静态线默认配置。
      */
@@ -56,4 +63,9 @@ export default class Line {
      * 确保地图销毁后所有 requestAnimationFrame / postrender 监听被回收。
      */
     destroyAllFlowLines(): void;
+    /**
+     * 销毁本实例创建的所有线图层。静态线由 Line 自身托管，
+     * 流动线继续复用 destroyAllFlowLines，保证动画监听与 rAF 一并释放。
+     */
+    destroyAll(): void;
 }

package/core/line/Line.js

@@ -14,10 +14,20 @@ import LineStyleFactory from "./LineStyleFactory";
 export default class Line {
     constructor(map) {
         this.flowLineRegistry = new globalThis.Map();
+        /** 由本实例创建的静态线图层。destroyAll 时统一移除，避免 MyOl.destroy 后残留。 */
+        this.managedLayers = new Set();
         this.styleFactory = new LineStyleFactory();
         ValidationUtils.validateMapInstance(map);
         this.map = map;
     }
+    /**
+     * 跟踪一个本实例创建的静态线图层，便于销毁阶段统一清理。
+     * @internal
+     */
+    trackLayer(layer) {
+        this.managedLayers.add(layer);
+        return layer;
+    }
     /**
      * 合并静态线默认配置。
      */
@@ -59,15 +69,19 @@ export default class Line {
         });
         layer.setVisible(options.visible ?? true);
         this.map.addLayer(layer);
-        return layer;
+        return this.trackLayer(layer);
     }
     /** *********************统一句柄：静态线图层*********************/
     toLayerHandle(layer) {
         const map = this.map;
+        const managedLayers = this.managedLayers;
         return {
             layer,
             setVisible(visible) { layer.setVisible(visible); },
-            remove() { map.removeLayer(layer); }
+            remove() {
+                managedLayers.delete(layer);
+                map.removeLayer(layer);
+            }
         };
     }
     /**
@@ -106,6 +120,12 @@ export default class Line {
     removeLineLayer(layerName) {
         ValidationUtils.validateLayerName(layerName);
         MapTools.removeLayer(this.map, layerName);
+        // 同步清理托管记录，避免后续 destroyAll 重复持有已移除图层。
+        this.managedLayers.forEach(layer => {
+            if (layer.get('layerName') === layerName || layer.get('name') === layerName) {
+                this.managedLayers.delete(layer);
+            }
+        });
     }
     addFlowLine(data, options) {
         const mergedOptions = this.mergeFlowLineOptions(options);
@@ -169,4 +189,18 @@ export default class Line {
         });
         this.flowLineRegistry.clear();
     }
+    /**
+     * 销毁本实例创建的所有线图层。静态线由 Line 自身托管，
+     * 流动线继续复用 destroyAllFlowLines，保证动画监听与 rAF 一并释放。
+     */
+    destroyAll() {
+        this.destroyAllFlowLines();
+        this.managedLayers.forEach(layer => {
+            try {
+                this.map.removeLayer(layer);
+            }
+            catch { /* ignore */ }
+        });
+        this.managedLayers.clear();
+    }
 }

package/core/point/Point.d.ts

@@ -3,7 +3,7 @@ import { Style } from "ol/style";
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import Overlay from 'ol/Overlay';
-import { PointOptions, ClusterOptions, PointData, VueTemplatePointInstance, TwinkleItem, PulsePointOptions, PulsePointLayerHandle, LayerHandle, ControlHandle } from '../../types';
+import { PointOptions, PointLayerOptions, ClusterOptions, ClusterPointLayerOptions, PointData, VueTemplatePointInstance, TwinkleItem, PulsePointLayerOptions, PulsePointLayerHandle, LayerHandle, ControlHandle } from '../../types';
 import { type PointJSONInput } from '../../utils/GeoJSONProcessor';
 export default class Point {
     private map;
@@ -74,13 +74,9 @@ export default class Point {
     /** *********************创建聚合点图层*********************/
     private createClusterPointLayer;
     /** *********************添加普通点*********************/
-    addPoint(pointData: PointJSONInput, options: PointOptions & {
-        layerName: string;
-    }): LayerHandle<VectorLayer<VectorSource>> | null;
+    addPoint(pointData: PointJSONInput, options: PointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null;
     /** *********************添加聚合点*********************/
-    addClusterPoint(pointData: PointJSONInput, options: ClusterOptions & {
-        layerName: string;
-    }): LayerHandle<VectorLayer<VectorSource>> | null;
+    addClusterPoint(pointData: PointJSONInput, options: ClusterPointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null;
     /** @internal 把 VectorLayer 包成 LayerHandle 的内部工具。 */
     private toLayerHandle;
     /**
@@ -89,24 +85,18 @@ export default class Point {
      * 与 addDomPoint 不同，该方法使用 VectorLayer 批量渲染点位，并通过单个
      * requestAnimationFrame 驱动闪烁圈，适合村庄预警等大量点位场景。
      */
-    addPulsePointLayer(pointData: PointJSONInput, options: PulsePointOptions & {
-        layerName: string;
-    }): PulsePointLayerHandle | null;
+    addPulsePointLayer(pointData: PointJSONInput, options: PulsePointLayerOptions): 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>;
+    addPointByUrl(url: string, options: PointLayerOptions): Promise<LayerHandle<VectorLayer<VectorSource>> | null>;
     /**
      * P1-2：从 URL 加载点位数据并添加为高性能闪烁点图层。
      */
-    addPulsePointLayerByUrl(url: string, options: PulsePointOptions & {
-        layerName: string;
-    }): Promise<PulsePointLayerHandle | null>;
+    addPulsePointLayerByUrl(url: string, options: PulsePointLayerOptions): Promise<PulsePointLayerHandle | null>;
     /**
      * 添加闪烁点
      * @param twinkleList 闪烁点数据

package/core/point/Point.js

@@ -12,6 +12,7 @@ import { ConfigManager, MapTools } from "../map";
 import PointClusterLayer from './PointClusterLayer';
 import PointOverlay from './PointOverlay';
 import PointPulseLayer from './PointPulseLayer';
+import { createPointFeatureProperties } from './PointFeatureProperties';
 export default class Point {
     constructor(map) {
         /** 由本实例创建的纯图层（addPoint / addClusterPoint）。destroyAll 时统一移除。 */
@@ -167,9 +168,7 @@ export default class Point {
                 return;
             }
             const pointFeature = new Feature({
-                rawData: item,
-                type: options.layerName,
-                layerName: options.layerName,
+                ...createPointFeatureProperties(item, options.layerName),
                 geometry: new olPoint(ProjectionUtils.transformCoordinate([item.lgtd, item.lttd], options))
             });
             if (options.style) {

package/core/point/PointClusterLayer.d.ts

@@ -1,10 +1,10 @@
 import Map from "ol/Map";
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
-import type { ClusterOptions, PointData } from "../../types";
+import type { ClusterOptions, ClusterPointLayerOptions, PointData } from "../../types";
 /**
  * 点聚合图层构建器。
  */
 export default class PointClusterLayer {
-    static create(map: Map, pointData: PointData[], options: ClusterOptions, createClusterStyle: (options: ClusterOptions, name: string) => any): VectorLayer<VectorSource>;
+    static create(map: Map, pointData: PointData[], options: ClusterPointLayerOptions, createClusterStyle: (options: ClusterOptions, name: string) => any): VectorLayer<VectorSource>;
 }

package/core/point/PointClusterLayer.js

@@ -6,6 +6,7 @@ import { Cluster } from "ol/source";
 import ProjectionUtils from "../../utils/ProjectionUtils";
 import ValidationUtils from "../../utils/ValidationUtils";
 import { ConfigManager } from "../map";
+import { createPointFeatureProperties } from "./PointFeatureProperties";
 /**
  * 点聚合图层构建器。
  */
@@ -17,11 +18,8 @@ export default class PointClusterLayer {
                 return;
             }
             pointFeatureList.push(new Feature({
-                type: options.layerName,
-                layerName: options.layerName,
+                ...createPointFeatureProperties(item, options.layerName),
                 geometry: new OlPoint(ProjectionUtils.transformCoordinate([item.lgtd, item.lttd], options)),
-                name: options.textKey ? item[options.textKey] : '',
-                rawData: item,
             }));
         });
         const source = new VectorSource({ features: pointFeatureList });
@@ -31,7 +29,10 @@ export default class PointClusterLayer {
             source,
         });
         const clusterLayer = new VectorLayer({
-            layerName: options.layerName,
+            properties: {
+                name: options.layerName,
+                layerName: options.layerName
+            },
             source: clusterSource,
             style: (feature) => {
                 if (options.style) {
@@ -40,7 +41,9 @@ export default class PointClusterLayer {
                     }
                     return options.style;
                 }
-                const name = feature.get('features')[0].get('name');
+                const rawFeature = feature.get('features')[0];
+                const rawData = rawFeature.get('rawData');
+                const name = options.textKey ? String(rawData?.[options.textKey] ?? '') : '';
                 return createClusterStyle(options, name);
             },
             zIndex: options.zIndex || ConfigManager.DEFAULT_CLUSTER_OPTIONS.zIndex,

package/core/point/PointFeatureProperties.d.ts

@@ -0,0 +1,9 @@
+import type { PointData } from "../../types";
+/** *********************点 Feature 属性构建*********************/
+/**
+ * 构建写入 OpenLayers Feature 顶层的点属性。
+ *
+ * lgtd / lttd 只用于几何坐标，不作为业务属性平铺；rawData 保留给旧代码兼容，
+ * 新代码应优先通过 feature.get('字段名') 或 feature.getProperties() 读取业务字段。
+ */
+export declare function createPointFeatureProperties(item: PointData, layerName?: string): Record<string, unknown>;

package/core/point/PointFeatureProperties.js

@@ -0,0 +1,21 @@
+/** *********************点 Feature 属性构建*********************/
+/**
+ * 构建写入 OpenLayers Feature 顶层的点属性。
+ *
+ * lgtd / lttd 只用于几何坐标，不作为业务属性平铺；rawData 保留给旧代码兼容，
+ * 新代码应优先通过 feature.get('字段名') 或 feature.getProperties() 读取业务字段。
+ */
+export function createPointFeatureProperties(item, layerName) {
+    const businessProperties = {};
+    Object.keys(item).forEach(key => {
+        if (key !== 'lgtd' && key !== 'lttd') {
+            businessProperties[key] = item[key];
+        }
+    });
+    return {
+        ...businessProperties,
+        rawData: item,
+        type: layerName,
+        layerName,
+    };
+}

package/core/point/PointPulseLayer.d.ts

@@ -1,13 +1,13 @@
 import Feature from "ol/Feature";
 import Map from "ol/Map";
 import { Text } from "ol/style";
-import type { PointData, PulsePointLayerHandle, PulsePointOptions } from "../../types";
+import type { PointData, PulsePointLayerHandle, PulsePointLayerOptions, PulsePointOptions } from "../../types";
 /**
  * 高性能闪烁点图层构建器。
  */
 export default class PointPulseLayer {
     static createTextStyle(options: PulsePointOptions, text: string): Text;
     static withOpacity(color: string, opacity: number): string;
-    static createFeatures(pointData: PointData[], options: PulsePointOptions): Feature[];
-    static create(map: Map, pointData: PointData[], options: PulsePointOptions): PulsePointLayerHandle;
+    static createFeatures(pointData: PointData[], options: PulsePointLayerOptions): Feature[];
+    static create(map: Map, pointData: PointData[], options: PulsePointLayerOptions): PulsePointLayerHandle;
 }

package/core/point/PointPulseLayer.js

@@ -6,6 +6,7 @@ import { Circle as CircleStyle, Fill, Icon, Stroke, Style, Text } from "ol/style
 import ProjectionUtils from "../../utils/ProjectionUtils";
 import ValidationUtils from "../../utils/ValidationUtils";
 import { ConfigManager } from "../map";
+import { createPointFeatureProperties } from "./PointFeatureProperties";
 /**
  * 高性能闪烁点图层构建器。
  */
@@ -49,9 +50,7 @@ export default class PointPulseLayer {
                 return;
             }
             pointFeatureList.push(new Feature({
-                rawData: item,
-                type: options.layerName,
-                layerName: options.layerName,
+                ...createPointFeatureProperties(item, options.layerName),
                 geometry: new OlPoint(ProjectionUtils.transformCoordinate([item.lgtd, item.lttd], options))
             }));
         });
@@ -82,7 +81,15 @@ export default class PointPulseLayer {
         const source = new VectorSource({
             features: PointPulseLayer.createFeatures(pointData, options)
         });
-        const createStyles = (feature) => {
+        const baseZIndex = options.zIndex || ConfigManager.DEFAULT_POINT_OPTIONS.zIndex;
+        const iconImg = options.icon?.img ?? options.icon?.src;
+        /**
+         * 仅负责绘制脉冲动画，避免动画覆盖图标。
+         */
+        const createPulseStyle = (feature) => {
+            if (!pulseOptions.enabled) {
+                return undefined;
+            }
             const rawData = feature.get('rawData');
             const level = String(rawData?.[levelKey] ?? 'default');
             const progress = frameIndex / Math.max(1, pulseOptions.frameCount - 1);
@@ -91,28 +98,28 @@ export default class PointPulseLayer {
             const opacity = 1 - progress;
             const fillColor = pulseOptions.colorMap[level] ?? pulseOptions.colorMap.default ?? 'rgba(6, 183, 253, 0.32)';
             const strokeColor = pulseOptions.strokeColorMap?.[level] ?? pulseOptions.strokeColorMap?.default;
-            const styles = [];
-            if (pulseOptions.enabled) {
-                const pulseCacheKey = `${level}_${frameIndex}`;
-                let pulseStyle = pulseStyleCache.get(pulseCacheKey);
-                if (!pulseStyle) {
-                    pulseStyle = new Style({
-                        zIndex: 0,
-                        image: new CircleStyle({
-                            radius,
-                            fill: new Fill({ color: PointPulseLayer.withOpacity(fillColor, opacity) }),
-                            stroke: strokeColor && pulseOptions.strokeWidth > 0
-                                ? new Stroke({ color: PointPulseLayer.withOpacity(strokeColor, opacity), width: pulseOptions.strokeWidth })
-                                : undefined
-                        })
-                    });
-                    pulseStyleCache.set(pulseCacheKey, pulseStyle);
-                }
-                styles.push(pulseStyle);
+            const pulseCacheKey = `${level}_${frameIndex}`;
+            let pulseStyle = pulseStyleCache.get(pulseCacheKey);
+            if (!pulseStyle) {
+                pulseStyle = new Style({
+                    image: new CircleStyle({
+                        radius,
+                        fill: new Fill({ color: PointPulseLayer.withOpacity(fillColor, opacity) }),
+                        stroke: strokeColor && pulseOptions.strokeWidth > 0
+                            ? new Stroke({ color: PointPulseLayer.withOpacity(strokeColor, opacity), width: pulseOptions.strokeWidth })
+                            : undefined
+                    })
+                });
+                pulseStyleCache.set(pulseCacheKey, pulseStyle);
             }
+            return pulseStyle;
+        };
+        /**
+         * 仅负责绘制图标与文本，固定放在脉冲层之上。
+         */
+        const createStaticStyle = (feature) => {
+            const rawData = feature.get('rawData');
             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 ?? iconImg ?? '',
                 options.scale ?? options.icon?.scale ?? ConfigManager.DEFAULT_POINT_ICON_SCALE,
@@ -121,8 +128,7 @@ export default class PointPulseLayer {
             ].join('|');
             let pointStyle = staticStyleCache.get(staticCacheKey);
             if (pointStyle) {
-                styles.push(pointStyle);
-                return styles;
+                return pointStyle;
             }
             const pointStyleOptions = {};
             const iconSrc = options.img ?? iconImg;
@@ -148,20 +154,34 @@ export default class PointPulseLayer {
             }
             if (pointStyleOptions.image || pointStyleOptions.text) {
                 pointStyle = new Style(pointStyleOptions);
-                pointStyle.setZIndex(1);
                 staticStyleCache.set(staticCacheKey, pointStyle);
-                styles.push(pointStyle);
+                return pointStyle;
             }
-            return styles;
+            return undefined;
         };
-        const layer = new VectorLayer({
-            layerName: options.layerName,
+        const pulseLayer = new VectorLayer({
+            properties: {
+                name: options.layerName,
+                layerName: options.layerName
+            },
             source,
-            style: createStyles,
-            zIndex: options.zIndex || ConfigManager.DEFAULT_POINT_OPTIONS.zIndex,
+            style: createPulseStyle,
+            zIndex: baseZIndex,
         });
-        layer.setVisible(options.visible === undefined ? true : options.visible);
-        map.addLayer(layer);
+        const visible = options.visible === undefined ? true : options.visible;
+        pulseLayer.setVisible(visible);
+        map.addLayer(pulseLayer);
+        const staticLayer = new VectorLayer({
+            properties: {
+                name: options.layerName,
+                layerName: options.layerName
+            },
+            source,
+            style: createStaticStyle,
+            zIndex: baseZIndex + 1,
+        });
+        staticLayer.setVisible(visible);
+        map.addLayer(staticLayer);
         const tick = () => {
             if (!running)
                 return;
@@ -171,7 +191,7 @@ export default class PointPulseLayer {
             if (nextFrameIndex !== renderedFrameIndex) {
                 frameIndex = nextFrameIndex;
                 renderedFrameIndex = nextFrameIndex;
-                layer.changed();
+                pulseLayer.changed();
             }
             rafId = requestAnimationFrame(tick);
         };
@@ -190,11 +210,14 @@ export default class PointPulseLayer {
         };
         start();
         return {
-            layer,
+            layer: pulseLayer,
             source,
             start,
             stop,
-            setVisible: (visible) => layer.setVisible(visible),
+            setVisible: (visible) => {
+                pulseLayer.setVisible(visible);
+                staticLayer.setVisible(visible);
+            },
             updateData: (nextData) => {
                 source.clear();
                 source.addFeatures(PointPulseLayer.createFeatures(nextData, options));
@@ -202,7 +225,8 @@ export default class PointPulseLayer {
             remove: () => {
                 stop();
                 source.clear();
-                map.removeLayer(layer);
+                map.removeLayer(pulseLayer);
+                map.removeLayer(staticLayer);
             }
         };
     }

package/core/polygon/PolygonStyleFactory.js

@@ -103,9 +103,20 @@ export default class PolygonStyleFactory {
         const strokeWidth = withDefaultStroke ? options?.strokeWidth ?? previousStroke?.getWidth() : undefined;
         const lineDash = withDefaultStroke ? options?.lineDash ?? previousStroke?.getLineDash() ?? undefined : undefined;
         const lineDashOffset = withDefaultStroke ? options?.lineDashOffset ?? previousStroke?.getLineDashOffset() : undefined;
-        const newColor = hasMappedColor
-            ? colorObj[name]
-            : options?.fillColor ?? (withDefaultFill ? previousFill?.getColor() : undefined);
+        /** *********************颜色回退策略*********************/
+        // 1) colorObj 命中映射：使用映射颜色
+        // 2) 未命中但 options.fillColor 传入：使用传入的 fillColor
+        // 3) 都未提供：使用透明填充，避免沿用上一次更新的颜色
+        let newColor;
+        if (hasMappedColor) {
+            newColor = colorObj[name];
+        }
+        else if (options?.fillColor !== undefined) {
+            newColor = options.fillColor;
+        }
+        else {
+            newColor = withDefaultFill ? 'rgba(0, 0, 0, 0)' : undefined;
+        }
         const featureStyle = new Style({
             stroke: strokeColor !== undefined || strokeWidth !== undefined || lineDash !== undefined || lineDashOffset !== undefined
                 ? new Stroke({ color: strokeColor, width: strokeWidth, lineDash, lineDashOffset })

package/docs/.vitepress/config.mts

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

package/docs/Line.md

@@ -69,6 +69,7 @@ addLine(data: MapJSONData, options: LineOptions & { layerName: string }): LayerH
 ```
 
 添加静态线图层，返回统一 `LayerHandle`。
+`handle.remove()` 会同步退出 `Line` 内部托管集合，后续再调用 `destroyAll()` 不会重复持有已移除图层。
 
 ### addLineByUrl
 
@@ -85,6 +86,7 @@ removeLineLayer(layerName: string): void
 ```
 
 移除静态线图层。
+该方法会同步清理 `Line` 内部托管记录，避免后续 `destroyAll()` 重复处理同名图层。
 
 ## 流动线 / 动态图标线
 
@@ -113,6 +115,22 @@ removeFlowLineLayer(layerName: string): void
 
 按图层名移除流动线的基础图层与动画图层。
 
+### destroyAll
+
+```typescript
+destroyAll(): void
+```
+
+销毁当前 `Line` 实例创建的所有线图层。包括 `addLine` / `addLineByUrl` 创建的静态线，以及 `addFlowLine` / `addFlowLineByUrl` 创建的流动线基础图层、动画图层和 rAF 动画。`MyOl.destroy()` 会自动调用该方法。
+
+### destroyAllFlowLines
+
+```typescript
+destroyAllFlowLines(): void
+```
+
+仅销毁当前 `Line` 实例创建的流动线动画和对应图层。该方法保留用于兼容旧代码；新代码需要完整清理 Line 模块时优先使用 `destroyAll()`。
+
 ## 使用示例
 
 ### 基础静态线

package/docs/MIGRATION-3.0.md

@@ -27,6 +27,7 @@ line.addLine(data, { layerName: 'my-line', strokeColor: 'red' })
 > **为什么**：依赖默认 `layerName` 的两次调用会互相覆盖，是 2.x 最常见的"图层莫名消失"陷阱。
 
 `PointOptions / LineOptions / PolygonOptions` interface **本身**没改（`layerName?: string` 仍然可选），所以已有的工厂函数、配置对象不受影响 —— 只是公开方法签名收紧了。
+点图层入口同时导出 `PointLayerOptions`、`ClusterPointLayerOptions`、`PulsePointLayerOptions`，新代码如果要单独声明配置变量，优先使用这些命名类型，避免手写 `PointOptions & { layerName: string }`。
 
 ### 1.2 `add*` 返回值改为 Handle
 

package/docs/MyOl.md

@@ -207,7 +207,7 @@ getMapOptions(): Readonly<MapInitType>
 
 #### destroy
 
-销毁地图实例，清理所有事件监听和资源。
+销毁地图实例，并级联清理子模块资源：`SelectHandler.destroy()`、`Line.destroyAll()`、`Point.destroyAll()`、`Polygon.destroyAll()`、`EventManager.clear()`。其中 `Line.destroyAll()` 会同时移除静态线和流动线图层。
 
 ```typescript
 destroy(): void

package/docs/Point.md

@@ -24,7 +24,7 @@ constructor(map: Map)
 | iconColor | `string` | 图标颜色（用于改变图标色调） |
 | circleColor | `string` | 圆点填充颜色。未设置 img 时生效，与 circleRadius 搭配绘制纯色圆点 |
 | circleRadius | `number` | 圆点半径（像素），默认 6。仅在未设置 img 时生效 |
-| layerName | `string` | 图层名称（必填，继承自 BaseOptions） |
+| layerName | `string` | 图层名称（基础配置中可选；公开 add 图层入口使用 `*LayerOptions` 要求必填） |
 | zIndex | `number` | 图层层级 |
 | visible | `boolean` | 是否可见 |
 | style | `Style \| Style[] \| ((feature: FeatureLike) => Style \| Style[])` | 自定义样式函数 |
@@ -38,6 +38,24 @@ constructor(map: Map)
 | distance | `number` | 聚合距离（像素），默认为 20 |
 | minDistance | `number` | 最小聚合距离 |
 
+### PointLayerOptions / ClusterPointLayerOptions / PulsePointLayerOptions
+
+公开点图层入口使用的配置类型，分别继承自 `PointOptions`、`ClusterOptions`、`PulsePointOptions`，并把 `layerName` 收紧为必填。
+
+```typescript
+interface PointLayerOptions extends PointOptions {
+  layerName: string
+}
+
+interface ClusterPointLayerOptions extends ClusterOptions {
+  layerName: string
+}
+
+interface PulsePointLayerOptions extends PulsePointOptions {
+  layerName: string
+}
+```
+
 ### PulsePointOptions
 
 继承自 `PointOptions`，因此与 `addPoint` 一致支持 `img`、`scale`、`iconColor`、`textKey`、`textVisible` 等参数。
@@ -91,6 +109,7 @@ type PointJSONInput =
 - `FeatureCollection` 中只提取 `Point` / `MultiPoint` 类型的 Feature，其他 geometry 类型被跳过。
 - `MultiPoint` 会被拆分为多个独立的 `PointData`。
 - GeoJSON Feature 的 `properties` 会被保留，与 `lgtd` / `lttd` 合并。
+- 创建 OpenLayers Feature 时，业务字段会平铺到 Feature 顶层，可通过 `feature.get('name')` 或 `feature.getProperties().name` 读取；`rawData` 仅保留兼容旧代码，不推荐新代码继续依赖。
 - 坐标含 `NaN`、`Infinity` 或缺失的点会被过滤。
 - 不支持 `lng/lat`、`longitude/latitude`、`x/y` 等字段别名。
 
@@ -118,7 +137,7 @@ type PointJSONInput =
 添加普通点图层。支持 `PointJSONInput` 任意形态（`PointData[]`、GeoJSON FeatureCollection、Feature、裸 geometry）。
 
 ```typescript
-addPoint(pointData: PointJSONInput, options: PointOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
+addPoint(pointData: PointJSONInput, options: PointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
 - **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
@@ -130,7 +149,7 @@ addPoint(pointData: PointJSONInput, options: PointOptions & { layerName: string
 添加聚合点图层。支持 `PointJSONInput` 任意形态。
 
 ```typescript
-addClusterPoint(pointData: PointJSONInput, options: ClusterOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
+addClusterPoint(pointData: PointJSONInput, options: ClusterPointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
 - **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
@@ -142,7 +161,7 @@ addClusterPoint(pointData: PointJSONInput, options: ClusterOptions & { layerName
 从 URL 加载点位数据，支持 `PointData[]` 数组或 GeoJSON FeatureCollection。
 
 ```typescript
-addPointByUrl(url: string, options: PointOptions & { layerName: string }): Promise<LayerHandle<VectorLayer<VectorSource>> | null>
+addPointByUrl(url: string, options: PointLayerOptions): Promise<LayerHandle<VectorLayer<VectorSource>> | null>
 ```
 
 ### addDomPoint
@@ -167,7 +186,7 @@ addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
 添加高性能闪烁点图层。支持 `PointJSONInput` 任意形态。
 
 ```typescript
-addPulsePointLayer(pointData: PointJSONInput, options: PulsePointOptions & { layerName: string }): PulsePointLayerHandle | null
+addPulsePointLayer(pointData: PointJSONInput, options: PulsePointLayerOptions): PulsePointLayerHandle | null
 ```
 
 - **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
@@ -179,7 +198,7 @@ addPulsePointLayer(pointData: PointJSONInput, options: PulsePointOptions & { lay
 从 URL 加载点位数据并添加高性能闪烁点图层。
 
 ```typescript
-addPulsePointLayerByUrl(url: string, options: PulsePointOptions & { layerName: string }): Promise<PulsePointLayerHandle | null>
+addPulsePointLayerByUrl(url: string, options: PulsePointLayerOptions): Promise<PulsePointLayerHandle | null>
 ```
 
 ### addVueTemplatePoint
@@ -288,6 +307,9 @@ const fc = {
   ]
 };
 const handle = point.addPoint(fc, { layerName: 'cities', textKey: 'name' });
+const firstFeature = handle?.layer.getSource()?.getFeatures()[0];
+firstFeature?.get('name'); // '北京'
+// firstFeature.get('rawData') 仅保留兼容旧代码，新代码优先读取顶层业务字段。
 
 // 方式二：单个 Feature
 const feature = { type: 'Feature', properties: { name: '杭州' }, geometry: { type: 'Point', coordinates: [120.15, 30.27] } };

package/index.d.ts

@@ -14,7 +14,7 @@ export { default as ValidationUtils } from './utils/ValidationUtils';
 export { normalizePointData } from './utils/GeoJSONProcessor';
 export type { PointJSONInput } from './types';
 export type { BaseOptions, StyleOptions, TextOptions, LayerHandle, AnimatedLayerHandle } from './types';
-export type { PointOptions, LineOptions, FlowLineOptions, FlowLineLayerHandle, PolygonOptions, PulsePointOptions, PulsePointLayerHandle } from './types';
+export type { PointOptions, PointLayerOptions, LineOptions, FlowLineOptions, FlowLineLayerHandle, PolygonOptions, PulsePointOptions, PulsePointLayerOptions, PulsePointLayerHandle } from './types';
 export type { OptionsType } from './types';
-export type { MapInitType, MapLayersOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions, PointData, PulsePointIconOptions, LineData, ClusterOptions, MeasureHandlerType, VueTemplatePointOptions, VueTemplatePointInstance, TwinkleItem, MapJSONData, FeatureData, AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy, GeoJSONLayerName, AddGeoJSONPointOptions, AddGeoJSONOptions, GeoJSONGroupHandle, GeoJSONRenderHandle, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './types';
+export type { MapInitType, MapLayersOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions, PointData, PulsePointIconOptions, LineData, ClusterOptions, ClusterPointLayerOptions, MeasureHandlerType, VueTemplatePointOptions, VueTemplatePointInstance, TwinkleItem, MapJSONData, FeatureData, AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy, GeoJSONLayerName, AddGeoJSONPointOptions, AddGeoJSONOptions, GeoJSONGroupHandle, GeoJSONRenderHandle, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './types';
 export { VueTemplatePointState } from './types';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "3.1.2",
+  "version": "3.1.4",
   "type": "module",
   "license": "MIT",
   "main": "index.js",

package/types/index.d.ts

@@ -2,7 +2,7 @@ export type { BaseOptions, StyleOptions, TextOptions } from './base';
 export type { LayerHandle, AnimatedLayerHandle, ControlHandle } from './handle';
 export type { FeatureData, MapJSONData, OptionsType, MeasureHandlerType, EventType } from './common';
 export type { MapInitType, MapLayersOptions, MapLayers, AnnotationType, TiandituType, AnnotationLayerOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions } from './map';
-export type { PointOptions, PointData, PointJSONInput, ClusterOptions, PulsePointIconOptions, PulsePointOptions, PulsePointLayerHandle, TwinkleItem } from './point';
+export type { PointOptions, PointLayerOptions, PointData, PointJSONInput, ClusterOptions, ClusterPointLayerOptions, PulsePointIconOptions, PulsePointOptions, PulsePointLayerOptions, PulsePointLayerHandle, TwinkleItem } from './point';
 export type { LineOptions, LineData, FlowLineOptions, FlowLineLayerHandle } from './line';
 export type { PolygonOptions, FeatureColorUpdateOptions } from './polygon';
 export type { AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy, GeoJSONLayerName, AddGeoJSONPointOptions, AddGeoJSONOptions, GeoJSONGroupHandle, GeoJSONRenderHandle } from './geojson';

package/types/point.d.ts

@@ -13,6 +13,10 @@ export interface PointOptions extends BaseOptions, StyleOptions, TextOptions {
     /** 圆点半径（像素），默认 6。仅在未设置 img 时生效。 */
     circleRadius?: number;
 }
+/** addPoint / addPointByUrl 的公开入口配置，要求 layerName 必填。 */
+export interface PointLayerOptions extends PointOptions {
+    layerName: string;
+}
 export interface PointData {
     lgtd: number;
     lttd: number;
@@ -30,6 +34,10 @@ export interface ClusterOptions extends PointOptions {
     distance?: number;
     minDistance?: number;
 }
+/** addClusterPoint 的公开入口配置，要求 layerName 必填。 */
+export interface ClusterPointLayerOptions extends ClusterOptions {
+    layerName: string;
+}
 export interface PulsePointIconOptions {
     /**
      * 图标资源 URL。
@@ -59,6 +67,10 @@ export interface PulsePointOptions extends PointOptions {
         frameCount?: number;
     };
 }
+/** addPulsePointLayer / addPulsePointLayerByUrl 的公开入口配置，要求 layerName 必填。 */
+export interface PulsePointLayerOptions extends PulsePointOptions {
+    layerName: string;
+}
 export interface PulsePointLayerHandle extends AnimatedLayerHandle<VectorLayer<VectorSource>> {
     layer: VectorLayer<VectorSource>;
     source: VectorSource;