my-openlayer 2.4.7 → 2.4.9

package/docs/RiverLayerManager.md

@@ -1,59 +1,187 @@
-# RiverLayerManager 河流图层管理类
-
-`RiverLayerManager` 专门用于处理河流数据的分级显示和样式管理。
-
-## 方法
-
-### 分级显示 (Zoom-based)
-
-根据地图缩放级别自动显示不同等级的河流。
-
-- **addRiverLayersByZoom(fyRiverJson: MapJSONData, options?: RiverLayerOptions)**: 添加分级河流图层。
-  - `options.levelCount`: 河流等级总数。
-  - `options.zoomOffset`: 缩放级别偏移量，控制何时显示哪一级。
-- **addRiverLayersByZoomByUrl(url: string, options?)**: 从 URL 加载分级河流。
-- **showRiverLayer(show: boolean)**: 控制分级河流图层的总开关。
-
-### 宽度分级 (Level-based Width)
-
-根据河流等级属性渲染不同宽度的线条。
-
-- **addRiverWidthByLevel(data: MapJSONData, options?)**: 添加按等级设定宽度的河流。
-- **addRiverWidthByLevelByUrl(url: string, options?)**: 从 URL 加载。
-
-### 管理
-
-- **clearRiverLayers()**: 清除所有由该管理器创建的河流图层。
-- **getRiverLayerVisibility()**: 获取当前可见性状态。
-
-## 使用示例
-
-```typescript
-// 需要单独实例化，或扩展 MyOl
-import { RiverLayerManager } from 'my-openlayer';
-
-const riverManager = new RiverLayerManager(map.map);
-
-// 1. 添加分级河流（随缩放显示更多细节）
-riverManager.addRiverLayersByZoom(riverGeoJSON, {
-  layerName: 'main-river',
-  levelCount: 5, // 数据中包含 level 1-5
-  zoomOffset: 8, // level 1 在 zoom > 9 (1+8) 显示
-  strokeColor: '#0071FF',
-  strokeWidth: 2
-});
-
-// 2. 控制显隐
-riverManager.showRiverLayer(true);
-
-// 3. 添加按等级设定宽度的河流（静态显示）
-riverManager.addRiverWidthByLevel(riverGeoJSON, {
-  layerName: 'width-river',
-  strokeColor: '#0071FF',
-  levelWidthMap: {
-    1: 5, // 1级河流宽5px
-    2: 3,
-    3: 1
-  }
-});
-```
+# RiverLayerManager 河流图层管理类
+
+`RiverLayerManager` 专门用于处理河流数据的分级显示和样式管理。它支持基于地图缩放级别（Zoom-based）的动态分级显示，以及基于河流属性等级（Level-based）的固定线宽渲染。
+
+## 构造函数
+
+```typescript
+constructor(map: Map, eventManager?: EventManager)
+```
+
+- **参数**:
+  - `map` (Map): OpenLayers 地图实例。
+  - `eventManager` (EventManager): 可选。事件管理器实例，如果未提供则内部创建。
+
+## 接口定义
+
+### RiverLayerOptions
+
+河流图层配置选项，继承自 `LineOptions`。
+
+| 属性 | 类型 | 必填 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| levelCount | `number` | 否 | `5` | 河流等级总数。用于分级显示循环加载。 |
+| zoomOffset | `number` | 否 | `8` | 缩放级别偏移量。控制何时显示哪一级河流 (Zoom > Level + Offset)。 |
+| levelWidthMap | `RiverLevelWidthMap` | 否 | 默认映射 | 河流级别与线宽的映射对象。 |
+| removeExisting | `boolean` | 否 | `false` | 添加前是否删除由本管理器创建的旧图层。 |
+| layerName | `string` | 否 | - | 图层名称，用于标识和清理。 |
+| visible | `boolean` | 否 | `true` | 初始可见性。 |
+| strokeColor | `string` | 否 | - | 线条颜色。 |
+| strokeWidth | `number` | 否 | - | 基础线宽（如果未使用 levelWidthMap）。 |
+| zIndex | `number` | 否 | - | 图层 Z-Index。 |
+| projectionOptOptions | `any` | 否 | - | GeoJSON 读取时的投影选项。 |
+
+### RiverLevelWidthMap
+
+河流级别线宽映射接口。
+
+```typescript
+interface RiverLevelWidthMap {
+  [level: number]: number;
+}
+```
+
+默认映射 (`ConfigManager.DEFAULT_RIVER_LEVEL_WIDTH_MAP`) 通常为 `{1: 5, 2: 4, 3: 3, 4: 2, 5: 1}` 等类似结构。
+
+## 方法
+
+### 分级显示 (Zoom-based)
+
+根据地图缩放级别自动显示不同等级的河流。通常用于实现“缩放越大约详细”的效果。
+
+#### addRiverLayersByZoom
+
+直接传递 GeoJSON 数据添加分级河流图层。
+
+```typescript
+addRiverLayersByZoom(fyRiverJson: MapJSONData, options?: RiverLayerOptions): void
+```
+
+- **参数**:
+  - `fyRiverJson`: 河流 GeoJSON 数据对象。
+  - `options`: 配置选项。
+
+#### addRiverLayersByZoomByUrl
+
+通过 URL 加载 GeoJSON 数据并添加分级河流图层。
+
+```typescript
+addRiverLayersByZoomByUrl(url: string, options?: RiverLayerOptions): void
+```
+
+#### showRiverLayer
+
+控制分级河流图层的总开关。
+
+```typescript
+showRiverLayer(show: boolean): void
+```
+
+#### showRiverLayerByZoom
+
+手动触发根据当前缩放级别更新图层可见性（通常不需要手动调用，已绑定 `moveend` 事件）。
+
+```typescript
+showRiverLayerByZoom(): void
+```
+
+### 宽度分级 (Level-based Width)
+
+根据河流数据中的 `level` 属性渲染不同宽度的线条，通常用于静态展示不同等级河流的粗细差异。
+
+#### addRiverWidthByLevel
+
+直接传递 GeoJSON 数据添加按等级设定宽度的河流。
+
+```typescript
+addRiverWidthByLevel(data: MapJSONData, options?: RiverLayerOptions): VectorLayer<VectorSource>
+```
+
+- **返回值**: 创建的矢量图层。
+
+#### addRiverWidthByLevelByUrl
+
+通过 URL 加载 GeoJSON 数据并添加按等级设定宽度的河流。
+
+```typescript
+addRiverWidthByLevelByUrl(url: string, options?: RiverLayerOptions): VectorLayer<VectorSource>
+```
+
+### 管理与清理
+
+#### clearRiverLayers
+
+清除所有由该管理器创建的分级河流图层。
+
+```typescript
+clearRiverLayers(): void
+```
+
+#### getRiverLayerVisibility
+
+获取当前分级河流图层的总显示状态。
+
+```typescript
+getRiverLayerVisibility(): boolean
+```
+
+#### getRiverLayers
+
+获取当前管理的所有分级河流图层列表。
+
+```typescript
+getRiverLayers(): VectorLayer<VectorSource>[]
+```
+
+#### destroy
+
+销毁管理器，清理所有图层和事件监听。
+
+```typescript
+destroy(): void
+```
+
+## 使用示例
+
+```typescript
+import { MyOl, RiverLayerManager } from 'my-openlayer';
+
+const map = new MyOl('map-container');
+const riverManager = new RiverLayerManager(map.map);
+
+// 假设 riverGeoJSON 数据中每个 feature 都有 properties.level (1-5)
+
+// 示例 1: 添加分级河流（随地图缩放自动显隐不同级别的河流）
+// Level 1 在 Zoom > 9 (1+8) 显示
+// Level 2 在 Zoom > 10 (2+8) 显示
+// ...
+riverManager.addRiverLayersByZoom(riverGeoJSON, {
+  layerName: 'dynamic-river',
+  levelCount: 5, 
+  zoomOffset: 8, 
+  strokeColor: '#0071FF',
+  strokeWidth: 2,
+  removeExisting: true
+});
+
+// 控制分级河流的总开关
+riverManager.showRiverLayer(false); // 全部隐藏
+riverManager.showRiverLayer(true);  // 恢复并根据当前 Zoom 显示对应级别
+
+// 示例 2: 添加静态河流，根据等级显示不同粗细
+riverManager.addRiverWidthByLevel(riverGeoJSON, {
+  layerName: 'static-river',
+  strokeColor: '#0071FF',
+  levelWidthMap: {
+    1: 6, // 1级河流宽 6px
+    2: 5,
+    3: 4,
+    4: 3,
+    5: 1
+  },
+  zIndex: 10
+});
+
+// 清理资源
+// riverManager.destroy();
+```

package/docs/SelectHandler.md

@@ -1,126 +1,147 @@
-# SelectHandler 要素选择类
-
-`SelectHandler` 负责地图要素的交互选择，支持点击、悬停等多种模式，以及编程式选择。
-
-## 核心特性
-
-- **独立渲染机制**：采用独立的 Select 实例渲染选中要素，确保样式完全隔离，互不干扰。
-- **静态样式固化**：在选中瞬间计算并固化样式，支持基于原始样式的复杂计算（如 `feature.getStyle()`），彻底避免递归调用风险。
-- **多选隔离**：支持不同要素同时应用完全不同的高亮样式。
-- **自动清理**：自动管理渲染实例的生命周期，防止内存泄漏。
-
-## 方法
-
-### 交互选择
-
-- **enableSelect(mode: SelectMode, options?: SelectOptions)**: 启用选择交互。
-  - `mode`: `'click'` (点击), `'hover'` (悬停), `'ctrl'` (Ctrl+点击)。
-  - `options`:
-    - `multi`: 是否允许多选。
-    - `layerFilter`: 图层过滤器（图层名称数组）。
-    - `onSelect`: 选中回调。
-    - `onDeselect`: 取消选中回调。
-    - `selectStyle`: 选中时的样式。支持 `Style` 对象、数组或函数 `(feature, resolution) => Style`。**推荐使用函数**以实现基于原始样式的动态高亮。
-
-- **disableSelect()**: 禁用选择交互（停止响应用户操作，并清理交互式高亮）。
-- **isSelectEnabled()**: 检查是否已启用。
-
-### 编程式选择
-
-- **selectByIds(featureIds: string[], options?)**: 根据 ID 选中要素。
-- **selectByProperty(propertyName: string, propertyValue: any, options?)**: 根据属性值选中要素。
-- **clearSelection()**: 清除当前所有选中状态（包括交互式和编程式）。
-- **getSelectedFeatures()**: 获取当前选中的要素列表（仅包含交互式选择的要素）。
-
-## 使用示例
-
-### 1. 基础用法
-
-```typescript
-const selectHandler = map.getSelectHandler();
-
-// 启用点击选择
-selectHandler.enableSelect('click', {
-  multi: false, // 单选
-  layerFilter: ['target-layer'], // 仅选择特定图层的要素
-  onSelect: (event) => {
-    const feature = event.selected[0];
-    console.log('选中要素:', feature.getProperties());
-  },
-  onDeselect: (event) => {
-    console.log('取消选中:', event.deselected);
-  },
-  // 自定义选中样式（简单对象）
-  selectStyle: new Style({
-    image: new Circle({
-      radius: 8,
-      fill: new Fill({ color: 'red' }),
-      stroke: new Stroke({ color: 'white', width: 2 })
-    })
-  })
-});
-```
-
-### 2. 高级用法：基于原始样式的动态高亮
-
-利用函数式 `selectStyle`，可以在选中时动态获取要素的原始样式，并在此基础上修改（例如只改边框颜色，保留填充）。由于采用了**样式固化**机制，这种写法是安全的。
-
-```typescript
-selectHandler.enableSelect('click', {
-  selectStyle: (feature, resolution) => {
-    // 获取要素的原始样式
-    // 注意：feature.getStyle() 可能返回 Style 对象、数组或函数，需要自行处理归一化
-    const originStyleLike = feature.getStyle(); 
-    let originStyle = originStyleLike;
-    
-    // 如果原始样式是函数，执行它获取 Style 对象
-    if (typeof originStyleLike === 'function') {
-      originStyle = originStyleLike(feature, resolution);
-    }
-    
-    // 归一化为数组
-    const styles = Array.isArray(originStyle) ? originStyle : [originStyle];
-    
-    // 克隆并修改样式（例如：将边框改为青色）
-    return styles.map(s => {
-      const clone = s.clone();
-      const stroke = clone.getStroke();
-      if (stroke) {
-        stroke.setColor('#00FFFF');
-        stroke.setWidth(3);
-      } else {
-        // 如果没有边框，添加一个
-        clone.setStroke(new Stroke({ color: '#00FFFF', width: 3 }));
-      }
-      return clone;
-    });
-  }
-});
-```
-
-### 3. 编程式选择（带独立样式）
-
-编程式选择支持传入特定的样式，该样式将独立于主交互样式生效，且支持多要素使用不同样式。
-
-```typescript
-// 选中 ID 为 'feature-1' 的要素，并用红色高亮
-selectHandler.selectByIds(['feature-1'], {
-  selectStyle: new Style({ stroke: new Stroke({ color: 'red', width: 4 }) }),
-  fitView: true // 自动定位
-});
-
-// 同时选中 ID 为 'feature-2' 的要素，但用蓝色高亮（互不冲突）
-selectHandler.selectByIds(['feature-2'], {
-  selectStyle: new Style({ stroke: new Stroke({ color: 'blue', width: 4 }) })
-});
-```
-
-### 4. 禁用与清理
-
-```typescript
-// 禁用用户交互（停止响应点击，但保留编程式高亮）
-selectHandler.disableSelect();
-
-// 清除所有选择（包括交互式和编程式的高亮）
-selectHandler.clearSelection();
-```
+# SelectHandler 类
+
+`SelectHandler` 类用于处理地图上的要素选择交互，支持点击、悬停、Ctrl+点击等多种模式，并支持编程式选择。
+
+## 构造函数
+
+```typescript
+constructor(map: Map)
+```
+
+- **map**: OpenLayers 地图实例。
+
+## 接口定义
+
+### SelectOptions
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| multi | `boolean` | 是否支持多选，默认 `false` |
+| layerFilter | `string[]` | 图层过滤器，指定可选择的图层名称列表 |
+| featureFilter | `(feature: FeatureLike) => boolean` | 要素过滤器函数 |
+| hitTolerance | `number` | 点击容差（像素），默认为 0 |
+| selectStyle | `Style \| Style[] \| ((feature: FeatureLike) => Style \| Style[])` | 选中要素的样式 |
+| onSelect | `(event: SelectCallbackEvent) => void` | 选中要素时的回调函数 |
+| onDeselect | `(event: SelectCallbackEvent) => void` | 取消选中要素时的回调函数 |
+
+### ProgrammaticSelectOptions
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| layerName | `string` | 图层名称，指定在哪个图层中选择要素 |
+| selectStyle | `Style \| Style[] \| ((feature: FeatureLike) => Style \| Style[])` | 自定义选中样式（仅作用于此次选择） |
+| fitView | `boolean` | 是否定位至选中要素，默认 `false` |
+| fitDuration | `number` | 定位动画持续时间（毫秒），默认 500 |
+| fitPadding | `number` | 定位时的边距（像素），默认 100 |
+
+### SelectMode
+
+```typescript
+type SelectMode = 'click' | 'hover' | 'ctrl';
+```
+
+## 方法
+
+### enableSelect
+
+启用要素选择。
+
+```typescript
+enableSelect(mode: SelectMode = 'click', options?: SelectOptions): this
+```
+
+- **mode**: 选择模式。
+- **options**: 配置选项。
+- **返回值**: `SelectHandler` 实例，支持链式调用。
+
+### disableSelect
+
+禁用要素选择。
+
+```typescript
+disableSelect(): this
+```
+
+- **返回值**: `SelectHandler` 实例。
+
+### clearSelection
+
+清除所有选择（包括交互式和编程式）。
+
+```typescript
+clearSelection(): this
+```
+
+- **返回值**: `SelectHandler` 实例。
+
+### selectByIds
+
+通过要素 ID 编程式选择要素。
+
+```typescript
+selectByIds(featureIds: string[], options?: ProgrammaticSelectOptions): this
+```
+
+- **featureIds**: 要素 ID 数组。
+- **options**: 编程式选择选项。
+- **返回值**: `SelectHandler` 实例。
+
+### selectByProperty
+
+通过属性编程式选择要素。
+
+```typescript
+selectByProperty(propertyName: string, propertyValue: any, options?: ProgrammaticSelectOptions): this
+```
+
+- **propertyName**: 属性名。
+- **propertyValue**: 属性值。
+- **options**: 编程式选择选项。
+- **返回值**: `SelectHandler` 实例。
+
+## 使用示例
+
+### 启用点击选择
+
+```typescript
+import { SelectHandler } from 'my-openlayers';
+
+const selectHandler = new SelectHandler(map);
+
+// 启用点击选择，仅针对 'cities' 图层
+selectHandler.enableSelect('click', {
+  layerFilter: ['cities'],
+  onSelect: (event) => {
+    console.log('Selected:', event.selected);
+  },
+  onDeselect: (event) => {
+    console.log('Deselected:', event.deselected);
+  }
+});
+```
+
+### 启用悬停高亮
+
+```typescript
+selectHandler.enableSelect('hover', {
+  selectStyle: new Style({
+    stroke: new Stroke({ color: 'yellow', width: 4 })
+  })
+});
+```
+
+### 编程式选择并定位
+
+```typescript
+// 选择 ID 为 'beijing' 的要素并自动定位
+selectHandler.selectByIds(['beijing'], {
+  fitView: true,
+  fitPadding: 50
+});
+```
+
+### 清除选择
+
+```typescript
+selectHandler.clearSelection();
+```

package/docs/ValidationUtils.md

@@ -1,38 +1,83 @@
-# ValidationUtils 验证工具类
-
-`ValidationUtils` 提供了一系列静态方法用于参数校验。
-
-## 方法
-
-- **isValidCoordinate(lng, lat)**: 检查坐标是否有效（数字且在范围内）。
-- **validateLngLat(lng, lat)**: 简化的经纬度检查。
-- **validateLayerName(name)**: 验证图层名称非空。
-- **validateGeoJSONData(data)**: 验证 GeoJSON 数据格式。
-- **isValidColor(color)**: 验证颜色字符串格式。
-- **validateVueParams(...)**: 验证 Vue 组件点位所需的参数。
-
-## 使用示例
-
-```typescript
-import { ValidationUtils } from 'my-openlayer';
-
-// 1. 验证坐标
-const lng = 120.1;
-const lat = 30.2;
-
-if (ValidationUtils.isValidCoordinate(lng, lat)) {
-  console.log('坐标有效');
-} else {
-  console.error('坐标无效');
-}
-
-// 2. 验证颜色
-if (ValidationUtils.isValidColor('#ff0000')) {
-  // ...
-}
-
-// 3. 验证 GeoJSON
-if (ValidationUtils.validateGeoJSONData(jsonData)) {
-  // 安全地加载数据
-}
-```
+# ValidationUtils 验证工具
+
+`ValidationUtils` 提供了一系列静态方法，用于验证地图操作中的各种参数和数据，确保数据的完整性和类型正确性。
+
+## 导入
+
+```typescript
+import { ValidationUtils } from 'my-openlayer';
+```
+
+## 静态方法
+
+### 坐标验证
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `isValidCoordinate(longitude, latitude)` | `longitude: number`<br>`latitude: number` | `boolean` | 验证经纬度坐标是否有效（数字且在合法范围内） |
+| `validateCoordinate(longitude, latitude)` | `longitude: number`<br>`latitude: number` | `void` | 验证经纬度，无效时抛出异常 |
+
+### 数据验证
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `validatePointData(pointData)` | `pointData: any[]` | `boolean` | 验证点位数据数组是否有效 |
+| `validateOptions(options)` | `options: any` | `boolean` | 验证配置选项是否为对象 |
+| `validateMaskData(data)` | `data: any` | `void` | 验证遮罩数据，无效时抛出异常 |
+
+### 对象/实例验证
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `validateMapInstance(map)` | `map: any` | `void` | 验证 OpenLayers 地图实例是否存在 |
+| `validateElementId(id)` | `id: string` | `boolean` | 验证 DOM 元素 ID 是否存在 |
+| `validateVueParams(pointInfoList, template, Vue)` | `pointInfoList: any[]`<br>`template: any`<br>`Vue: any` | `boolean` | 验证 Vue 组件相关参数 |
+
+### 通用验证
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `validateRequired(value, message)` | `value: any`<br>`message: string` | `void` | 验证值是否存在，否则抛出带消息的异常 |
+| `validateType(value, expectedType, message)` | `value: any`<br>`expectedType: string`<br>`message: string` | `void` | 验证值类型，否则抛出带消息的异常 |
+
+## 使用示例
+
+### 验证坐标
+
+```typescript
+import { ValidationUtils } from 'my-openlayer';
+
+const lng = 120.5;
+const lat = 30.5;
+
+if (ValidationUtils.isValidCoordinate(lng, lat)) {
+  // 坐标有效，执行操作
+  map.getView().setCenter([lng, lat]);
+} else {
+  console.error('Invalid coordinates');
+}
+```
+
+### 验证必填参数
+
+```typescript
+function initLayer(map, options) {
+  try {
+    ValidationUtils.validateMapInstance(map);
+    ValidationUtils.validateRequired(options, 'Options are required');
+    
+    // 初始化图层
+  } catch (error) {
+    console.error('Initialization failed:', error.message);
+  }
+}
+```
+
+### 验证 Vue 组件参数
+
+```typescript
+if (ValidationUtils.validateVueParams(points, MyComponent, Vue)) {
+  // 创建 Vue 覆盖物
+  new VueTemplatePoint(map).addVueTemplatePoint(points, MyComponent);
+}
+```