my-openlayer 2.4.2 → 2.4.3

package/core/SelectHandler.d.ts

@@ -145,6 +145,12 @@ export default class SelectHandler {
      * @returns SelectHandler 实例（支持链式调用）
      */
     updateSelectStyle(selectStyle: Style | Style[] | ((feature: FeatureLike) => Style | Style[])): this;
+    /**
+     * 确保 Select 交互已创建
+     * 如果当前未启用选择交互，则创建一个不响应用户操作的交互实例用于编程式选择
+     * @private
+     */
+    private ensureSelectInteraction;
     /**
      * 附加事件监听器
      * @private

package/core/SelectHandler.js

@@ -151,8 +151,10 @@ export default class SelectHandler {
      */
     selectByIds(featureIds, options) {
         try {
+            // 确保交互实例存在
+            this.ensureSelectInteraction();
             if (!this.selectInteraction) {
-                this.errorHandler.warn('选择交互未启用，无法选择要素');
+                // 理论上 ensureSelectInteraction 后不应为空，这里做双重保险
                 return this;
             }
             if (!featureIds || featureIds.length === 0) {
@@ -215,8 +217,10 @@ export default class SelectHandler {
      */
     selectByProperty(propertyName, propertyValue, options) {
         try {
+            // 确保交互实例存在
+            this.ensureSelectInteraction();
             if (!this.selectInteraction) {
-                this.errorHandler.warn('选择交互未启用，无法选择要素');
+                // 理论上 ensureSelectInteraction 后不应为空，这里做双重保险
                 return this;
             }
             if (!propertyName) {
@@ -463,6 +467,27 @@ export default class SelectHandler {
             throw error;
         }
     }
+    /**
+     * 确保 Select 交互已创建
+     * 如果当前未启用选择交互，则创建一个不响应用户操作的交互实例用于编程式选择
+     * @private
+     */
+    ensureSelectInteraction() {
+        if (this.selectInteraction) {
+            return;
+        }
+        // 创建一个不响应任何用户操作的 Select 交互
+        // condition 返回 false 表示不响应任何事件
+        this.selectInteraction = new Select({
+            condition: () => false,
+            style: this.createSelectStyle()
+        });
+        this.map.addInteraction(this.selectInteraction);
+        this.isEnabled = true;
+        // 注意：这里我们不设置 currentMode，因为这是一种特殊的编程式模式
+        // 也不需要 attachEventListeners，因为这种交互不会触发用户事件
+        this.errorHandler.debug('已自动创建编程式选择交互实例');
+    }
     /**
      * 附加事件监听器
      * @private

package/docs/ConfigManager.md

@@ -0,0 +1,40 @@
+# ConfigManager 配置管理类
+
+`ConfigManager` 用于统一管理库的默认配置项，提供配置合并和 ID 生成工具。
+
+## 静态属性 (默认配置)
+
+- **DEFAULT_POINT_OPTIONS**: 默认点位配置。
+- **DEFAULT_LINE_OPTIONS**: 默认线要素配置。
+- **DEFAULT_POLYGON_OPTIONS**: 默认面要素配置。
+- **DEFAULT_CLUSTER_OPTIONS**: 默认聚合配置。
+- **DEFAULT_HEATMAP_OPTIONS**: 默认热力图配置。
+- **DEFAULT_IMAGE_OPTIONS**: 默认图片图层配置。
+- **DEFAULT_MASK_OPTIONS**: 默认遮罩配置。
+- **TIANDITU_CONFIG**: 天地图服务配置。
+
+## 静态方法
+
+- **mergeOptions<T>(defaultOptions: T, userOptions?: Partial<T>)**: 合并用户配置与默认配置。
+- **generateId(prefix?: string)**: 生成带前缀的唯一 ID。
+- **deepClone<T>(obj: T)**: 深度克隆对象。
+
+## 使用示例
+
+```typescript
+import { ConfigManager, PointOptions } from 'my-openlayer';
+
+// 1. 合并用户配置与默认配置
+const userOptions: PointOptions = {
+  layerName: 'my-points',
+  visible: true
+};
+
+const finalOptions = ConfigManager.mergeOptions(
+  ConfigManager.DEFAULT_POINT_OPTIONS,
+  userOptions
+);
+
+// 2. 生成唯一 ID
+const pointId = ConfigManager.generateId('point'); // 例如: point_169...
+```

package/docs/ErrorHandler.md

@@ -0,0 +1,45 @@
+# ErrorHandler 错误处理类
+
+`ErrorHandler` 是一个单例类，提供全局的错误捕获、日志记录和回调分发机制。
+
+## 方法
+
+- **getInstance()**: 获取单例实例。
+- **addErrorCallback(callback)**: 添加全局错误监听回调。
+- **handleError(error: MyOpenLayersError)**: 手动触发错误处理。
+- **validate(condition, message, context)**: 断言验证，失败则抛出错误。
+- **setEnabled(enabled: boolean)**: 启用/禁用日志。
+- **setLogLevel(level)**: 设置日志级别 (`debug`, `info`, `warn`, `error`)。
+
+## 静态验证方法
+
+- **validateMap(map)**: 验证地图实例。
+- **validateCoordinates(lng, lat)**: 验证经纬度有效性。
+- **validateLayerName(name)**: 验证图层名称。
+
+## 使用示例
+
+```typescript
+import { ErrorHandler, MyOpenLayersError } from 'my-openlayer';
+
+// 1. 获取实例
+const errorHandler = ErrorHandler.getInstance();
+
+// 2. 注册全局错误监听
+errorHandler.addErrorCallback((error) => {
+  console.error('地图组件发生错误:', error.message);
+  // 上报错误监控系统
+});
+
+// 3. 手动验证数据
+try {
+  ErrorHandler.validateCoordinates(200, 0); // 将抛出错误，因为经度超出范围
+} catch (e) {
+  // 处理验证错误
+}
+
+// 4. 手动触发错误
+errorHandler.handleError(
+  new MyOpenLayersError('自定义错误消息', 'CUSTOM_ERROR', { detail: '...' })
+);
+```

package/docs/EventManager.md

@@ -0,0 +1,52 @@
+# EventManager 事件管理类
+
+`EventManager` 提供统一的地图事件监听和管理功能，支持事件过滤、一次性监听和自动计数。
+
+## 方法
+
+- **on(type: MapEventType, callback: EventCallback, options?: { once?: boolean; filter?: (event: MapEventData) => boolean })**: 注册事件监听器。
+  - 支持的事件类型: `click`, `dblclick`, `hover`, `moveend`, `zoomend`, `pointermove`, `rendercomplete`, `error`。
+- **off(id: string)**: 根据 ID 移除事件监听器。
+- **offAll(type: MapEventType)**: 移除指定类型的所有监听器。
+- **clear()**: 清除所有事件监听器。
+- **getListenerCount(type: MapEventType)**: 获取指定类型的监听器数量。
+
+## 类型定义
+
+### MapEventData
+包含事件的详细信息：
+- `type`: 事件类型。
+- `coordinate`: 地理坐标。
+- `pixel`: 屏幕像素坐标。
+- `feature`: 触发事件的要素（如有）。
+- `features`: 触发事件的所有要素列表。
+- `zoom`: 当前缩放级别。
+
+## 使用示例
+
+```typescript
+const eventManager = map.getEventManager();
+
+// 1. 监听点击事件
+const clickListenerId = eventManager.on('click', (event) => {
+  console.log('点击坐标:', event.coordinate);
+  if (event.feature) {
+    console.log('点击到的要素:', event.feature.getProperties());
+  }
+});
+
+// 2. 监听一次性事件
+eventManager.on('rendercomplete', () => {
+  console.log('地图渲染完成');
+}, { once: true });
+
+// 3. 带过滤器的监听
+eventManager.on('click', (event) => {
+  console.log('点击了特定图层的要素');
+}, {
+  filter: (e) => e.feature && e.feature.get('layerName') === 'target-layer'
+});
+
+// 4. 移除监听
+eventManager.off(clickListenerId);
+```

package/docs/Line.md

@@ -0,0 +1,52 @@
+# Line 线要素类
+
+`Line` 类用于在地图上绘制线要素，支持 GeoJSON 数据加载。
+
+## 方法
+
+- **addLine(data: MapJSONData, options?: LineOptions)**: 添加线要素图层。
+  - `data`: GeoJSON 格式的数据。
+  - `options`: 配置项，支持 `strokeColor` (颜色), `strokeWidth` (宽度), `lineDash` (虚线) 等。
+
+- **addLineByUrl(url: string, options?: LineOptions)**: 从 URL 加载并添加线要素图层。
+
+- **removeLineLayer(layerName: string)**: 根据图层名称移除线图层。
+
+## 使用示例
+
+```typescript
+const lineModule = map.getLine();
+
+// GeoJSON 数据
+const lineData = {
+  type: 'FeatureCollection',
+  features: [
+    {
+      type: 'Feature',
+      geometry: {
+        type: 'LineString',
+        coordinates: [[119.8, 29.9], [119.9, 30.0]]
+      },
+      properties: { name: '线路1' }
+    }
+  ]
+};
+
+// 1. 添加线图层
+lineModule.addLine(lineData, {
+  layerName: 'my-line-layer',
+  strokeColor: '#ff0000',
+  strokeWidth: 4,
+  lineDash: [10, 10], // 虚线样式
+  zIndex: 10
+});
+
+// 2. 从 URL 加载
+lineModule.addLineByUrl('http://example.com/lines.json', {
+  layerName: 'url-line-layer',
+  strokeColor: 'blue'
+});
+
+// 3. 移除图层
+lineModule.removeLineLayer('my-line-layer');
+```

package/docs/MapBaseLayers.md

@@ -0,0 +1,48 @@
+# MapBaseLayers 底图管理类
+
+`MapBaseLayers` 用于管理地图底图（如天地图）和注记图层，支持图层切换和自定义图层。
+
+## 方法
+
+### 底图操作
+
+- **switchBaseLayer(type: string)**: 切换底图类型（如 `vec_c`, `img_c`, `ter_c`）。
+- **getCurrentBaseLayerType()**: 获取当前底图类型。
+
+### 注记操作
+
+- **addAnnotationLayer(options: AnnotationLayerOptions)**: 添加注记图层。
+- **switchAnnotationLayer(annotationType: AnnotationType)**: 切换注记类型（如 `cva_c`）。
+- **setAnnotationVisible(visible: boolean)**: 设置注记图层可见性。
+- **isAnnotationVisible()**: 检查注记图层是否可见。
+
+### 其他图层
+
+- **addGeoServerLayer(url: string, layerName: string, options: GeoServerLayerOptions)**: 添加 GeoServer WMS 图层。
+- **removeLayersByType(type: string)**: 移除指定类型的图层。
+- **clearAllLayers()**: 清除所有底图和注记图层。
+- **getLayerStats()**: 获取图层统计信息。
+
+## 使用示例
+
+```typescript
+const baseLayers = map.getMapBaseLayers();
+
+// 1. 切换底图
+// vec_c: 矢量底图, img_c: 影像底图, ter_c: 地形底图
+baseLayers.switchBaseLayer('img_c');
+
+// 2. 控制注记图层
+baseLayers.setAnnotationVisible(false); // 隐藏注记
+baseLayers.switchAnnotationLayer('cia_c'); // 切换为影像注记
+
+// 3. 添加 GeoServer WMS 图层
+baseLayers.addGeoServerLayer(
+  'http://localhost:8080/geoserver/wms',
+  'workspace:layer_name',
+  {
+    visible: true,
+    zIndex: 5
+  }
+);
+```

package/docs/MapTools.md

@@ -0,0 +1,48 @@
+# MapTools 地图工具类
+
+`MapTools` 提供通用的地图操作工具，如图层查找、移除、显隐控制、地图裁剪和视图自适应。
+
+## 方法
+
+### 图层管理
+
+- **getLayerByLayerName(layerName: string | string[])**: 根据名称获取图层对象（支持模糊匹配）。
+- **removeLayer(layerName: string | string[])**: 移除指定名称的图层。
+- **setLayerVisible(layerName: string, visible: boolean)**: 设置图层可见性。
+
+### 视图操作
+
+- **locationAction(lgtd: number, lttd: number, zoom?: number, duration?: number)**: 视图定位。
+- **fitToLayers(layerNameOrLayers: string | string[] | Layer[], fitOptions?)**: 缩放地图以适应指定图层的范围。
+- **fitByData(jsonData: MapJSONData, fitOptions?)**: 缩放地图以适应 GeoJSON 数据的范围。
+
+### 其他
+
+- **setMapClip(baseLayer: any, data: MapJSONData)**: 设置地图裁剪区域（Canvas 级裁剪）。
+
+## 使用示例
+
+```typescript
+const tools = map.getTools();
+
+// 1. 获取图层
+const layers = tools.getLayerByLayerName('my-layer');
+if (layers.length > 0) {
+  console.log('找到图层:', layers[0]);
+}
+
+// 2. 移除图层
+tools.removeLayer('temp-layer');
+
+// 3. 视图自适应图层
+tools.fitToLayers('target-layer', {
+  padding: [50, 50, 50, 50],
+  duration: 1000
+});
+
+// 4. 根据数据缩放
+tools.fitByData(geoJsonData);
+
+// 5. 设置可见性
+tools.setLayerVisible('background-layer', false);
+```

package/docs/MeasureHandler.md

@@ -0,0 +1,47 @@
+# MeasureHandler 测量工具类
+
+`MeasureHandler` 提供在地图上进行距离和面积测量的功能。
+
+## 方法
+
+- **start(type: 'LineString' | 'Polygon')**: 开始测量。
+  - `'LineString'`: 测量距离（单位：m/km）。
+  - `'Polygon'`: 测量面积（单位：m²/km²）。
+- **end()**: 结束当前的绘制测量操作。
+- **clean()**: 清除所有测量结果和绘制的图形。
+- **destory()**: 销毁测量工具，释放资源。
+
+## 交互说明
+
+- 单击开始绘制。
+- 双击结束绘制。
+- 移动鼠标会显示实时测量提示。
+
+## 使用示例
+
+```typescript
+import { MeasureHandler } from 'my-openlayer';
+
+// 实例化测量工具（需要传入原生 ol.Map 对象）
+const measure = new MeasureHandler(map.map);
+
+// 1. 开始测距
+document.getElementById('measure-dist-btn').onclick = () => {
+  measure.start('LineString');
+};
+
+// 2. 开始测面
+document.getElementById('measure-area-btn').onclick = () => {
+  measure.start('Polygon');
+};
+
+// 3. 结束测量（停止绘制，保留图形）
+document.getElementById('end-btn').onclick = () => {
+  measure.end();
+};
+
+// 4. 清除结果（移除图形和提示）
+document.getElementById('clear-btn').onclick = () => {
+  measure.clean();
+};
+```

package/docs/MyOl.md

@@ -0,0 +1,62 @@
+# MyOl 核心类
+
+`MyOl` 是地图组件库的入口类，负责初始化地图实例并提供对各个功能模块的访问入口。
+
+## 构造函数
+
+```typescript
+new MyOl(id: string | HTMLElement, options?: MapInitType)
+```
+
+- **id**: 地图容器的 ID 或 DOM 元素。
+- **options**: 地图初始化配置项。
+
+## 方法
+
+### 模块获取
+
+- **getPoint()**: 获取点要素操作实例 `Point`。
+- **getLine()**: 获取线要素操作实例 `Line`。
+- **getPolygon()**: 获取面要素操作实例 `Polygon`。
+- **getMapBaseLayers()**: 获取底图管理实例 `MapBaseLayers`。
+- **getTools()**: 获取地图工具实例 `MapTools`。
+- **getSelectHandler()**: 获取要素选择实例 `SelectHandler`。
+- **getEventManager()**: 获取事件管理实例 `EventManager`。
+- **getErrorHandler()**: 获取错误处理实例 `ErrorHandler`。
+- **getConfigManager()**: 获取配置管理实例 `ConfigManager`。
+
+### 地图操作
+
+- **locationAction(longitude: number, latitude: number, zoom?: number, duration?: number)**: 地图定位到指定坐标。
+- **resetPosition(duration?: number)**: 重置地图位置到初始中心点。
+- **destroy()**: 销毁地图实例及相关资源。
+
+### 静态方法
+
+- **createView(options: MapInitType)**: 创建地图视图。
+
+## 使用示例
+
+```typescript
+import MyOl, { MapInitType } from 'my-openlayer';
+
+// 1. 定义配置
+const options: MapInitType = {
+  center: [119.81, 29.969],
+  zoom: 10,
+  minZoom: 3,
+  maxZoom: 18,
+  token: '您的天地图Token', // 可选，用于加载天地图
+  annotation: true // 是否显示注记
+};
+
+// 2. 初始化地图
+const map = new MyOl('map-container', options);
+
+// 3. 获取功能模块
+const pointModule = map.getPoint();
+const lineModule = map.getLine();
+
+// 4. 地图操作
+map.locationAction(120.15, 30.28, 12); // 定位到杭州
+```

package/docs/Point.md

@@ -0,0 +1,58 @@
+# Point 点要素类
+
+`Point` 类用于在地图上添加和管理点位要素，支持普通点位、聚合点位、DOM 点位和 Vue 组件点位。
+
+## 方法
+
+### 普通点位
+
+- **addPoint(pointData: PointData[], options: PointOptions)**: 添加普通点位图层。
+  - `pointData`: 点位数据数组，需包含 `lgtd` (经度) 和 `lttd` (纬度)。
+  - `options`: 配置项，包括图标 `img`、文本 `textKey` 等。
+
+### 聚合点位
+
+- **addClusterPoint(pointData: PointData[], options: ClusterOptions)**: 添加聚合点位图层。
+  - 会根据地图缩放级别自动聚合临近的点位。
+  - `options.distance`: 聚合距离。
+
+### DOM 与组件点位
+
+- **addVueTemplatePoint(pointDataList: PointData[], template: any, options?)**: 添加 Vue 组件点位（推荐）。
+  - 返回控制对象，包含 `setVisible`, `remove`, `getPoints` 等方法。
+- **addDomPoint(twinkleList: TwinkleItem[], callback?)**: 添加原生 DOM 点位（底层实现）。
+
+### 其他
+
+- **locationAction(lgtd: number, lttd: number, zoom?: number, duration?: number)**: 定位到指定点。
+
+## 使用示例
+
+```typescript
+const pointModule = map.getPoint();
+
+// 1. 添加普通点位
+const points = [
+  { lgtd: 119.81, lttd: 29.969, name: '点A', type: 'station' },
+  { lgtd: 119.82, lttd: 29.970, name: '点B', type: 'station' }
+];
+
+pointModule.addPoint(points, {
+  layerName: 'station-layer',
+  img: 'path/to/icon.png', // 图标路径
+  scale: 0.8,
+  textKey: 'name', // 显示 'name' 字段作为标注
+  textFillColor: '#000',
+  textOffsetY: 25
+});
+
+// 2. 添加聚合点位
+pointModule.addClusterPoint(points, {
+  layerName: 'cluster-layer',
+  distance: 40, // 聚合像素距离
+  img: 'path/to/cluster-icon.png'
+});
+
+// 3. 定位
+pointModule.locationAction(119.81, 29.969, 15);
+```

package/docs/Polygon.md

@@ -0,0 +1,65 @@
+# Polygon 面要素类
+
+`Polygon` 类用于在地图上绘制面要素、热力图、图片图层和遮罩层。
+
+## 方法
+
+### 面要素操作
+
+- **addPolygon(dataJSON: MapJSONData, options?: PolygonOptions)**: 添加多边形图层。
+  - 支持填充色 `fillColor`、边框 `strokeColor`、文本标注 `textKey` 等配置。
+- **addPolygonByUrl(url: string, options?: PolygonOptions)**: 从 URL 加载多边形图层。
+- **addBorderPolygon(data: MapJSONData, options?: PolygonOptions)**: 添加边界图层（通常用于行政区划边界）。
+- **addBorderPolygonByUrl(url: string, options?: PolygonOptions)**: 从 URL 加载边界图层。
+- **removePolygonLayer(layerName: string)**: 移除面图层。
+
+### 样式更新
+
+- **updateFeatureColor(layerName: string, colorObj?: { [propName: string]: string }, options?: FeatureColorUpdateOptions)**: 动态更新面要素颜色，常用于数据可视化展示。
+
+### 高级图层
+
+- **addImageLayer(imageData: ImageLayerData, options?: PolygonOptions)**: 添加图片图层（ImageStatic）。
+  - 支持将图片叠加在特定地理范围 `extent` 上。
+- **addHeatmap(pointData: PointData[], options?: HeatMapOptions)**: 添加热力图。
+- **addMaskLayer(data: any, options?: MaskLayerOptions)**: 添加遮罩图层（反向裁剪效果）。
+- **setOutLayer(data: MapJSONData, options?)**: 设置外围蒙版图层（擦除效果）。
+
+## 使用示例
+
+```typescript
+const polygonModule = map.getPolygon();
+
+// 1. 添加面图层
+polygonModule.addPolygon(geoJsonData, {
+  layerName: 'area-layer',
+  fillColor: 'rgba(0, 0, 255, 0.1)',
+  strokeColor: 'blue',
+  strokeWidth: 2,
+  textKey: 'name', // 显示名称
+  textFillColor: '#fff'
+});
+
+// 2. 动态更新颜色（数据可视化）
+// 假设 'area-layer' 中的要素有 'name' 属性，我们将 '区域A' 设为红色
+polygonModule.updateFeatureColor(
+  'area-layer',
+  {
+    '区域A': 'rgba(255, 0, 0, 0.5)',
+    '区域B': 'rgba(0, 255, 0, 0.5)'
+  },
+  { textKey: 'name' }
+);
+
+// 3. 添加热力图
+const heatPoints = [
+  { lgtd: 119.8, lttd: 29.9, value: 100 },
+  { lgtd: 119.9, lttd: 30.0, value: 50 }
+];
+polygonModule.addHeatmap(heatPoints, {
+  layerName: 'heatmap',
+  radius: 20,
+  blur: 15,
+  valueKey: 'value' // 权重字段
+});
+```

package/docs/RiverLayerManager.md

@@ -0,0 +1,59 @@
+# 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
+  }
+});
+```