my-openlayer 2.5.5 → 3.0.1

package/core/polygon/PolygonHeatmapLayer.js

@@ -3,6 +3,7 @@ import { Point } from "ol/geom";
 import { Heatmap } from "ol/layer";
 import VectorSource from "ol/source/Vector";
 import { ConfigManager, MapTools } from "../map";
+import { ErrorHandler } from "../../utils/ErrorHandler";
 /**
  * 面热力图辅助类。
  */
@@ -28,11 +29,23 @@ export default class PolygonHeatmapLayer {
         }
         map.addLayer(heatmapLayer);
         const valueKey = mergedOptions.valueKey || ConfigManager.DEFAULT_HEATMAP_VALUE_KEY;
-        const max = Math.max(...pointData.map(item => item[valueKey]));
+        // 计算归一化最大值。当数据里没有 valueKey 或值全为非数字时，max 是 NaN/-Infinity，
+        // 会导致 weight = value/max = NaN，OL 热力图整层不渲染。
+        // 此时回退到等权重 1（让用户至少看到热力图，再去补 valueKey）。
+        const numericValues = pointData
+            .map(item => Number(item[valueKey]))
+            .filter(v => Number.isFinite(v));
+        const max = numericValues.length > 0 ? Math.max(...numericValues) : 0;
+        const useFallbackWeight = max <= 0;
+        if (useFallbackWeight) {
+            ErrorHandler.getInstance().warn(`[Heatmap] 数据中未找到有效的 "${valueKey}" 字段，已回退为等权重渲染。请通过 options.valueKey 指定正确字段。`);
+        }
         pointData.forEach(item => {
+            const raw = Number(item[valueKey]);
+            const weight = useFallbackWeight || !Number.isFinite(raw) ? 1 : raw / max;
             heatmapLayer.getSource().addFeature(new Feature({
                 geometry: new Point([item.lgtd, item.lttd]),
-                weight: item[valueKey] / max
+                weight
             }));
         });
         return heatmapLayer;

package/core/polygon/PolygonMaskLayer.d.ts

@@ -10,11 +10,11 @@ import type { MapJSONData, MaskLayerOptions } from "../../types";
 export default class PolygonMaskLayer {
     static setOutLayer(map: Map, data: MapJSONData, options?: {
         layerName?: string;
-        extent?: any;
+        extent?: number[];
         fillColor?: string;
         strokeWidth?: number;
         strokeColor?: string;
         zIndex?: number;
     }): VectorLayer<VectorSource<Feature<Geometry>>, Feature<Geometry>>;
-    static addMaskLayer(map: Map, data: any, options?: MaskLayerOptions): VectorLayer<VectorSource>;
+    static addMaskLayer(map: Map, data: MapJSONData, options?: MaskLayerOptions): VectorLayer<VectorSource>;
 }

package/core/polygon/PolygonMaskLayer.js

@@ -98,7 +98,9 @@ export default class PolygonMaskLayer {
                 }) : undefined
             }),
             opacity: mergedOptions.opacity,
-            visible: mergedOptions.visible
+            visible: mergedOptions.visible,
+            // 显式传 zIndex，否则被天地图底图（zIndex 9）盖住，用户看不到 mask
+            zIndex: mergedOptions.zIndex
         });
         maskLayer.set('layerName', mergedOptions.layerName);
         map.addLayer(maskLayer);

package/core/polygon/PolygonStyleFactory.d.ts

@@ -1,11 +1,12 @@
-import Feature from "ol/Feature";
+import Feature, { type FeatureLike } from "ol/Feature";
+import { Style } from "ol/style";
 import type { FeatureColorUpdateOptions, PolygonOptions } from "../../types";
 /**
  * 面图层样式工厂。
  */
 export default class PolygonStyleFactory {
-    static getFeatureText(feature: Feature, options: PolygonOptions | FeatureColorUpdateOptions): string;
-    static createStyle(options: PolygonOptions): any;
+    static getFeatureText(feature: FeatureLike, options: PolygonOptions | FeatureColorUpdateOptions): string;
+    static createStyle(options: PolygonOptions): Style | Style[] | ((feature: FeatureLike) => Style | Style[]);
     static updateSingleFeatureColor(feature: Feature, colorObj?: {
         [propName: string]: string;
     }, options?: FeatureColorUpdateOptions): void;

package/core/projection/ProjectionManager.d.ts

@@ -0,0 +1,66 @@
+import { Projection as olProjProjection } from "ol/proj";
+import type { Units } from "ol/proj/Units";
+import type { MapInitType } from "../../types";
+/**
+ * 项目内置 EPSG 编码。
+ */
+export declare const PROJECTIONS: {
+    readonly WGS84: "EPSG:4326";
+    readonly CGCS2000: "EPSG:4490";
+    readonly CGCS2000_3_DEGREE: "EPSG:4549";
+};
+/**
+ * 自定义投影注册元数据。
+ */
+export interface CustomProjectionRegistration {
+    /** EPSG 编码，例如 "EPSG:4528" */
+    code: string;
+    /** proj4 定义字符串 */
+    def: string;
+    /** 投影范围 [minX, minY, maxX, maxY] */
+    extent?: number[];
+    /** 世界范围 [minX, minY, maxX, maxY] */
+    worldExtent?: number[];
+    /** OL 投影单位（degrees / m / ft 等），未提供时从 proj4 定义自动推导 */
+    units?: Units;
+}
+export default class ProjectionManager {
+    /** 项目内置 EPSG 编码常量。 */
+    static readonly PROJECTIONS: {
+        readonly WGS84: "EPSG:4326";
+        readonly CGCS2000: "EPSG:4490";
+        readonly CGCS2000_3_DEGREE: "EPSG:4549";
+    };
+    /** 默认投影 = EPSG:4490 (CGCS2000)。 */
+    static readonly DEFAULT_PROJECTION: "EPSG:4490";
+    /**
+     * 注册内置投影 + 应用 options.projection 自定义投影。
+     *
+     * 幂等：重复调用安全。被 MyOl 构造函数和 MyOl.createView 都会调，外部一般无需直接调用。
+     */
+    static initialize(options?: MapInitType): void;
+    /**
+     * 注册一个任意 EPSG 投影到 proj4 + OL。
+     *
+     * 这是 MyOl 之外的便利入口。units 未提供时由 proj4 自动推导。
+     */
+    static register(registration: CustomProjectionRegistration): void;
+    /**
+     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
+     *
+     * 仅当 options 显式覆盖 extent / worldExtent / units 之一时才新建 Projection 实例。
+     */
+    static resolveViewProjection(options: MapInitType, code: string): olProjProjection;
+    /**
+     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
+     */
+    private static ensureProj4Definition;
+    /**
+     * 应用用户显式提供的投影元数据。
+     *
+     * - 提供 units：以用户输入为权威，覆盖已注册投影
+     * - 未提供 units 但已注册：仅刷新 extent / worldExtent
+     * - 未提供 units 且未注册：新建 Projection（OL 会从 proj4 推导单位）
+     */
+    private static applyCustomProjectionMetadata;
+}

package/core/projection/ProjectionManager.js

@@ -0,0 +1,144 @@
+/**
+ * 投影管理器
+ *
+ * 集中管理所有投影注册与解析逻辑，对外暴露内置常量（EPSG:4326 / 4490 / 4549）以及
+ * 自定义投影注册入口。MyOl 内部委托此类初始化投影，使用户也可以在 MyOl 实例之外
+ * 主动注册新的 EPSG。
+ */
+import proj4 from "proj4";
+import { register as olProj4Register } from "ol/proj/proj4";
+import { Projection as olProjProjection, addProjection as olProjAddProjection, get as olProjGetProjection } from "ol/proj";
+/**
+ * 项目内置 EPSG 编码。
+ */
+export const PROJECTIONS = {
+    WGS84: "EPSG:4326",
+    CGCS2000: "EPSG:4490",
+    CGCS2000_3_DEGREE: "EPSG:4549"
+};
+/**
+ * 内置 EPSG 的 proj4 定义字符串。
+ */
+const PROJECTION_DEFINITIONS = {
+    [PROJECTIONS.WGS84]: "+title=WGS 84 (long/lat) +proj=longlat +ellps=WGS84 +datum=WGS84 +units=degrees",
+    [PROJECTIONS.CGCS2000]: "+proj=longlat +ellps=GRS80 +no_defs",
+    [PROJECTIONS.CGCS2000_3_DEGREE]: "+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=500000 +y_0=0 +ellps=GRS80 +units=m +no_defs"
+};
+class ProjectionManager {
+    /**
+     * 注册内置投影 + 应用 options.projection 自定义投影。
+     *
+     * 幂等：重复调用安全。被 MyOl 构造函数和 MyOl.createView 都会调，外部一般无需直接调用。
+     */
+    static initialize(options) {
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.WGS84, PROJECTION_DEFINITIONS[PROJECTIONS.WGS84]);
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.CGCS2000, PROJECTION_DEFINITIONS[PROJECTIONS.CGCS2000]);
+        ProjectionManager.ensureProj4Definition(PROJECTIONS.CGCS2000_3_DEGREE, PROJECTION_DEFINITIONS[PROJECTIONS.CGCS2000_3_DEGREE]);
+        // 用户自定义投影的 proj4 定义优先注入
+        if (options?.projection?.code && options.projection.def) {
+            proj4.defs(options.projection.code, options.projection.def);
+        }
+        // 注入 proj4 → OpenLayers
+        olProj4Register(proj4);
+        // 注册 CGCS2000 OL Projection（带 degrees 单位）
+        olProjAddProjection(new olProjProjection({
+            code: PROJECTIONS.CGCS2000,
+            extent: [-180, -90, 180, 90],
+            worldExtent: [-180, -90, 180, 90],
+            units: "degrees"
+        }));
+        if (options?.projection?.code) {
+            ProjectionManager.applyCustomProjectionMetadata(options.projection);
+        }
+    }
+    /**
+     * 注册一个任意 EPSG 投影到 proj4 + OL。
+     *
+     * 这是 MyOl 之外的便利入口。units 未提供时由 proj4 自动推导。
+     */
+    static register(registration) {
+        const { code, def, extent, worldExtent, units } = registration;
+        ProjectionManager.ensureProj4Definition(code, def);
+        olProj4Register(proj4);
+        ProjectionManager.applyCustomProjectionMetadata({
+            code,
+            def,
+            extent,
+            worldExtent,
+            units
+        });
+    }
+    /**
+     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
+     *
+     * 仅当 options 显式覆盖 extent / worldExtent / units 之一时才新建 Projection 实例。
+     */
+    static resolveViewProjection(options, code) {
+        const registeredProjection = olProjGetProjection(code);
+        if (registeredProjection
+            && !options.projection?.extent
+            && !options.projection?.worldExtent
+            && !options.projection?.units) {
+            return registeredProjection;
+        }
+        return new olProjProjection({
+            code,
+            extent: options.projection?.extent
+                ?? registeredProjection?.getExtent()
+                ?? [-180, -90, 180, 90],
+            worldExtent: options.projection?.worldExtent
+                ?? registeredProjection?.getWorldExtent()
+                ?? [-180, -90, 180, 90],
+            units: options.projection?.units
+                ?? registeredProjection?.getUnits()
+                ?? "degrees"
+        });
+    }
+    /**
+     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
+     */
+    static ensureProj4Definition(code, definition) {
+        if (!proj4.defs(code)) {
+            proj4.defs(code, definition);
+        }
+    }
+    /**
+     * 应用用户显式提供的投影元数据。
+     *
+     * - 提供 units：以用户输入为权威，覆盖已注册投影
+     * - 未提供 units 但已注册：仅刷新 extent / worldExtent
+     * - 未提供 units 且未注册：新建 Projection（OL 会从 proj4 推导单位）
+     */
+    static applyCustomProjectionMetadata(projection) {
+        const { code, extent, worldExtent, units } = projection;
+        const registeredProjection = olProjGetProjection(code);
+        if (units) {
+            olProjAddProjection(new olProjProjection({
+                code,
+                extent: extent ?? registeredProjection?.getExtent(),
+                worldExtent: worldExtent ?? registeredProjection?.getWorldExtent(),
+                units
+            }));
+            return;
+        }
+        if (registeredProjection) {
+            if (extent)
+                registeredProjection.setExtent(extent);
+            if (worldExtent)
+                registeredProjection.setWorldExtent(worldExtent);
+            return;
+        }
+        if (extent || worldExtent) {
+            olProjAddProjection(new olProjProjection({
+                code,
+                extent,
+                worldExtent
+            }));
+        }
+    }
+}
+/** 项目内置 EPSG 编码常量。 */
+ProjectionManager.PROJECTIONS = PROJECTIONS;
+/** 默认投影 = EPSG:4490 (CGCS2000)。 */
+ProjectionManager.DEFAULT_PROJECTION = PROJECTIONS.CGCS2000;
+export default ProjectionManager;

package/core/projection/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ProjectionManager, PROJECTIONS } from './ProjectionManager';
+export type { CustomProjectionRegistration } from './ProjectionManager';

package/core/projection/index.js

@@ -0,0 +1 @@
+export { default as ProjectionManager, PROJECTIONS } from './ProjectionManager';

package/core/select/SelectHandler.d.ts

@@ -64,7 +64,7 @@ export default class SelectHandler {
     /**
      * 通过属性选择要素
      */
-    selectByProperty(propertyName: string, propertyValue: any, options?: ProgrammaticSelectOptions): this;
+    selectByProperty(propertyName: string, propertyValue: unknown, options?: ProgrammaticSelectOptions): this;
     /**
      * 应用选择（编程式）
      */

package/core/vue-template-point/VueTemplatePoint.d.ts

@@ -1,5 +1,5 @@
 import { Map as OLMap } from 'ol';
-import { VueTemplatePointInstance } from '../../types';
+import { ControlHandle, VueTemplatePointInstance } from '../../types';
 /**
  * Vue模板点位管理类
  * 用于在地图上添加和管理Vue组件覆盖物
@@ -23,10 +23,8 @@ export default class VueTemplatePoint {
     addVueTemplatePoint(pointDataList: any[], template: any, 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;
+    }): ControlHandle<VueTemplatePointInstance[]> & {
         setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void;
-        remove: () => void;
         getPoints: () => VueTemplatePointInstance[];
     };
     /**

package/core/vue-template-point/VueTemplatePoint.js

@@ -113,6 +113,7 @@ export default class VueTemplatePoint {
                 this.vuePoints.set(instance.id, instance);
             });
             return {
+                target: instances,
                 setVisible: (visible) => {
                     instances.forEach((instance) => {
                         instance.setVisible(visible);
@@ -378,9 +379,22 @@ class VueTemplatePointInstanceImpl {
             throw new Error('Cannot update props on destroyed DOM point');
         }
         try {
-            // 重新创建Vue应用实例
+            // 重新创建Vue应用实例。
+            // 注意：createVueApp 把 options.props 当 Vue 组件的 props 声明（非传值），
+            // 根组件没有父组件传值，因此必须把每个值包成 { default: value } 才能被
+            // Vue 当 prop 默认值消费，render 里才能读到。
             this.destroyVueApp();
-            this.options.props = { ...this.options.props, ...newProps };
+            const normalized = { ...this.options.props };
+            for (const key of Object.keys(newProps)) {
+                const value = newProps[key];
+                // 已经是 { type, default } 形式则原样合并，否则包装为默认值
+                const isAlreadyDeclaration = value !== null
+                    && typeof value === 'object'
+                    && (Object.prototype.hasOwnProperty.call(value, 'default')
+                        || Object.prototype.hasOwnProperty.call(value, 'type'));
+                normalized[key] = isAlreadyDeclaration ? value : { default: value };
+            }
+            this.options.props = normalized;
             this.createVueApp();
         }
         catch (error) {

package/docs/.vitepress/config.mts

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

package/docs/Line.md

@@ -65,18 +65,18 @@ interface FlowLineLayerHandle {
 ### addLine
 
 ```typescript
-addLine(data: MapJSONData, options?: LineOptions): VectorLayer<VectorSource>
+addLine(data: MapJSONData, options: LineOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>>
 ```
 
-添加静态线图层。
+添加静态线图层，返回统一 `LayerHandle`。
 
 ### addLineByUrl
 
 ```typescript
-addLineByUrl(url: string, options?: LineOptions): VectorLayer<VectorSource>
+addLineByUrl(url: string, options: LineOptions & { layerName: string }): Promise<LayerHandle<VectorLayer<VectorSource>>>
 ```
 
-从 URL 加载并添加静态线图层。
+从 URL 加载 GeoJSON 后添加静态线图层，await 后返回完整 `LayerHandle`。
 
 ### removeLineLayer
 

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 节。