my-openlayer 2.5.4 → 3.0.1

package/core/map/ConfigManager.js

@@ -1,8 +1,163 @@
+const BUILTIN_DEFAULTS = {
+    POINT_OPTIONS: { visible: true, zIndex: 21 },
+    POINT_TEXT_OPTIONS: {
+        textFont: '12px Calibri,sans-serif',
+        textFillColor: '#FFF',
+        textStrokeColor: '#000',
+        textStrokeWidth: 3,
+        textOffsetY: 20
+    },
+    POINT_ICON_SCALE: 1,
+    CLUSTER_OPTIONS: { distance: 40, minDistance: 0, zIndex: 21 },
+    DOM_POINT_OVERLAY_OPTIONS: { positioning: 'center-center', stopEvent: false },
+    LINE_OPTIONS: {
+        type: 'line',
+        strokeColor: 'rgba(3, 122, 255, 1)',
+        strokeWidth: 2,
+        visible: true,
+        layerName: 'lineLayer',
+        zIndex: 15
+    },
+    FLOW_LINE_OPTIONS: {
+        type: 'line',
+        strokeColor: 'rgba(3, 122, 255, 1)',
+        strokeWidth: 2,
+        visible: true,
+        layerName: 'lineLayer',
+        duration: 4000,
+        loop: true,
+        autoStart: true,
+        showBaseLine: true,
+        animationMode: 'icon',
+        flowSymbol: {
+            scale: 0.8,
+            rotateWithView: true,
+            count: 1,
+            spacing: 0.15
+        },
+        trailEnabled: false,
+        trailLength: 0,
+        zIndex: 16
+    },
+    POLYGON_OPTIONS: {
+        zIndex: 11,
+        visible: true,
+        textFont: '14px Calibri,sans-serif',
+        textFillColor: '#FFF',
+        textStrokeColor: '#409EFF',
+        textStrokeWidth: 2
+    },
+    POLYGON_COLOR_MAP: {
+        '0': 'rgba(255, 0, 0, 0.6)',
+        '1': 'rgba(245, 154, 35, 0.6)',
+        '2': 'rgba(255, 238, 0, 0.6)',
+        '3': 'rgba(1, 111, 255, 0.6)'
+    },
+    IMAGE_OPTIONS: { opacity: 1, visible: true, layerName: 'imageLayer', zIndex: 11 },
+    MASK_OPTIONS: { fillColor: 'rgba(0, 0, 0, 0.5)', opacity: 1, visible: true, layerName: 'maskLayer', zIndex: 12 },
+    TEXT_OPTIONS: { textFont: '14px Calibri,sans-serif', textFillColor: '#FFF', textStrokeColor: '#409EFF', textStrokeWidth: 2 },
+    HEATMAP_OPTIONS: { blur: 15, radius: 10, zIndex: 11, opacity: 1 },
+    HEATMAP_VALUE_KEY: 'value',
+    TIANDITU_CONFIG: {
+        BASE_URL: '//t{0-7}.tianditu.gov.cn/DataServer',
+        PROJECTION: 'EPSG:4326',
+        DEFAULT_ZINDEX: 9,
+        ANNOTATION_ZINDEX_OFFSET: 10
+    },
+    MAP_LAYERS_OPTIONS: { zIndex: 9, annotation: false, mapClip: false, mapClipData: undefined },
+    MYOL_OPTIONS: { layers: undefined, zoom: 10, center: [119.81, 29.969], extent: undefined },
+    VUE_TEMPLATE_POINT_OPTIONS: { positioning: 'center-center', stopEvent: false, visible: true, zIndex: 1 },
+    RIVER_LEVEL_WIDTH_MAP: { 1: 2, 2: 1, 3: 0.5, 4: 0.5, 5: 0.5 },
+    RIVER_LAYERS_BY_ZOOM_OPTIONS: {
+        type: 'river', levelCount: 5, zoomOffset: 8, strokeColor: 'rgb(0,113,255)', strokeWidth: 3,
+        visible: true, zIndex: 15, layerName: 'riverLayer', removeExisting: false
+    },
+    RIVER_WIDTH_BY_LEVEL_OPTIONS: {
+        type: 'river', layerName: 'river', strokeColor: 'rgba(3, 122, 255, 1)', strokeWidth: 2,
+        visible: true, zIndex: 15, removeExisting: false
+    }
+};
+/**
+ * 当前生效的 defaults。运行时通过 setDefaults 修改这里的值，getter 再合并。
+ * 深拷贝一份避免外部意外修改 BUILTIN_DEFAULTS。
+ */
+const currentDefaults = deepClone(BUILTIN_DEFAULTS);
+function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (obj instanceof Date)
+        return new Date(obj.getTime());
+    if (Array.isArray(obj))
+        return obj.map(item => deepClone(item));
+    const cloned = {};
+    for (const k in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, k))
+            cloned[k] = deepClone(obj[k]);
+    }
+    return cloned;
+}
+function deepMerge(base, partial) {
+    const result = Array.isArray(base) ? [...base] : { ...base };
+    for (const k of Object.keys(partial)) {
+        const v = partial[k];
+        if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)) {
+            result[k] = deepMerge(result[k] ?? {}, v);
+        }
+        else {
+            result[k] = v;
+        }
+    }
+    return result;
+}
 /**
  * 配置管理类
  * 用于统一管理默认配置和验证
+ *
+ * 运行时修改默认值：调用 ConfigManager.setDefaults('LINE_OPTIONS', { strokeWidth: 4 })
+ * 之后所有新创建的 Line/FlowLine 都将以此为默认。
  */
-class ConfigManager {
+export default class ConfigManager {
+    /** 运行时覆盖默认配置。partial 会与现有 default 做深合并，未提到的键保持原值。 */
+    static setDefaults(group, partial) {
+        currentDefaults[group] = deepMerge(currentDefaults[group], partial);
+    }
+    /** 取当前运行时 default（含 setDefaults 覆盖后的结果），返回深拷贝避免被外部修改。 */
+    static getDefaults(group) {
+        return deepClone(currentDefaults[group]);
+    }
+    /** 把所有 setDefaults 覆盖清掉，恢复到内置默认值。 */
+    static resetDefaults(group) {
+        if (group) {
+            currentDefaults[group] = deepClone(BUILTIN_DEFAULTS[group]);
+        }
+        else {
+            Object.keys(BUILTIN_DEFAULTS).forEach(k => {
+                currentDefaults[k] = deepClone(BUILTIN_DEFAULTS[k]);
+            });
+        }
+    }
+    // ---------------- 兼容性 getter（旧 callsite 直接读字段，setDefaults 透明生效）----------------
+    static get DEFAULT_POINT_OPTIONS() { return currentDefaults.POINT_OPTIONS; }
+    static get DEFAULT_POINT_TEXT_OPTIONS() { return currentDefaults.POINT_TEXT_OPTIONS; }
+    static get DEFAULT_POINT_ICON_SCALE() { return currentDefaults.POINT_ICON_SCALE; }
+    static get DEFAULT_CLUSTER_OPTIONS() { return currentDefaults.CLUSTER_OPTIONS; }
+    static get DEFAULT_DOM_POINT_OVERLAY_OPTIONS() { return currentDefaults.DOM_POINT_OVERLAY_OPTIONS; }
+    static get DEFAULT_LINE_OPTIONS() { return currentDefaults.LINE_OPTIONS; }
+    static get DEFAULT_FLOW_LINE_OPTIONS() { return currentDefaults.FLOW_LINE_OPTIONS; }
+    static get DEFAULT_POLYGON_OPTIONS() { return currentDefaults.POLYGON_OPTIONS; }
+    static get DEFAULT_POLYGON_COLOR_MAP() { return currentDefaults.POLYGON_COLOR_MAP; }
+    static get DEFAULT_IMAGE_OPTIONS() { return currentDefaults.IMAGE_OPTIONS; }
+    static get DEFAULT_MASK_OPTIONS() { return currentDefaults.MASK_OPTIONS; }
+    static get DEFAULT_TEXT_OPTIONS() { return currentDefaults.TEXT_OPTIONS; }
+    static get DEFAULT_HEATMAP_OPTIONS() { return currentDefaults.HEATMAP_OPTIONS; }
+    static get DEFAULT_HEATMAP_VALUE_KEY() { return currentDefaults.HEATMAP_VALUE_KEY; }
+    static get TIANDITU_CONFIG() { return currentDefaults.TIANDITU_CONFIG; }
+    static get DEFAULT_MAP_LAYERS_OPTIONS() { return currentDefaults.MAP_LAYERS_OPTIONS; }
+    static get DEFAULT_MYOL_OPTIONS() { return currentDefaults.MYOL_OPTIONS; }
+    static get DEFAULT_VUE_TEMPLATE_POINT_OPTIONS() { return currentDefaults.VUE_TEMPLATE_POINT_OPTIONS; }
+    static get DEFAULT_RIVER_LEVEL_WIDTH_MAP() { return currentDefaults.RIVER_LEVEL_WIDTH_MAP; }
+    static get DEFAULT_RIVER_LAYERS_BY_ZOOM_OPTIONS() { return currentDefaults.RIVER_LAYERS_BY_ZOOM_OPTIONS; }
+    static get DEFAULT_RIVER_WIDTH_BY_LEVEL_OPTIONS() { return currentDefaults.RIVER_WIDTH_BY_LEVEL_OPTIONS; }
     /**
      * 合并配置选项
      * @param defaultOptions 默认配置
@@ -29,179 +184,6 @@ class ConfigManager {
      * @returns 克隆后的对象
      */
     static deepClone(obj) {
-        if (obj === null || typeof obj !== 'object') {
-            return obj;
-        }
-        if (obj instanceof Date) {
-            return new Date(obj.getTime());
-        }
-        if (Array.isArray(obj)) {
-            return obj.map(item => ConfigManager.deepClone(item));
-        }
-        const cloned = {};
-        for (const key in obj) {
-            if (obj.hasOwnProperty(key)) {
-                cloned[key] = ConfigManager.deepClone(obj[key]);
-            }
-        }
-        return cloned;
+        return deepClone(obj);
     }
 }
-/**
- * 默认点位配置
- */
-ConfigManager.DEFAULT_POINT_OPTIONS = {
-    visible: true,
-    zIndex: 21
-};
-ConfigManager.DEFAULT_POINT_TEXT_OPTIONS = {
-    textFont: '12px Calibri,sans-serif',
-    textFillColor: '#FFF',
-    textStrokeColor: '#000',
-    textStrokeWidth: 3,
-    textOffsetY: 20
-};
-ConfigManager.DEFAULT_POINT_ICON_SCALE = 1;
-ConfigManager.DEFAULT_CLUSTER_OPTIONS = {
-    distance: 40,
-    minDistance: 0,
-    zIndex: 21
-};
-ConfigManager.DEFAULT_DOM_POINT_OVERLAY_OPTIONS = {
-    positioning: 'center-center',
-    stopEvent: false
-};
-/**
- * 默认线配置
- */
-ConfigManager.DEFAULT_LINE_OPTIONS = {
-    type: 'line',
-    strokeColor: 'rgba(3, 122, 255, 1)',
-    strokeWidth: 2,
-    visible: true,
-    layerName: 'lineLayer',
-    zIndex: 15
-};
-/**
- * 默认流动线动画配置
- */
-ConfigManager.DEFAULT_FLOW_LINE_OPTIONS = {
-    ...ConfigManager.DEFAULT_LINE_OPTIONS,
-    duration: 4000,
-    loop: true,
-    autoStart: true,
-    showBaseLine: true,
-    animationMode: 'icon',
-    flowSymbol: {
-        scale: 0.8,
-        rotateWithView: true,
-        count: 1,
-        spacing: 0.15
-    },
-    trailEnabled: false,
-    trailLength: 0,
-    zIndex: 16
-};
-/**
- * 默认面配置
- */
-ConfigManager.DEFAULT_POLYGON_OPTIONS = {
-    zIndex: 11,
-    visible: true,
-    textFont: '14px Calibri,sans-serif',
-    textFillColor: '#FFF',
-    textStrokeColor: '#409EFF',
-    textStrokeWidth: 2
-};
-ConfigManager.DEFAULT_POLYGON_COLOR_MAP = {
-    '0': 'rgba(255, 0, 0, 0.6)',
-    '1': 'rgba(245, 154, 35, 0.6)',
-    '2': 'rgba(255, 238, 0, 0.6)',
-    '3': 'rgba(1, 111, 255, 0.6)'
-};
-/**
- * 默认图片图层配置
- */
-ConfigManager.DEFAULT_IMAGE_OPTIONS = {
-    opacity: 1,
-    visible: true,
-    layerName: 'imageLayer',
-    zIndex: 11
-};
-/**
- * 默认遮罩图层配置
- */
-ConfigManager.DEFAULT_MASK_OPTIONS = {
-    fillColor: 'rgba(0, 0, 0, 0.5)',
-    opacity: 1,
-    visible: true,
-    layerName: 'maskLayer'
-};
-/**
- * 默认文本配置
- */
-ConfigManager.DEFAULT_TEXT_OPTIONS = {
-    textFont: '14px Calibri,sans-serif',
-    textFillColor: '#FFF',
-    textStrokeColor: '#409EFF',
-    textStrokeWidth: 2
-};
-ConfigManager.DEFAULT_HEATMAP_OPTIONS = {
-    blur: 15,
-    radius: 10,
-    zIndex: 11,
-    opacity: 1
-};
-ConfigManager.DEFAULT_HEATMAP_VALUE_KEY = 'value';
-ConfigManager.TIANDITU_CONFIG = {
-    BASE_URL: '//t{0-7}.tianditu.gov.cn/DataServer',
-    PROJECTION: 'EPSG:4326',
-    DEFAULT_ZINDEX: 9,
-    ANNOTATION_ZINDEX_OFFSET: 10
-};
-ConfigManager.DEFAULT_MAP_LAYERS_OPTIONS = {
-    zIndex: ConfigManager.TIANDITU_CONFIG.DEFAULT_ZINDEX,
-    annotation: false,
-    mapClip: false,
-    mapClipData: undefined
-};
-ConfigManager.DEFAULT_MYOL_OPTIONS = {
-    layers: undefined,
-    zoom: 10,
-    center: [119.81, 29.969],
-    extent: undefined
-};
-ConfigManager.DEFAULT_VUE_TEMPLATE_POINT_OPTIONS = {
-    positioning: 'center-center',
-    stopEvent: false,
-    visible: true,
-    zIndex: 1
-};
-ConfigManager.DEFAULT_RIVER_LEVEL_WIDTH_MAP = {
-    1: 2,
-    2: 1,
-    3: 0.5,
-    4: 0.5,
-    5: 0.5
-};
-ConfigManager.DEFAULT_RIVER_LAYERS_BY_ZOOM_OPTIONS = {
-    type: 'river',
-    levelCount: 5,
-    zoomOffset: 8,
-    strokeColor: 'rgb(0,113,255)',
-    strokeWidth: 3,
-    visible: true,
-    zIndex: 15,
-    layerName: 'riverLayer',
-    removeExisting: false
-};
-ConfigManager.DEFAULT_RIVER_WIDTH_BY_LEVEL_OPTIONS = {
-    type: 'river',
-    layerName: 'river',
-    strokeColor: 'rgba(3, 122, 255, 1)',
-    strokeWidth: 2,
-    visible: true,
-    zIndex: 15,
-    removeExisting: false
-};
-export default ConfigManager;

package/core/map/MapBaseLayers.d.ts

@@ -8,6 +8,7 @@ import { Tile as TileLayer } from "ol/layer";
 import { TileWMS } from "ol/source";
 import WMTSTileGrid from "ol/tilegrid/WMTS";
 import XYZ from "ol/source/XYZ";
+import BaseLayer from "ol/layer/Base";
 import { MapLayersOptions, TiandituType, AnnotationLayerOptions, AnnotationType } from "../../types";
 /**
  * GeoServer图层选项接口
@@ -100,6 +101,11 @@ export default class MapBaseLayers {
      * 获取当前底图类型
      */
     getCurrentBaseLayerType(): string | null;
+    /**
+     * 获取当前可见底图对应的 BaseLayer 数组（多 layer 的底图类型会返回多个）。
+     * 用于 MapTools.setMapClip 等需要直接操作底图实例的场景。
+     */
+    getCurrentBaseLayers(): BaseLayer[];
     /**
      * 获取默认底图类型
      * @private

package/core/map/MapBaseLayers.js

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

package/core/map/MapTools.d.ts

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

package/core/map/MapTools.js

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

package/core/point/Point.d.ts

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