my-openlayer 2.5.4 → 3.0.1

package/docs/MIGRATION-3.0.md

@@ -0,0 +1,221 @@
+# my-openlayer 3.0 迁移指南
+
+3.0 完成了一次系统性的 API 改造。图层类 `add*` 返回值会从原始 OpenLayers layer 改成统一 Handle；迁移后可以用同一套 `remove()` / `setVisible()` 管理生命周期。本指南分三段：
+
+1. **必须改的**（编译错误）
+2. **推荐改的**（用新 API 写新代码）
+3. **保留旧 API 的期限**
+
+---
+
+## 1. 必须改的（编译错误）
+
+### 1.1 `layerName` 在公开 `add*` 签名上变成必填
+
+所有 `Point.addPoint / addClusterPoint / addPulsePointLayer`、`Line.addLine / addLineByUrl / addFlowLine / addFlowLineByUrl`、`Polygon.addPolygon / addPolygonByUrl` 现在要求 `options.layerName` 是 `string`（不再可选）。
+
+```ts
+// ❌ 2.x：layerName 可选，遗忘时取 ConfigManager 默认值 'lineLayer'
+line.addLine(data)
+line.addLine(data, { strokeColor: 'red' })
+
+// ✅ 3.0：必须传 layerName
+line.addLine(data, { layerName: 'my-line' })
+line.addLine(data, { layerName: 'my-line', strokeColor: 'red' })
+```
+
+> **为什么**：依赖默认 `layerName` 的两次调用会互相覆盖，是 2.x 最常见的"图层莫名消失"陷阱。
+
+`PointOptions / LineOptions / PolygonOptions` interface **本身**没改（`layerName?: string` 仍然可选），所以已有的工厂函数、配置对象不受影响 —— 只是公开方法签名收紧了。
+
+### 1.2 `add*` 返回值改为 Handle
+
+真实图层类 `add*` 不再直接返回 OpenLayers layer，而是返回统一 `LayerHandle`。
+
+```ts
+// ❌ 2.x
+const layer = line.addLine(data, { layerName: 'l1' })
+layer.getSource()
+layer.setVisible(false)
+
+// ✅ 3.0
+const handle = line.addLine(data, { layerName: 'l1' })
+handle.layer.getSource()
+handle.setVisible(false)
+handle.remove()
+```
+
+`addDomPoint` / `addVueTemplatePoint` 不是 OL 图层，3.0 返回 `ControlHandle`：
+
+```ts
+const domHandle = point.addDomPoint(points)
+domHandle.target       // Overlay[]
+domHandle.anchors      // 兼容原字段
+
+const vueHandle = point.addVueTemplatePoint(points, Component)
+vueHandle.target       // VueTemplatePointInstance[]
+vueHandle.getPoints()  // 兼容原方法
+```
+
+---
+
+## 2. 推荐改的（用新 API 写新代码）
+
+### 2.1 用 `add*` 拿统一句柄
+
+新代码统一用 `add*` 系列：
+
+```ts
+import type { LayerHandle } from 'my-openlayer'
+
+// 跨 Point / Line / Polygon 一致的形态
+const pointHandle: LayerHandle | null = myOl.getPoint().addPoint(data, { layerName: 'p1' })
+const lineHandle:  LayerHandle        = myOl.getLine().addLine(data, { layerName: 'l1' })
+const polyHandle:  LayerHandle        = myOl.getPolygon().addPolygon(data, { layerName: 'r1' })
+
+// 统一生命周期
+pointHandle?.setVisible(false)
+pointHandle?.remove()
+```
+
+动画句柄（`PulsePointLayerHandle` / `FlowLineLayerHandle`）现在显式继承 `AnimatedLayerHandle`：
+
+```ts
+import type { AnimatedLayerHandle } from 'my-openlayer'
+
+const flowHandle: AnimatedLayerHandle | null = myOl.getLine().addFlowLine(data, { layerName: 'flow' })
+flowHandle?.start()
+flowHandle?.pause?.()
+flowHandle?.remove()
+```
+
+### 2.2 `*ByUrl` 统一异步返回 Handle
+
+旧的 `Line.addLineByUrl` / `Polygon.addPolygonByUrl` 同步返回 layer，但 features 仍在异步加载，导致 `fitView` 经常失败、`getFeatures().length === 0`。3.0 改为先 `fetch` JSON，再调用对应 add 方法：
+
+```ts
+// ❌ 2.x：返回 layer 时 features 还在路上
+const layer = polygon.addPolygonByUrl('/boundary.geojson', { layerName: 'b' })
+// layer.getSource().getFeatures().length === 0  ← 经常踩坑
+
+// ✅ 3.0：await 后拿到完整 LayerHandle
+const handle = await polygon.addPolygonByUrl('/boundary.geojson', { layerName: 'b' })
+console.log(handle.layer.getSource()?.getFeatures().length) // 准确
+```
+
+### 2.3 Point 新增 `*ByUrl` Promise API
+
+之前 `Point` 没有任何 `*ByUrl` 方法，必须自己 `fetch + addPoint`。3.0 补齐：
+
+```ts
+// 从 URL 加载点位（自动识别 PointData[] 数组或 GeoJSON FeatureCollection）
+const handle = await myOl.getPoint().addPointByUrl('/points.json', { layerName: 'p1' })
+
+const handle = await myOl.getPoint().addPulsePointLayerByUrl('/villages.json', {
+  layerName: 'villages',
+  pulse: { enabled: true, frameCount: 24 }
+})
+```
+
+### 2.4 投影注册抽到 `ProjectionManager`
+
+2.x 用 `options.projection` 注册自定义投影。3.0 仍然支持，**外加**一个独立入口：
+
+```ts
+import { ProjectionManager } from 'my-openlayer'
+
+// 应用启动时一次性注册自定义 EPSG
+ProjectionManager.register({
+  code: 'EPSG:2380',
+  def: '+proj=tmerc +lat_0=0 +lon_0=117 +k=1 +x_0=500000 +y_0=0 +ellps=WGS84 +units=m +no_defs'
+  // units 省略时由 proj4 自动推导
+})
+
+// 之后任何 new MyOl({ projection: { code: 'EPSG:2380' } }) 都能直接用
+```
+
+### 2.5 `ConfigManager.setDefaults` 全局覆盖默认值
+
+```ts
+import { ConfigManager } from 'my-openlayer'
+
+// 应用启动时把所有线的默认宽度改成 3px
+ConfigManager.setDefaults('LINE_OPTIONS', { strokeWidth: 3 })
+
+// 嵌套对象深合并
+ConfigManager.setDefaults('FLOW_LINE_OPTIONS', {
+  flowSymbol: { scale: 1.2 }  // 其它 flowSymbol 字段保持原默认
+})
+
+// 测试结束后重置
+ConfigManager.resetDefaults()              // 全部
+ConfigManager.resetDefaults('LINE_OPTIONS') // 单组
+```
+
+所有现有 `add*` 方法都通过 `ConfigManager.DEFAULT_X` getter 读默认值，因此 `setDefaults` **立即对所有后续调用生效**，不需要改任何业务代码。
+
+### 2.6 `PulsePointIconOptions.src` → `img`
+
+为了和 `PointOptions.img` 命名统一：
+
+```ts
+// ❌ 2.x（仍可用，但 @deprecated）
+point.addPulsePointLayer(data, {
+  layerName: 'p',
+  icon: { src: '/icon.svg', scale: 0.8 }
+})
+
+// ✅ 3.0
+point.addPulsePointLayer(data, {
+  layerName: 'p',
+  icon: { img: '/icon.svg', scale: 0.8 }
+})
+```
+
+PointPulseLayer 同时识别 `img` 和 `src`，平滑过渡。
+
+### 2.7 用具体错误类型做精细化处理
+
+```ts
+import { LayerNotFoundError, InvalidGeoJSONError, ProjectionError } from 'my-openlayer'
+
+try {
+  polygon.updateFeatureColor('nonexistent', { /* ... */ })
+} catch (e) {
+  if (e instanceof LayerNotFoundError) {
+    // 友好提示
+    showToast(`图层 "${e.context.layerName}" 不存在，请先调用 addPolygon`)
+  } else if (e instanceof InvalidGeoJSONError) {
+    showToast('GeoJSON 数据格式有误')
+  } else {
+    throw e
+  }
+}
+```
+
+---
+
+## 3. 保留旧 API 的期限
+
+下列旧 API 在 3.0 标了 `@deprecated`，**3.x 整个生命周期都仍然可用**，但 3.x 末尾（4.0）会移除。建议趁早迁移：
+
+| 旧 API | 替代品 |
+|---|---|
+| `add*` 不传 `layerName`（仅使用 `ConfigManager.DEFAULT_*.layerName`） | `add*` 显式传 `layerName` |
+| `addPolygonByUrl`（同步返回 layer） | `await addPolygonByUrl`（Promise<LayerHandle>） |
+| `addLineByUrl`（同步返回 layer） | `await addLineByUrl`（Promise<LayerHandle>） |
+| `MyOl.getView` | `MyOl.createView` |
+| `PulsePointIconOptions.src` | `PulsePointIconOptions.img` |
+| `(MyOl as any).initializeProjections` | `ProjectionManager.initialize` |
+
+---
+
+## 4. 升级前后检查清单
+
+- [ ] 所有 `add*` 调用都显式传 `layerName`（TS 编译会提示）
+- [ ] `addPolygonByUrl` / `addLineByUrl` 调用处加 `await`，并通过 `handle.layer` 访问底层图层
+- [ ] `MyOl.destroy()` 调用后是否真的需要重建地图（destroy 已强化级联清理，老代码可能不再需要手动 stop 各 handle）
+- [ ] 自定义投影注册：尝试迁移到 `ProjectionManager.register` 集中管理
+- [ ] 全局样式默认值：用 `ConfigManager.setDefaults` 替代多处复制 options
+
+升级过程中遇到任何"老代码 TS 编译过不去"的情况，请优先翻看本指南第 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,13 @@ 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, MapJSONData, FeatureData, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } 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';
+export { VueTemplatePointState } from './types';

package/index.js

@@ -7,7 +7,10 @@ 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 模板点位状态枚举（运行时值，需要单独导出）
+export { VueTemplatePointState } from './types';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "2.5.4",
+  "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';
+    }
+}
 /**
  * 错误处理工具类
  */