my-openlayer 2.5.5 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## [3.0.0] - 2026-05-22
+
+### 🚀 BREAKING CHANGE: 总览
+
+3.0 在保持向后兼容的前提下统一了 API 形态、加强了类型约束、把投影管理抽成独立类。所有 2.x 用户都应**配合 [`docs/MIGRATION-3.0.md`](./docs/MIGRATION-3.0.md) 阅读升级**。
+
+升级核心结论：
+
+- 真实图层类 `add*` 返回值从原始 OpenLayers layer 改为统一 `LayerHandle`
+- 所有公开 `add*` 方法签名上 `layerName` 现在是**必填**（编译时强制）
+- `addPointByUrl` / `addLineByUrl` / `addPolygonByUrl` 统一异步返回完整 Handle
+
+### ✨ Features
+
+- **handle**：新增统一 [`LayerHandle`](./src/types/handle.ts)、`AnimatedLayerHandle` 与 `ControlHandle` 接口；真实图层 add* 返回 `{ layer, remove, setVisible }`，非图层点位返回 `{ target, remove, setVisible }`。
+- **add\***：Point / Line / Polygon 的真实图层 add 方法统一返回 `LayerHandle`；`PulsePointLayerHandle`、`FlowLineLayerHandle` 显式继承动画句柄契约。
+- **\*ByUrl**：`Point.addPointByUrl`、`Line.addLineByUrl`、`Polygon.addPolygonByUrl` 统一先获取 JSON，再调用对应 add 方法并返回 Promise Handle。
+- **Point \*ByUrl**：新增 `Point.addPointByUrl` / `Point.addPulsePointLayerByUrl`，从 URL 直接异步加载点位数据。
+- **ProjectionManager**：投影注册逻辑从 `MyOl` 抽到独立 [`ProjectionManager`](./src/core/projection/ProjectionManager.ts) 类，对外暴露 `register / initialize / resolveViewProjection`。用户现在可在 MyOl 实例之外注册任意 EPSG。
+- **ConfigManager.setDefaults**：运行时修改全局默认配置（如线宽、闪烁颜色），所有未提供该字段的后续调用都生效。配 `resetDefaults` 恢复。
+- **错误体系**：新增 `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError` 三个具体子类，方便调用方 `instanceof` 判别。
+- **类型导出**：补齐 `TwinkleItem` / `VueTemplatePointInstance` / `MeasureHandlerType` 等遗漏类型；运行时枚举 `VueTemplatePointState` 也导出。
+
+### 🐛 Bug Fixes
+
+- **destroy 泄漏（P0-1）**：`MyOl.destroy()` 现在会级联调用 `SelectHandler.destroy / Line.destroyAllFlowLines / Point.destroyAll / Polygon.destroyAll`，确保所有 rAF / Overlay / Vue 实例 / Select interaction 释放。
+- **Point/Polygon 句柄注册表**：`Point` / `Polygon` 内部新增 `managedLayers` / `managedDisposables` 注册表，所有 `add*` 都会登记；`destroyAll` 一次性回收。
+- **VueTemplatePoint 实例复用**：`Point.addVueTemplatePoint` 之前每次调用都 `new VueTemplatePoint(map)` 丢弃引用，现在改为单例复用并随 `destroyAll` 一起清理。
+- **Polygon `[key:string]:any` 删除**：`removePolygonLayer` 不再依赖动态属性赋值。
+
+### 🔒 Hardening
+
+- 公开 `add*` 方法签名上 `layerName` 变成必填（用 `Options & { layerName: string }` 形式），不动 interface 本身保证 2.x 用户的 options 对象赋值不报错。
+- `MapTools.setMapClip` 的 `baseLayer` 类型从 `any` 收紧为 `BaseLayer`；坐标数组从 `any[]` 收紧为 `number[][]` / `number[][][]`。
+- `PulsePointIconOptions.src` 标 `@deprecated`，统一改名为 `img`（PointPulseLayer 同时识别两者）。
+
+### 📝 Documentation
+
+- 新增 [`docs/MIGRATION-3.0.md`](./docs/MIGRATION-3.0.md) 迁移指南。
+- `addPolygonByUrl` / `addLineByUrl` / `Point.addVueTemplatePoint` 等破坏性返回值变化已写入迁移指南。
+
+### 🧪 Tests
+
+- 新增 5 个测试文件，共 40 个用例：`destroy-leak`、`config-defaults`、`async-url-api`、`layer-handle`、`config-defaults`，覆盖 P0/P1/P2 所有改动点。
+
+---
+
+## [2.5.5] - Unreleased（P0 补丁版）
+
+### 🐛 Bug Fixes (P0)
+
+- **destroy 级联清理**：`MyOl.destroy()` 现在会依次调用 `SelectHandler.destroy / Line.destroyAllFlowLines / Point.destroyAll / Polygon.destroyAll / EventManager.clear`，每一步独立 try/catch，确保所有 RAF、Overlay、Vue app、Select interaction 真正释放。
+- **Point/Polygon 句柄注册表**：`Point.addPoint / addClusterPoint / addPulsePointLayer / addDomPoint / addVueTemplatePoint` 与 `Polygon.addPolygon / addBorderPolygon / addImageLayer / addHeatmap / addMaskLayer / setOutLayer` 创建的图层都注册到内部表，便于 `destroyAll()` 一次性回收。
+- **VueTemplatePoint 实例复用**：`Point.addVueTemplatePoint` 之前每次都 `new VueTemplatePoint(map)` 丢弃引用导致内存泄漏，现改为单例复用。
+- **死代码清理**：删除 `Point.ts` 注释段（旧 `addTwinkleLayerFromPolygon` 实现）；删除 `Polygon` 的 `[key:string]:any` 索引签名，重写 `removePolygonLayer`。
+
+### 🔒 Hardening (P0)
+
+- `MapTools.setMapClip` 的 `baseLayer` 类型从 `any` 收紧到 `BaseLayer`；坐标数组从 `any[]` 收紧为 `number[][]` / `number[][][]`。
+
+### ✨ Type Exports (P0)
+
+- 补齐 `TwinkleItem` / `VueTemplatePointInstance` / `MeasureHandlerType` 等遗漏类型；导出运行时枚举 `VueTemplatePointState`。
+
+### 🧪 Tests (P0)
+
+- 新增 `tests/destroy-leak.test.ts`，4 个用例覆盖 `Line.destroyAllFlowLines` / `Point.destroyAll` / `Polygon.destroyAll` / `removePolygonLayer`。
+
 ## [2.5.4] - 2026-05-18
 
 ### 🐛 Bug Fixes

package/MyOl.d.ts

@@ -24,9 +24,10 @@ export default class MyOl {
     private readonly configManager;
     private readonly options;
     static readonly DefaultOptions: MapInitType;
+    /**
+     * @deprecated 请使用 ProjectionManager.PROJECTIONS 代替
+     */
     private static readonly PROJECTIONS;
-    /** *********************内置投影定义*********************/
-    private static readonly PROJECTION_DEFINITIONS;
     /**
      * 构造函数
      * @param id 地图容器 DOM 元素 ID
@@ -38,21 +39,6 @@ export default class MyOl {
      * @private
      */
     private validateConstructorParams;
-    /**
-     * 初始化坐标系
-     * @private
-     */
-    private static initializeProjections;
-    /**
-     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
-     * @private
-     */
-    private static ensureProj4Definition;
-    /**
-     * 应用用户显式提供的投影元数据。
-     * @private
-     */
-    private static applyCustomProjectionMetadata;
     /**
      * 创建地图控件
      * @private
@@ -69,11 +55,6 @@ export default class MyOl {
      * @returns View 地图视图实例
      */
     static createView(options?: MapInitType): View;
-    /**
-     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
-     * @private
-     */
-    private static resolveViewProjection;
     /**
      * 获取视图（向后兼容）
      * @deprecated 请使用 createView 方法

package/MyOl.js

@@ -1,17 +1,16 @@
 "use strict";
 // OpenLayers 核心导入
-import { register as olProj4Register } from 'ol/proj/proj4';
-import { Projection as olProjProjection, addProjection as olProjAddProjection, fromLonLat as olProjFromLonLat, get as olProjGetProjection } from 'ol/proj';
 import View from "ol/View";
 import Map from "ol/Map";
 import { defaults as defaultControls } from 'ol/control';
-import proj4 from "proj4";
+import { fromLonLat as olProjFromLonLat } from 'ol/proj';
 // 内部模块导入
 import { Polygon } from "./core/polygon";
 import { Point } from "./core/point";
 import { Line } from "./core/line";
 import { MapBaseLayers, MapTools, EventManager, ConfigManager } from "./core/map";
 import { SelectHandler } from "./core/select";
+import { ProjectionManager } from "./core/projection";
 import { ErrorHandler, MyOpenLayersError, ErrorType } from './utils/ErrorHandler';
 /**
  * MyOl 地图核心类
@@ -37,7 +36,7 @@ class MyOl {
             // 参数验证
             this.validateConstructorParams(id, this.options);
             // 初始化坐标系
-            MyOl.initializeProjections(this.options);
+            ProjectionManager.initialize(this.options);
             // 准备图层
             const layers = Array.isArray(this.options.layers) ? this.options.layers : [];
             // 创建地图实例
@@ -81,75 +80,6 @@ class MyOl {
             throw new Error(typeof id === 'string' ? `找不到 ID 为 '${id}' 的 DOM 元素` : '提供的 DOM 元素无效');
         }
     }
-    /**
-     * 初始化坐标系
-     * @private
-     */
-    static initializeProjections(options) {
-        /** *********************投影定义初始化*********************/
-        MyOl.ensureProj4Definition(MyOl.PROJECTIONS.WGS84, MyOl.PROJECTION_DEFINITIONS[MyOl.PROJECTIONS.WGS84]);
-        MyOl.ensureProj4Definition(MyOl.PROJECTIONS.CGCS2000, MyOl.PROJECTION_DEFINITIONS[MyOl.PROJECTIONS.CGCS2000]);
-        MyOl.ensureProj4Definition(MyOl.PROJECTIONS.CGCS2000_3_DEGREE, MyOl.PROJECTION_DEFINITIONS[MyOl.PROJECTIONS.CGCS2000_3_DEGREE]);
-        if (options.projection?.code && options.projection.def) {
-            proj4.defs(options.projection.code, options.projection.def);
-        }
-        // 注册到 OpenLayers
-        olProj4Register(proj4);
-        // 添加 CGCS2000 投影
-        const cgsc2000 = new olProjProjection({
-            code: MyOl.PROJECTIONS.CGCS2000,
-            extent: [-180, -90, 180, 90],
-            worldExtent: [-180, -90, 180, 90],
-            units: "degrees"
-        });
-        olProjAddProjection(cgsc2000);
-        if (options.projection?.code) {
-            MyOl.applyCustomProjectionMetadata(options.projection);
-        }
-    }
-    /**
-     * 缺失时注册 proj4 投影定义，避免生产构建依赖第三方模块默认副作用。
-     * @private
-     */
-    static ensureProj4Definition(code, definition) {
-        if (!proj4.defs(code)) {
-            proj4.defs(code, definition);
-        }
-    }
-    /**
-     * 应用用户显式提供的投影元数据。
-     * @private
-     */
-    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
-            }));
-        }
-    }
     /**
      * 创建地图控件
      * @private
@@ -184,9 +114,9 @@ class MyOl {
     static createView(options = MyOl.DefaultOptions) {
         try {
             /** *********************静态视图投影初始化*********************/
-            MyOl.initializeProjections(options);
-            const code = options.projection?.code ?? MyOl.PROJECTIONS.CGCS2000;
-            const projection = MyOl.resolveViewProjection(options, code);
+            ProjectionManager.initialize(options);
+            const code = options.projection?.code ?? ProjectionManager.DEFAULT_PROJECTION;
+            const projection = ProjectionManager.resolveViewProjection(options, code);
             const viewOptions = {
                 projection,
                 center: olProjFromLonLat(options.center, projection),
@@ -201,26 +131,6 @@ class MyOl {
             throw new MyOpenLayersError(`视图创建失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { options });
         }
     }
-    /**
-     * 解析视图投影，优先复用已注册投影，避免丢失 proj4 推导的单位信息。
-     * @private
-     */
-    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"
-        });
-    }
     /**
      * 获取视图（向后兼容）
      * @deprecated 请使用 createView 方法
@@ -503,16 +413,8 @@ class MyOl {
 }
 // 默认配置
 MyOl.DefaultOptions = ConfigManager.DEFAULT_MYOL_OPTIONS;
-// 坐标系配置
-MyOl.PROJECTIONS = {
-    WGS84: "EPSG:4326",
-    CGCS2000: "EPSG:4490",
-    CGCS2000_3_DEGREE: "EPSG:4549"
-};
-/** *********************内置投影定义*********************/
-MyOl.PROJECTION_DEFINITIONS = {
-    [MyOl.PROJECTIONS.WGS84]: "+title=WGS 84 (long/lat) +proj=longlat +ellps=WGS84 +datum=WGS84 +units=degrees",
-    [MyOl.PROJECTIONS.CGCS2000]: "+proj=longlat +ellps=GRS80 +no_defs",
-    [MyOl.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"
-};
+/**
+ * @deprecated 请使用 ProjectionManager.PROJECTIONS 代替
+ */
+MyOl.PROJECTIONS = ProjectionManager.PROJECTIONS;
 export default MyOl;

package/README.md

@@ -6,6 +6,26 @@ my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+**[在线 Demo](https://cuteyuchen.github.io/my-openlayer/demo/)** · [文档](https://cuteyuchen.github.io/my-openlayer/) · [迁移指南 (2.x → 3.0)](docs/MIGRATION-3.0.md)
+
+---
+
+## 3.0 亮点
+
+3.0 是一次 API 形态层的范式转移，核心目标是**统一 lifecycle、降低学习成本**：
+
+- **统一 LayerHandle** — 真实图层类 `add*` 返回 `{ layer, remove(), setVisible() }` 形态的句柄，跨 Point / Line / Polygon 复用同一套 lifecycle 模型
+- **统一 ControlHandle** — `addDomPoint` / `addVueTemplatePoint` 返回 `{ target, remove(), setVisible() }`，并保留 `anchors` / `getPoints()` 等原有能力
+- ***ByUrl 异步化** — `addPointByUrl` / `addLineByUrl` / `addPolygonByUrl` 统一先获取 JSON，再返回完整 Handle
+- **destroy 级联清理** — `MyOl.destroy()` 现在依次调用 `SelectHandler.destroy` / `Line.destroyAllFlowLines` / `Point.destroyAll` / `Polygon.destroyAll`，确保 rAF / Overlay / Vue 实例 / Select interaction 全部释放
+- **ProjectionManager** — 投影逻辑从 MyOl 内部抽取为独立类，支持 `ProjectionManager.register({ code, def })` 在 MyOl 实例之外注册任意 EPSG
+- **ConfigManager.setDefaults** — 运行时修改全局默认配置，所有未提供该字段的后续调用都生效
+- **具体错误类型** — `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError`，方便 `instanceof` 判别
+- **layerName 必填** — 公开 `add*` 方法签名上 `layerName` 变成必填（编译时强制）
+- **PulsePointIconOptions `src` → `img`** — 统一命名，旧 `src` 标 `@deprecated`
+
+> 从 2.x 升级请参考 [MIGRATION-3.0.md](docs/MIGRATION-3.0.md)。3.0 会把旧 `add*` 的原始 layer 返回值改为 Handle；访问 OL 图层请使用 `handle.layer`。
+
 ---
 
 ## 项目概述
@@ -27,19 +47,18 @@ my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地
   - **线要素绘制 (Line)**：支持静态线、流光线、流动线图标动画，详见 [Line 动画文档](docs/Line.md#流动线--动态图标线)
   - **面要素 (Polygon)**：面要素绘制、分区高亮、遮罩层
   - **Vue组件支持 (VueTemplatePoint)**：支持将 Vue 组件作为地图点位渲染
-  - **河流图层 (RiverLayerManager)**：支持分级显示的河流图层管理
 
 - **🛠️ 地图工具**
   - **测量工具 (MeasureHandler)**：距离和面积测量
   - **要素选择 (SelectHandler)**：支持点击、悬停、多选等交互选择
-  - **地图工具 (MapTools)**：图层管理、定位、视图自适应
+  - **地图工具 (MapTools)**：图层管理、定位、视图自适应、全图裁剪 (`clipMap`)
   - **事件管理 (EventManager)**：统一的地图事件监听与管理
 
 - **⚡ 高级特性**
-  - **TypeScript 完全支持**：提供完整的类型定义
-  - **错误处理 (ErrorHandler)**：统一的错误捕获与日志
-  - **配置管理 (ConfigManager)**：集中管理默认配置
-  - **坐标系支持**：内置 `EPSG:4326`、`EPSG:4490`、`EPSG:4549`，支持基于 `proj4.def` 的自定义投影注册
+  - **TypeScript 完全支持**：提供完整的类型定义，严格模式
+  - **错误处理 (ErrorHandler)**：统一的错误捕获与日志，含具体子类型
+  - **配置管理 (ConfigManager)**：集中管理默认配置，支持运行时 `setDefaults`
+  - **投影管理 (ProjectionManager)**：内置 `EPSG:4326` / `EPSG:4490` / `EPSG:4549`，支持 `ProjectionManager.register()` 注册任意自定义投影
 
 ## 安装
 
@@ -58,36 +77,52 @@ pnpm add my-openlayer
 - **proj4**: ^2.7.5
 - **@turf/turf**: ^7.2.0
 
+## CC Switch 技能仓库
+
+本仓库已按 CC Switch 技能仓库结构提供 `my-openlayer-helper`：
+
+```txt
+skills/my-openlayer-helper/SKILL.md
+```
+
+在 CC Switch 的“添加技能仓库”中填写：
+
+```txt
+仓库 URL：cuteyuchen/my-openlayer
+分支：main
+```
+
+CC Switch 扫描后会识别到 `my-openlayer-helper`。后续更新只需要同步本仓库，使用者在 CC Switch 中刷新/更新技能即可。
+
 ## 快速上手
 
 ### 1. 初始化地图
 
 ```typescript
-import MyOl, { MapInitType } from 'my-openlayer';
+import { MyOl } from 'my-openlayer';
 
-const mapConfig: MapInitType = {
+const map = new MyOl('map-container', {
   center: [119.81, 29.969],
   zoom: 10,
   token: import.meta.env.VITE_TIANDITU_TOKEN, // 天地图 Token
   annotation: true
-};
-
-const map = new MyOl('map-container', mapConfig);
+});
 ```
 
 ### 2. 使用功能模块
 
 ```typescript
-// 获取模块实例
+// 获取模块实例（懒加载）
 const point = map.getPoint();
 const line = map.getLine();
 const polygon = map.getPolygon();
 
-// 添加点位
-point.addPoint([{ lgtd: 119.81, lttd: 29.969, name: '示例点' }], {
-  layerName: 'example-point',
-  img: 'marker.png'
-});
+// 添加点位（3.0 add* 返回统一 LayerHandle）
+const handle = point.addPoint(
+  [{ lgtd: 119.81, lttd: 29.969, name: '示例点' }],
+  { layerName: 'example-point', img: 'marker.png' }
+);
+handle?.remove(); // 统一的生命周期管理
 ```
 
 ### 3. 添加高性能闪烁点
@@ -127,20 +162,15 @@ pulseLayer?.remove();
 
 ### 4. 添加流动线
 
-`Line` 模块现在支持流光线与流动线图标动画，调用方式与 `Point.addPulsePointLayer()` 保持一致，返回可控 handle。
-
 ```typescript
 const flow = map.getLine().addFlowLine(lineData, {
   layerName: 'river-flow',
   animationMode: 'icon+dash',
   strokeColor: '#19b1ff',
   strokeWidth: 3,
-  lineDash: [18, 12],
   flowSymbol: {
     src: '/symbols/boat.svg',
     scale: 0.9,
-    color: '#19b1ff',
-    rotateWithView: true,
     count: 2,
     spacing: 0.2
   }
@@ -151,28 +181,69 @@ flow?.resume();
 flow?.remove();
 ```
 
+### 5. 全图裁剪
+
+```typescript
+const tools = map.getTools();
+
+// 裁剪整张地图（底图 + 注记 + 用户图层全部只在区域内可见）
+tools.clipMap(geoJsonBoundary);
+
+// 或只裁剪当前底图
+const baseLayers = map.getMapBaseLayers().getCurrentBaseLayers();
+baseLayers.forEach(layer => MapTools.setMapClip(layer, geoJsonBoundary));
+```
+
+### 6. 注册自定义投影
+
+```typescript
+import { ProjectionManager } from 'my-openlayer';
+
+// 在 MyOl 实例之外注册任意 EPSG
+ProjectionManager.register({
+  code: 'EPSG:4528',
+  def: '+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=40500000 +y_0=0 +ellps=GRS80 +units=m +no_defs'
+});
+
+// 之后 MyOl 构造时直接用
+const map = new MyOl('map', { projection: { code: 'EPSG:4528' } });
+```
+
+### 7. 运行时修改默认配置
+
+```typescript
+import { ConfigManager } from 'my-openlayer';
+
+// 所有后续 addLine 调用的默认 strokeWidth 变为 4
+ConfigManager.setDefaults('LINE_OPTIONS', { strokeWidth: 4 });
+
+// 恢复内置默认
+ConfigManager.resetDefaults('LINE_OPTIONS');
+```
+
 ## 文档索引
 
-为了提供更详细的说明，我们将文档拆分为独立的模块文件：
+详细文档请访问 **[在线文档](https://cuteyuchen.github.io/my-openlayer/)**，交互式 Demo 请访问 **[Demo 站点](https://cuteyuchen.github.io/my-openlayer/demo/)**。
 
 ### 核心类库
 - **[MyOl](docs/MyOl.md)**: 地图入口类，负责初始化和模块访问。
+- **[ProjectionManager](docs/ProjectionManager.md)**: 投影管理（3.0 新增），支持 `register()` 注册任意 EPSG。
 - **[MapBaseLayers](docs/MapBaseLayers.md)**: 底图与注记管理。
-- **[ConfigManager](docs/ConfigManager.md)**: 配置管理。
+- **[ConfigManager](docs/ConfigManager.md)**: 配置管理，支持运行时 `setDefaults`。
 - **[EventManager](docs/EventManager.md)**: 事件管理。
-- **[ErrorHandler](docs/ErrorHandler.md)**: 错误处理。
+- **[ErrorHandler](docs/ErrorHandler.md)**: 错误处理，含 `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError`。
 
 ### 要素操作
-- **[Point](docs/Point.md)**: 点要素（含聚合、DOM 点位、高性能闪烁点）。
-- **[Line](docs/Line.md)**: 线要素。
-- **[Polygon](docs/Polygon.md)**: 面要素（含热力图、图片层）。
+- **[Point](docs/Point.md)**: 点要素（含聚合、DOM 点位、高性能闪烁点、统一 Handle）。
+- **[Point](docs/Point.md)**: 点要素（含聚合、DOM 点位、高性能闪烁点、统一 Handle）。
+- **[Line](docs/Line.md)**: 线要素（含静态线、流动线、URL 异步加载）。
+- **[Polygon](docs/Polygon.md)**: 面要素（含热力图、图片层、遮罩层、统一 Handle）。
 - **[VueTemplatePoint](docs/VueTemplatePoint.md)**: Vue 组件点位。
-- **[RiverLayerManager](docs/RiverLayerManager.md)**: 河流图层管理。
 
 ### 交互与工具
 - **[SelectHandler](docs/SelectHandler.md)**: 要素选择交互（支持独立样式渲染、多选隔离）。
 - **[MeasureHandler](docs/MeasureHandler.md)**: 测量工具。
-- **[MapTools](docs/MapTools.md)**: 通用地图工具。
+- **[MapTools](docs/MapTools.md)**: 通用地图工具（含 `clipMap` 全图裁剪）。
 - **[ValidationUtils](docs/ValidationUtils.md)**: 验证工具。
 
 ## 详细用法示例
@@ -196,7 +267,21 @@ measure.start('LineString'); // 开始测距
 measure.end(); // 结束测量
 ```
 
-> 注意：部分高级功能（如 SelectHandler）可以通过 `map.getSelectHandler()` 访问。
+### 要素选择
+
+```typescript
+const selectHandler = map.getSelectHandler();
+
+selectHandler.enableSelect('click', {
+  layerFilter: ['cities'],
+  onSelect: (event) => console.log('选中:', event.selected)
+});
+
+// 编程式选择
+selectHandler.selectByProperty('name', '杭州', { fitView: true });
+```
+
+> 注意：更多示例请访问 [Demo 站点](https://cuteyuchen.github.io/my-openlayer/demo/)，每个公开类都有独立的交互式演示页。
 
 ## 贡献指南
 

package/core/line/Line.d.ts

@@ -1,7 +1,7 @@
 import Map from "ol/Map";
 import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
-import type { FlowLineLayerHandle, FlowLineOptions, LineOptions, MapJSONData } from "../../types";
+import type { FlowLineLayerHandle, FlowLineOptions, LineOptions, MapJSONData, LayerHandle } from "../../types";
 /**
  * 线要素管理类
  * 用于在地图上添加和管理静态线与流动线要素。
@@ -23,6 +23,8 @@ export default class Line {
      * 创建静态线图层。
      */
     private createStaticLayer;
+    /** *********************统一句柄：静态线图层*********************/
+    private toLayerHandle;
     /**
      * 注册流动线句柄。
      */
@@ -31,11 +33,23 @@ export default class Line {
      * 注销流动线句柄。
      */
     private unregisterFlowLineHandle;
-    addLine(data: MapJSONData, options?: LineOptions): VectorLayer<VectorSource>;
-    addLineByUrl(url: string, options?: LineOptions): VectorLayer<VectorSource>;
+    /** *********************创建静态线图层*********************/
+    private createLineLayer;
+    /** *********************添加静态线图层*********************/
+    addLine(data: MapJSONData, options: LineOptions & {
+        layerName: string;
+    }): LayerHandle<VectorLayer<VectorSource>>;
+    /** *********************从 URL 添加静态线图层*********************/
+    addLineByUrl(url: string, options: LineOptions & {
+        layerName: string;
+    }): Promise<LayerHandle<VectorLayer<VectorSource>>>;
     removeLineLayer(layerName: string): void;
-    addFlowLine(data: MapJSONData, options?: FlowLineOptions): FlowLineLayerHandle | null;
-    addFlowLineByUrl(url: string, options?: FlowLineOptions): Promise<FlowLineLayerHandle | null>;
+    addFlowLine(data: MapJSONData, options: FlowLineOptions & {
+        layerName: string;
+    }): FlowLineLayerHandle | null;
+    addFlowLineByUrl(url: string, options: FlowLineOptions & {
+        layerName: string;
+    }): Promise<FlowLineLayerHandle | null>;
     removeFlowLineLayer(layerName: string): void;
     /**
      * 销毁本实例创建的所有流动线动画。供 MyOl.destroy 调用，

package/core/line/Line.js

@@ -61,6 +61,15 @@ export default class Line {
         this.map.addLayer(layer);
         return layer;
     }
+    /** *********************统一句柄：静态线图层*********************/
+    toLayerHandle(layer) {
+        const map = this.map;
+        return {
+            layer,
+            setVisible(visible) { layer.setVisible(visible); },
+            remove() { map.removeLayer(layer); }
+        };
+    }
     /**
      * 注册流动线句柄。
      */
@@ -73,26 +82,32 @@ export default class Line {
     unregisterFlowLineHandle(layerName) {
         this.flowLineRegistry.delete(layerName);
     }
-    addLine(data, options) {
+    /** *********************创建静态线图层*********************/
+    createLineLayer(data, options) {
         ValidationUtils.validateRequired(data, 'GeoJSON data is required');
         const mergedOptions = this.mergeDefaultOptions(options);
         const features = new GeoJSON().readFeatures(data, ProjectionUtils.getGeoJSONReadOptions(mergedOptions));
         return this.createStaticLayer(new VectorSource({ features }), mergedOptions);
     }
-    addLineByUrl(url, options = {}) {
+    /** *********************添加静态线图层*********************/
+    addLine(data, options) {
+        return this.toLayerHandle(this.createLineLayer(data, options));
+    }
+    /** *********************从 URL 添加静态线图层*********************/
+    async addLineByUrl(url, options) {
         ValidationUtils.validateNonEmptyString(url, 'Line url is required');
-        const mergedOptions = this.mergeDefaultOptions(options);
-        const source = new VectorSource({
-            url,
-            format: new GeoJSON(ProjectionUtils.getGeoJSONReadOptions(mergedOptions))
-        });
-        return this.createStaticLayer(source, mergedOptions);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch line GeoJSON: ${response.status}`);
+        }
+        const json = await response.json();
+        return this.addLine(json, options);
     }
     removeLineLayer(layerName) {
         ValidationUtils.validateLayerName(layerName);
         MapTools.removeLayer(this.map, layerName);
     }
-    addFlowLine(data, options = {}) {
+    addFlowLine(data, options) {
         const mergedOptions = this.mergeFlowLineOptions(options);
         const layerName = mergedOptions.layerName;
         try {
@@ -113,7 +128,7 @@ export default class Line {
             return null;
         }
     }
-    async addFlowLineByUrl(url, options = {}) {
+    async addFlowLineByUrl(url, options) {
         const mergedOptions = this.mergeFlowLineOptions(options);
         try {
             ValidationUtils.validateNonEmptyString(url, 'Flow line url is required');

package/core/line/index.d.ts

@@ -2,5 +2,3 @@ export { default as Line } from './Line';
 export { default as LineFlowAnimator } from './LineFlowAnimator';
 export { default as LineFeatureFactory } from './LineFeatureFactory';
 export { default as LineStyleFactory } from './LineStyleFactory';
-export { default as RiverLayerManager } from './RiverLayerManager';
-export type { RiverLayerOptions, RiverLevelWidthMap } from './RiverLayerManager';

package/core/line/index.js

@@ -2,4 +2,3 @@ export { default as Line } from './Line';
 export { default as LineFlowAnimator } from './LineFlowAnimator';
 export { default as LineFeatureFactory } from './LineFeatureFactory';
 export { default as LineStyleFactory } from './LineStyleFactory';
-export { default as RiverLayerManager } from './RiverLayerManager';