my-openlayer 2.5.5 → 3.0.1

package/docs/Point.md

@@ -94,24 +94,32 @@ constructor(map: Map)
 添加普通点图层。
 
 ```typescript
-addPoint(pointData: PointData[], options: PointOptions): VectorLayer<VectorSource> | null
+addPoint(pointData: PointData[], options: PointOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
 - **pointData**: 点位数据数组。
 - **options**: 配置选项。
-- **返回值**: 创建的向量图层，如果数据无效返回 `null`。
+- **返回值**: `{ layer, remove(), setVisible() }` 形态的统一句柄；如果数据无效返回 `null`。
 
 ### addClusterPoint
 
 添加聚合点图层。
 
 ```typescript
-addClusterPoint(pointData: PointData[], options: ClusterOptions): VectorLayer<VectorSource> | null
+addClusterPoint(pointData: PointData[], options: ClusterOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
 - **pointData**: 点位数据数组。
 - **options**: 聚合配置选项。
-- **返回值**: 创建的聚合图层。
+- **返回值**: `{ layer, remove(), setVisible() }` 形态的统一句柄。
+
+### addPointByUrl
+
+从 URL 加载点位数据，支持 `PointData[]` 数组或 GeoJSON FeatureCollection。
+
+```typescript
+addPointByUrl(url: string, options: PointOptions & { layerName: string }): Promise<LayerHandle<VectorLayer<VectorSource>> | null>
+```
 
 ### addDomPoint
 
@@ -119,6 +127,7 @@ addClusterPoint(pointData: PointData[], options: ClusterOptions): VectorLayer<Ve
 
 ```typescript
 addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
+  target: Overlay[],
   anchors: Overlay[],
   remove: () => void,
   setVisible: (visible: boolean) => void
@@ -127,7 +136,7 @@ addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
 
 - **twinkleList**: 包含经纬度和类名的数据列表。
 - **callback**: 点击回调函数。
-- **返回值**: 控制对象，包含 `remove` 和 `setVisible` 方法。
+- **返回值**: 控制对象，包含 `target`、`anchors`、`remove` 和 `setVisible`。
 
 ### addPulsePointLayer
 
@@ -141,12 +150,21 @@ addPulsePointLayer(pointData: PointData[], options: PulsePointOptions): PulsePoi
 - **options**: 闪烁点配置选项，复用 `addPoint` 的图标、文本和图层参数习惯。
 - **返回值**: 控制对象，包含动画启停、显隐、数据更新和移除方法；如果数据无效返回 `null`。
 
+### addPulsePointLayerByUrl
+
+从 URL 加载点位数据并添加高性能闪烁点图层。
+
+```typescript
+addPulsePointLayerByUrl(url: string, options: PulsePointOptions & { layerName: string }): Promise<PulsePointLayerHandle | null>
+```
+
 ### addVueTemplatePoint
 
 添加 Vue 组件作为点位。
 
 ```typescript
 addVueTemplatePoint(pointDataList: PointData[], template: any, options?: VueTemplatePointOptions): {
+  target: VueTemplatePointInstance[],
   setVisible: (visible: boolean) => void,
   setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void,
   remove: () => void,
@@ -157,7 +175,7 @@ addVueTemplatePoint(pointDataList: PointData[], template: any, options?: VueTemp
 - **pointDataList**: 点位数据列表。
 - **template**: Vue 组件。
 - **options**: 配置选项。
-- **返回值**: 控制对象，包含显示/隐藏和移除方法。
+- **返回值**: 控制对象，包含 `target`、显示/隐藏、按属性显示/隐藏和移除方法。
 
 ## 使用示例
 

package/docs/Polygon.md

@@ -69,7 +69,7 @@ const polygon = new Polygon(map: Map);
 添加多边形图层。
 
 ```typescript
-addPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>
+addPolygon(data: MapJSONData, options: PolygonOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>>
 ```
 
 | 参数 | 类型 | 说明 |
@@ -82,7 +82,7 @@ addPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSourc
 从 URL 加载多边形图层。
 
 ```typescript
-addPolygonByUrl(url: string, options?: PolygonOptions): VectorLayer<VectorSource>
+addPolygonByUrl(url: string, options: PolygonOptions & { layerName: string }): Promise<LayerHandle<VectorLayer<VectorSource>>>
 ```
 
 ### addBorderPolygon
@@ -90,7 +90,8 @@ addPolygonByUrl(url: string, options?: PolygonOptions): VectorLayer<VectorSource
 添加边界图层（通常用于行政区划边界，支持镂空效果）。
 
 ```typescript
-addBorderPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>
+addBorderPolygon(data: MapJSONData, options?: PolygonOptions): LayerHandle<VectorLayer<VectorSource>>
+addBorderPolygonByUrl(url: string, options?: PolygonOptions): Promise<LayerHandle<VectorLayer<VectorSource>>>
 ```
 
 ### updateFeatureColor
@@ -116,7 +117,7 @@ updateFeatureColor(
 添加静态图片图层（如叠加平面图、卫星图）。
 
 ```typescript
-addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): ImageLayer<any>
+addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): LayerHandle<ImageLayer<any>>
 ```
 
 ### addHeatmap
@@ -124,7 +125,15 @@ addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): ImageLayer<a
 添加热力图。
 
 ```typescript
-addHeatmap(pointData: PointData[], options?: HeatMapOptions): Heatmap
+addHeatmap(pointData: PointData[], options?: HeatMapOptions): LayerHandle<BaseLayer>
+```
+
+### addMaskLayer
+
+添加遮罩图层。
+
+```typescript
+addMaskLayer(data: MapJSONData, options?: MaskLayerOptions): LayerHandle<VectorLayer<VectorSource>>
 ```
 
 ### setOutLayer

package/index.d.ts

@@ -7,10 +7,12 @@ export { Polygon } from './core/polygon';
 export { MapBaseLayers, MapTools, MeasureHandler, ConfigManager, EventManager } from './core/map';
 export { VueTemplatePoint } from './core/vue-template-point';
 export { SelectHandler } from './core/select';
+export { ProjectionManager, PROJECTIONS } from './core/projection';
+export type { CustomProjectionRegistration } from './core/projection';
 export type { MapEventType, EventCallback, MapEventData } from './core/map/EventManager';
-export { ErrorHandler, MyOpenLayersError, ErrorType } from './utils/ErrorHandler';
+export { ErrorHandler, MyOpenLayersError, ErrorType, LayerNotFoundError, InvalidGeoJSONError, ProjectionError } from './utils/ErrorHandler';
 export { default as ValidationUtils } from './utils/ValidationUtils';
-export type { BaseOptions, StyleOptions, TextOptions } from './types';
+export type { BaseOptions, StyleOptions, TextOptions, LayerHandle, AnimatedLayerHandle } from './types';
 export type { PointOptions, LineOptions, FlowLineOptions, FlowLineLayerHandle, PolygonOptions, PulsePointOptions, 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, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './types';

package/index.js

@@ -7,8 +7,9 @@ export { Polygon } from './core/polygon';
 export { MapBaseLayers, MapTools, MeasureHandler, ConfigManager, EventManager } from './core/map';
 export { VueTemplatePoint } from './core/vue-template-point';
 export { SelectHandler } from './core/select';
+export { ProjectionManager, PROJECTIONS } from './core/projection';
 // 错误处理
-export { ErrorHandler, MyOpenLayersError, ErrorType } from './utils/ErrorHandler';
+export { ErrorHandler, MyOpenLayersError, ErrorType, LayerNotFoundError, InvalidGeoJSONError, ProjectionError } from './utils/ErrorHandler';
 // 验证工具
 export { default as ValidationUtils } from './utils/ValidationUtils';
 // Vue 模板点位状态枚举（运行时值，需要单独导出）

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "2.5.5",
+  "version": "3.0.1",
   "type": "module",
   "license": "MIT",
   "main": "index.js",
@@ -47,7 +47,8 @@
     "publish-flat-dry": "npm run build && npm run prepare-publish && cd temp-publish && npm publish --dry-run",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "demo:build": "vite build --base /my-openlayer/demo/ --outDir demo-dist"
   },
   "dependencies": {
     "@turf/turf": "^7.2.0",
@@ -57,12 +58,14 @@
   "devDependencies": {
     "@types/proj4": "^2.5.2",
     "@vitejs/plugin-vue": "^5.0.4",
+    "happy-dom": "^20.9.0",
     "typescript": "~5.6.2",
     "vite": "^5.4.10",
-    "vitest": "^2.1.9",
     "vite-plugin-css-modules": "^0.0.1",
     "vite-plugin-libcss": "^1.1.1",
     "vitepress": "^1.6.4",
+    "vitest": "^2.1.9",
+    "vue-router": "^4.6.4",
     "vue-tsc": "^2.0.6"
   },
   "peerDependencies": {

package/types/base.d.ts

@@ -1,4 +1,4 @@
-import Feature, { FeatureLike } from "ol/Feature";
+import { FeatureLike } from "ol/Feature";
 import { Style } from "ol/style";
 import type { MapJSONData } from "./common";
 /**
@@ -17,7 +17,7 @@ export interface BaseOptions {
     /**
      * @deprecated 新项目请使用 dataProjection / featureProjection。
      */
-    projectionOptOptions?: any;
+    projectionOptOptions?: Record<string, unknown>;
     style?: Style | Style[] | ((feature: FeatureLike) => Style | Style[]);
 }
 /**
@@ -29,7 +29,7 @@ export interface StyleOptions {
     lineDash?: number[];
     lineDashOffset?: number;
     fillColor?: string;
-    fillColorCallBack?: (feature: Feature) => string;
+    fillColorCallBack?: (feature: FeatureLike) => string;
     withDefaultStroke?: boolean;
     withDefaultFill?: boolean;
 }
@@ -38,7 +38,7 @@ export interface StyleOptions {
  */
 export interface TextOptions {
     textVisible?: boolean;
-    textCallBack?: (feature: Feature) => string;
+    textCallBack?: (feature: FeatureLike) => string;
     textFont?: string;
     textFillColor?: string;
     textStrokeColor?: string;

package/types/common.d.ts

@@ -3,10 +3,10 @@
  */
 export interface FeatureData {
     type: string;
-    properties: any;
+    properties: Record<string, unknown>;
     geometry: {
         type: "Polygon" | "MultiPolygon" | "Point" | "LineString" | "MultiLineString" | "MultiPoint" | "GeometryCollection";
-        coordinates: any[];
+        coordinates: number[] | number[][] | number[][][] | number[][][][];
     };
 }
 /**
@@ -33,18 +33,18 @@ export type OptionsType = {
     mapClipData?: MapJSONData;
     dataProjection?: string;
     featureProjection?: string;
-    projectionOptOptions?: any;
-    style?: any;
+    projectionOptOptions?: Record<string, unknown>;
+    style?: Style | Style[] | ((feature: FeatureLike) => Style | Style[]);
     strokeColor?: string | number[];
     strokeWidth?: number;
     lineDash?: number[];
     lineDashOffset?: number;
     fillColor?: string;
-    fillColorCallBack?: (feature: any) => string;
+    fillColorCallBack?: (feature: FeatureLike) => string;
     withDefaultStroke?: boolean;
     withDefaultFill?: boolean;
     textVisible?: boolean;
-    textCallBack?: (feature: any) => string;
+    textCallBack?: (feature: FeatureLike) => string;
     textFont?: string;
     textFillColor?: string;
     textStrokeColor?: string;
@@ -57,3 +57,5 @@ export type OptionsType = {
     type?: string;
     mask?: boolean;
 };
+import type { FeatureLike } from "ol/Feature";
+import type { Style } from "ol/style";

package/types/handle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * P1-1：统一图层句柄接口。
+ *
+ * 真实图层类 add* 方法在 3.0 之后都返回符合 LayerHandle 的对象，
+ * 用户记一次 `{ layer, remove, setVisible }` 就能跨 Point / Line / Polygon 通用。
+ *
+ * 动画句柄（流动线、闪烁点）扩展为 AnimatedLayerHandle，额外暴露 start/stop。
+ * Overlay / Vue 组件点这类非图层控制对象使用 ControlHandle，通过 target 暴露控制目标。
+ */
+import type BaseLayer from "ol/layer/Base";
+export interface LayerHandle<L extends BaseLayer = BaseLayer> {
+    /** 实际的 OL 图层实例。 */
+    readonly layer: L;
+    /** 从地图移除此图层，停止所有动画与监听。可安全多次调用。 */
+    remove(): void;
+    /** 切换图层可见性。 */
+    setVisible(visible: boolean): void;
+}
+export interface AnimatedLayerHandle<L extends BaseLayer = BaseLayer> extends LayerHandle<L> {
+    start(): void;
+    stop(): void;
+    pause?(): void;
+    resume?(): void;
+    /** 更新底层数据（数据形态因实现而异）。 */
+    updateData?(data: unknown): void;
+}
+export interface ControlHandle<T = unknown> {
+    /** 非 OL 图层控制目标，例如 Overlay[] 或 VueTemplatePointInstance[]。 */
+    readonly target: T;
+    /** 移除控制目标。可安全多次调用。 */
+    remove(): void;
+    /** 切换控制目标可见性。 */
+    setVisible(visible: boolean): void;
+}

package/types/handle.js

@@ -0,0 +1 @@
+export {};

package/types/index.d.ts

@@ -1,4 +1,5 @@
 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, ClusterOptions, PulsePointIconOptions, PulsePointOptions, PulsePointLayerHandle, TwinkleItem } from './point';

package/types/line.d.ts

@@ -1,6 +1,7 @@
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import type { BaseOptions, StyleOptions, TextOptions } from "./base";
+import type { AnimatedLayerHandle } from "./handle";
 import type { MapJSONData } from "./common";
 export interface LineOptions extends BaseOptions, StyleOptions, TextOptions {
     type?: string;
@@ -8,7 +9,7 @@ export interface LineOptions extends BaseOptions, StyleOptions, TextOptions {
 export interface LineData {
     type: string;
     coordinates: number[][];
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface FlowLineOptions extends LineOptions {
     loop?: boolean;
@@ -28,7 +29,7 @@ export interface FlowLineOptions extends LineOptions {
     trailEnabled?: boolean;
     trailLength?: number;
 }
-export interface FlowLineLayerHandle {
+export interface FlowLineLayerHandle extends AnimatedLayerHandle<VectorLayer<VectorSource>> {
     layer: VectorLayer<VectorSource>;
     animationLayer: VectorLayer<VectorSource>;
     start: () => void;

package/types/map.d.ts

@@ -65,7 +65,7 @@ export interface ImageLayerData {
     extent?: number[];
 }
 export interface MaskLayerOptions {
-    extent?: any;
+    extent?: number[];
     fillColor?: string;
     strokeWidth?: number;
     strokeColor?: string;

package/types/point.d.ts

@@ -1,6 +1,7 @@
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import type { BaseOptions, StyleOptions, TextOptions } from "./base";
+import type { AnimatedLayerHandle } from "./handle";
 export interface PointOptions extends BaseOptions, StyleOptions, TextOptions {
     textKey?: string;
     img?: string;
@@ -10,13 +11,20 @@ export interface PointOptions extends BaseOptions, StyleOptions, TextOptions {
 export interface PointData {
     lgtd: number;
     lttd: number;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface ClusterOptions extends PointOptions {
     distance?: number;
     minDistance?: number;
 }
 export interface PulsePointIconOptions {
+    /**
+     * 图标资源 URL。
+     */
+    img?: string;
+    /**
+     * @deprecated 请使用 `img` 字段，3.x 末尾会移除。
+     */
     src?: string;
     scale?: number;
     color?: string;
@@ -38,7 +46,7 @@ export interface PulsePointOptions extends PointOptions {
         frameCount?: number;
     };
 }
-export interface PulsePointLayerHandle {
+export interface PulsePointLayerHandle extends AnimatedLayerHandle<VectorLayer<VectorSource>> {
     layer: VectorLayer<VectorSource>;
     source: VectorSource;
     start: () => void;
@@ -50,5 +58,5 @@ export interface PulsePointLayerHandle {
 export interface TwinkleItem extends PointData {
     className?: string;
     element?: HTMLElement | ((item: TwinkleItem) => HTMLElement);
-    [key: string]: any;
+    [key: string]: unknown;
 }

package/utils/ErrorHandler.d.ts

@@ -18,6 +18,18 @@ export declare class MyOpenLayersError extends Error {
     readonly context?: any;
     constructor(message: string, type: ErrorType, context?: any);
 }
+/**
+ * P2-2：具体错误子类，方便调用方用 instanceof 判分支。
+ */
+export declare class LayerNotFoundError extends MyOpenLayersError {
+    constructor(layerName: string, context?: any);
+}
+export declare class InvalidGeoJSONError extends MyOpenLayersError {
+    constructor(reason: string, context?: any);
+}
+export declare class ProjectionError extends MyOpenLayersError {
+    constructor(reason: string, context?: any);
+}
 /**
  * 错误处理工具类
  */

package/utils/ErrorHandler.js

@@ -30,6 +30,27 @@ export class MyOpenLayersError extends Error {
         }
     }
 }
+/**
+ * P2-2：具体错误子类，方便调用方用 instanceof 判分支。
+ */
+export class LayerNotFoundError extends MyOpenLayersError {
+    constructor(layerName, context) {
+        super(`Layer '${layerName}' not found. 请检查 layerName 拼写、图层是否已被 remove，或在 fitView / removeLayer 调用前先 await *ByUrl。`, ErrorType.LAYER_ERROR, { layerName, ...context });
+        this.name = 'LayerNotFoundError';
+    }
+}
+export class InvalidGeoJSONError extends MyOpenLayersError {
+    constructor(reason, context) {
+        super(`Invalid GeoJSON data: ${reason}. 请检查数据是否为标准 GeoJSON FeatureCollection / Feature / Geometry。`, ErrorType.DATA_ERROR, context);
+        this.name = 'InvalidGeoJSONError';
+    }
+}
+export class ProjectionError extends MyOpenLayersError {
+    constructor(reason, context) {
+        super(`Projection error: ${reason}. 请确认 EPSG code 已通过 ProjectionManager.register 或 options.projection 注册。`, ErrorType.MAP_ERROR, context);
+        this.name = 'ProjectionError';
+    }
+}
 /**
  * 错误处理工具类
  */