my-openlayer 3.1.1 → 3.1.3

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))
             }));
         });
@@ -155,7 +154,10 @@ export default class PointPulseLayer {
             return styles;
         };
         const layer = new VectorLayer({
-            layerName: options.layerName,
+            properties: {
+                name: options.layerName,
+                layerName: options.layerName
+            },
             source,
             style: createStyles,
             zIndex: options.zIndex || ConfigManager.DEFAULT_POINT_OPTIONS.zIndex,

package/core/polygon/Polygon.js

@@ -193,19 +193,16 @@ export default class Polygon {
         if (!(layer instanceof VectorLayer)) {
             throw ErrorHandler.getInstance().createAndHandleError(`Layer '${layerName}' is not a vector layer`, ErrorType.LAYER_ERROR);
         }
-        const mergedOptions = {
-            textFont: '14px Calibri,sans-serif',
-            textFillColor: '#FFF',
-            textStrokeWidth: 2,
-            ...options
-        };
         const features = layer.getSource()?.getFeatures();
         if (!features) {
             ErrorHandler.getInstance().warn(`No features found in layer '${layerName}'`);
             return;
         }
+        const resolution = this.map.getView().getResolution() ?? 1;
         features.forEach((feature) => {
-            PolygonStyleFactory.updateSingleFeatureColor(feature, colorObj, mergedOptions);
+            const currentStyle = feature.getStyle() ?? layer.getStyle();
+            const previousStyles = PolygonStyleFactory.resolveFeatureStyles(currentStyle, feature, resolution);
+            PolygonStyleFactory.updateSingleFeatureColor(feature, colorObj, options, previousStyles);
         });
     }
     /**

package/core/polygon/PolygonStyleFactory.d.ts

@@ -6,8 +6,13 @@ import type { FeatureColorUpdateOptions, PolygonOptions } from "../../types";
  */
 export default class PolygonStyleFactory {
     static getFeatureText(feature: FeatureLike, options: PolygonOptions | FeatureColorUpdateOptions): string;
+    private static normalizeStyles;
+    static resolveFeatureStyles(styleLike: unknown, feature: FeatureLike, resolution?: number): Style[];
+    private static getPreviousStroke;
+    private static getPreviousFill;
+    private static getPreviousText;
     static createStyle(options: PolygonOptions): Style | Style[] | ((feature: FeatureLike) => Style | Style[]);
     static updateSingleFeatureColor(feature: Feature, colorObj?: {
         [propName: string]: string;
-    }, options?: FeatureColorUpdateOptions): void;
+    }, options?: FeatureColorUpdateOptions, previousStyles?: Style[]): void;
 }

package/core/polygon/PolygonStyleFactory.js

@@ -12,6 +12,28 @@ export default class PolygonStyleFactory {
         }
         return '';
     }
+    static normalizeStyles(styles) {
+        if (!styles)
+            return [];
+        return Array.isArray(styles) ? styles : [styles];
+    }
+    static resolveFeatureStyles(styleLike, feature, resolution = 1) {
+        if (!styleLike)
+            return [];
+        if (typeof styleLike === 'function') {
+            return PolygonStyleFactory.normalizeStyles(styleLike(feature, resolution));
+        }
+        return PolygonStyleFactory.normalizeStyles(styleLike);
+    }
+    static getPreviousStroke(styles) {
+        return styles.map(style => style.getStroke()).find((stroke) => !!stroke);
+    }
+    static getPreviousFill(styles) {
+        return styles.map(style => style.getFill()).find((fill) => !!fill);
+    }
+    static getPreviousText(styles) {
+        return styles.map(style => style.getText()).find((text) => !!text);
+    }
     static createStyle(options) {
         if (options.style) {
             return options.style;
@@ -56,6 +78,7 @@ export default class PolygonStyleFactory {
                         text: new Text({
                             text,
                             font: options.textFont,
+                            overflow: options.textOverflow,
                             fill: new Fill({ color: options.textFillColor }),
                             stroke: new Stroke({
                                 color: options.textStrokeColor,
@@ -68,30 +91,43 @@ export default class PolygonStyleFactory {
             return styles;
         };
     }
-    static updateSingleFeatureColor(feature, colorObj, options) {
-        const name = options?.textKey ? feature.get(options.textKey) : '';
-        const withDefaultStroke = options?.withDefaultStroke ?? true;
-        const withDefaultFill = options?.withDefaultFill ?? true;
-        const strokeColor = options?.strokeColor ?? (withDefaultStroke ? '#EBEEF5' : undefined);
-        const strokeWidth = options?.strokeWidth ?? 2;
-        const defaultFillColor = 'rgba(255, 255, 255, 0.3)';
-        const resolvedFillColor = options?.fillColor ?? (withDefaultFill ? defaultFillColor : undefined);
-        const newColor = colorObj?.[name] || resolvedFillColor;
+    static updateSingleFeatureColor(feature, colorObj, options, previousStyles = []) {
+        const name = options?.textKey ? String(feature.get(options.textKey) ?? '') : '';
+        const hasMappedColor = !!colorObj && Object.prototype.hasOwnProperty.call(colorObj, name);
+        const previousStroke = PolygonStyleFactory.getPreviousStroke(previousStyles);
+        const previousFill = PolygonStyleFactory.getPreviousFill(previousStyles);
+        const previousText = PolygonStyleFactory.getPreviousText(previousStyles);
+        const withDefaultStroke = options?.withDefaultStroke !== false;
+        const withDefaultFill = options?.withDefaultFill !== false;
+        const strokeColor = withDefaultStroke ? options?.strokeColor ?? previousStroke?.getColor() : undefined;
+        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);
         const featureStyle = new Style({
-            stroke: strokeColor ? new Stroke({ color: strokeColor, width: strokeWidth }) : undefined,
+            stroke: strokeColor !== undefined || strokeWidth !== undefined || lineDash !== undefined || lineDashOffset !== undefined
+                ? new Stroke({ color: strokeColor, width: strokeWidth, lineDash, lineDashOffset })
+                : undefined,
             fill: newColor ? new Fill({ color: newColor }) : undefined
         });
-        if (options?.textVisible) {
-            const text = PolygonStyleFactory.getFeatureText(feature, options);
+        const textVisible = options?.textVisible ?? !!previousText;
+        if (textVisible) {
+            const text = options ? PolygonStyleFactory.getFeatureText(feature, options) || previousText?.getText() : previousText?.getText();
             if (text) {
+                const textFillColor = options?.textFillColor ?? previousText?.getFill()?.getColor();
+                const textStrokeColor = options?.textStrokeColor ?? previousText?.getStroke()?.getColor();
+                const textStrokeWidth = options?.textStrokeWidth ?? previousText?.getStroke()?.getWidth();
                 featureStyle.setText(new Text({
                     text,
-                    font: options.textFont,
-                    fill: new Fill({ color: options.textFillColor }),
-                    stroke: new Stroke({
-                        color: options.textStrokeColor,
-                        width: options.textStrokeWidth
-                    })
+                    font: options?.textFont ?? previousText?.getFont(),
+                    overflow: options?.textOverflow ?? previousText?.getOverflow(),
+                    offsetY: options?.textOffsetY ?? previousText?.getOffsetY(),
+                    fill: textFillColor !== undefined ? new Fill({ color: textFillColor }) : undefined,
+                    stroke: textStrokeColor !== undefined || textStrokeWidth !== undefined
+                        ? new Stroke({ color: textStrokeColor, width: textStrokeWidth })
+                        : undefined
                 }));
             }
         }

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/docs/Polygon.md

@@ -37,6 +37,8 @@ const polygon = new Polygon(map: Map);
 | `textFont` | `string` | 字体样式 |
 | `textFillColor` | `string` | 文本颜色 |
 | `textStrokeColor` | `string` | 文本描边颜色 |
+| `textStrokeWidth` | `number` | 文本描边宽度 |
+| `textOverflow` | `boolean` | 是否允许文字溢出面范围。设为 `true` 时，文字不会因为当前缩放下放不进面内而被 OpenLayers 隐藏 |
 | **其他** | | |
 | `mask` | `boolean` | 是否作为蒙版（配合 `setOutLayer` 使用） |
 
@@ -112,6 +114,8 @@ updateFeatureColor(
 | `colorObj` | `Object` | 颜色映射对象 `{ '区域名': '颜色值' }` |
 | `options` | `FeatureColorUpdateOptions` | 包含 textKey 等配置以匹配要素 |
 
+未在 `options` 中指定的样式会沿用要素当前样式，例如 `strokeColor`、`strokeWidth`、`textFont`、`textFillColor`、`textStrokeColor`、`textStrokeWidth`、`textOverflow` 等。只传颜色映射时不会重置原有文字样式。
+
 ### addImageLayer
 
 添加静态图片图层（如叠加平面图、卫星图）。
@@ -183,6 +187,7 @@ polygonModule.addPolygon(polygonData, {
   textFillColor: '#fff',
   textStrokeColor: 'blue',
   textStrokeWidth: 2,
+  textOverflow: true, // 允许文字溢出面范围，避免随缩放尺寸不足被隐藏
   fitView: true
 });
 ```

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.1",
+  "version": "3.1.3",
   "type": "module",
   "license": "MIT",
   "main": "index.js",

package/types/base.d.ts

@@ -44,4 +44,9 @@ export interface TextOptions {
     textStrokeColor?: string;
     textStrokeWidth?: number;
     textOffsetY?: number;
+    /**
+     * 多边形或沿线文本是否允许溢出要素范围。
+     * 设置为 true 时，OpenLayers 不会因为当前缩放下文字放不进面/线而隐藏文本。
+     */
+    textOverflow?: boolean;
 }

package/types/common.d.ts

@@ -50,6 +50,7 @@ export type OptionsType = {
     textStrokeColor?: string;
     textStrokeWidth?: number;
     textOffsetY?: number;
+    textOverflow?: boolean;
     textKey?: string;
     img?: string;
     scale?: number;

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;