my-openlayer 2.4.8 → 2.4.9

package/docs/ErrorHandler.md

@@ -1,106 +1,106 @@
-# ErrorHandler 错误处理
-
-`ErrorHandler` 类是一个单例工具类，用于统一管理和分发应用程序中的错误。它支持不同的日志级别，并允许注册自定义错误回调。
-
-## 导入
-
-```typescript
-import { ErrorHandler, ErrorType, MyOpenLayersError } from 'my-openlayer';
-```
-
-## 枚举与类定义
-
-### ErrorType 枚举
-
-定义了系统中可能的错误类型：
-
-| 成员 | 值 | 描述 |
-| :--- | :--- | :--- |
-| `VALIDATION_ERROR` | `'VALIDATION_ERROR'` | 参数验证错误 |
-| `MAP_ERROR` | `'MAP_ERROR'` | 地图相关错误 |
-| `LAYER_ERROR` | `'LAYER_ERROR'` | 图层相关错误 |
-| `COORDINATE_ERROR` | `'COORDINATE_ERROR'` | 坐标无效错误 |
-| `DATA_ERROR` | `'DATA_ERROR'` | 数据格式错误 |
-| `COMPONENT_ERROR` | `'COMPONENT_ERROR'` | 组件内部错误 |
-
-### MyOpenLayersError 类
-
-自定义错误类，继承自 `Error`。
-
-| 属性 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| `message` | `string` | 错误消息 |
-| `type` | `ErrorType` | 错误类型 |
-| `timestamp` | `Date` | 错误发生的时间戳 |
-| `context` | `any` | 错误相关的上下文数据 |
-
-## 方法
-
-### 静态方法
-
-| 方法名 | 参数 | 返回值 | 描述 |
-| :--- | :--- | :--- | :--- |
-| `getInstance()` | - | `ErrorHandler` | 获取 `ErrorHandler` 的单例实例 |
-| `validate(condition, message, context?)` | `condition: boolean`<br>`message: string`<br>`context?: any` | `void` | 验证条件，如果为 `false` 则抛出 `VALIDATION_ERROR` |
-| `validateMap(map)` | `map: any` | `void` | 验证地图实例是否存在 |
-| `validateCoordinates(longitude, latitude)` | `longitude: number`<br>`latitude: number` | `void` | 验证经纬度坐标是否有效 |
-| `validateLayerName(layerName)` | `layerName: string` | `void` | 验证图层名称是否有效 |
-| `validateData(data, dataType)` | `data: any`<br>`dataType: string` | `void` | 验证数据是否存在 |
-| `safeExecute<T>(fn, errorMessage, errorType?, context?)` | `fn: () => T`<br>`errorMessage: string`<br>`errorType?: ErrorType`<br>`context?: any` | `T` | 安全执行函数，捕获并处理异常 |
-
-### 实例方法
-
-| 方法名 | 参数 | 返回值 | 描述 |
-| :--- | :--- | :--- | :--- |
-| `setLogLevel(level)` | `level: 'debug' \| 'info' \| 'warn' \| 'error'` | `void` | 设置日志级别 |
-| `debug(...args)` | `...args: any[]` | `void` | 输出调试日志 |
-| `info(...args)` | `...args: any[]` | `void` | 输出信息日志 |
-| `warn(...args)` | `...args: any[]` | `void` | 输出警告日志 |
-| `createAndHandleError(message, type, context?)` | `message: string`<br>`type: ErrorType`<br>`context?: any` | `MyOpenLayersError` | 创建并处理错误，通知监听器 |
-
-## 使用示例
-
-### 基本验证
-
-```typescript
-import { ErrorHandler } from 'my-openlayer';
-
-function setCenter(longitude: number, latitude: number) {
-  // 验证坐标，如果不合法会自动抛出异常
-  ErrorHandler.validateCoordinates(longitude, latitude);
-  
-  // ...设置中心点逻辑
-}
-```
-
-### 捕获和处理错误
-
-```typescript
-import { ErrorHandler, ErrorType } from 'my-openlayer';
-
-try {
-  // 可能出错的代码
-  throw new Error('Something went wrong');
-} catch (error) {
-  ErrorHandler.getInstance().createAndHandleError(
-    'Operation failed',
-    ErrorType.COMPONENT_ERROR,
-    { originalError: error }
-  );
-}
-```
-
-### 安全执行函数
-
-```typescript
-import { ErrorHandler } from 'my-openlayer';
-
-const result = ErrorHandler.safeExecute(
-  () => {
-    // 危险操作
-    return JSON.parse(someJsonString);
-  },
-  'Failed to parse JSON',
-  ErrorType.DATA_ERROR
-);
-```
+# ErrorHandler 错误处理
+
+`ErrorHandler` 类是一个单例工具类，用于统一管理和分发应用程序中的错误。它支持不同的日志级别，并允许注册自定义错误回调。
+
+## 导入
+
+```typescript
+import { ErrorHandler, ErrorType, MyOpenLayersError } from 'my-openlayer';
+```
+
+## 枚举与类定义
+
+### ErrorType 枚举
+
+定义了系统中可能的错误类型：
+
+| 成员 | 值 | 描述 |
+| :--- | :--- | :--- |
+| `VALIDATION_ERROR` | `'VALIDATION_ERROR'` | 参数验证错误 |
+| `MAP_ERROR` | `'MAP_ERROR'` | 地图相关错误 |
+| `LAYER_ERROR` | `'LAYER_ERROR'` | 图层相关错误 |
+| `COORDINATE_ERROR` | `'COORDINATE_ERROR'` | 坐标无效错误 |
+| `DATA_ERROR` | `'DATA_ERROR'` | 数据格式错误 |
+| `COMPONENT_ERROR` | `'COMPONENT_ERROR'` | 组件内部错误 |
+
+### MyOpenLayersError 类
+
+自定义错误类，继承自 `Error`。
+
+| 属性 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `message` | `string` | 错误消息 |
+| `type` | `ErrorType` | 错误类型 |
+| `timestamp` | `Date` | 错误发生的时间戳 |
+| `context` | `any` | 错误相关的上下文数据 |
+
+## 方法
+
+### 静态方法
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `getInstance()` | - | `ErrorHandler` | 获取 `ErrorHandler` 的单例实例 |
+| `validate(condition, message, context?)` | `condition: boolean`<br>`message: string`<br>`context?: any` | `void` | 验证条件，如果为 `false` 则抛出 `VALIDATION_ERROR` |
+| `validateMap(map)` | `map: any` | `void` | 验证地图实例是否存在 |
+| `validateCoordinates(longitude, latitude)` | `longitude: number`<br>`latitude: number` | `void` | 验证经纬度坐标是否有效 |
+| `validateLayerName(layerName)` | `layerName: string` | `void` | 验证图层名称是否有效 |
+| `validateData(data, dataType)` | `data: any`<br>`dataType: string` | `void` | 验证数据是否存在 |
+| `safeExecute<T>(fn, errorMessage, errorType?, context?)` | `fn: () => T`<br>`errorMessage: string`<br>`errorType?: ErrorType`<br>`context?: any` | `T` | 安全执行函数，捕获并处理异常 |
+
+### 实例方法
+
+| 方法名 | 参数 | 返回值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `setLogLevel(level)` | `level: 'debug' \| 'info' \| 'warn' \| 'error'` | `void` | 设置日志级别 |
+| `debug(...args)` | `...args: any[]` | `void` | 输出调试日志 |
+| `info(...args)` | `...args: any[]` | `void` | 输出信息日志 |
+| `warn(...args)` | `...args: any[]` | `void` | 输出警告日志 |
+| `createAndHandleError(message, type, context?)` | `message: string`<br>`type: ErrorType`<br>`context?: any` | `MyOpenLayersError` | 创建并处理错误，通知监听器 |
+
+## 使用示例
+
+### 基本验证
+
+```typescript
+import { ErrorHandler } from 'my-openlayer';
+
+function setCenter(longitude: number, latitude: number) {
+  // 验证坐标，如果不合法会自动抛出异常
+  ErrorHandler.validateCoordinates(longitude, latitude);
+  
+  // ...设置中心点逻辑
+}
+```
+
+### 捕获和处理错误
+
+```typescript
+import { ErrorHandler, ErrorType } from 'my-openlayer';
+
+try {
+  // 可能出错的代码
+  throw new Error('Something went wrong');
+} catch (error) {
+  ErrorHandler.getInstance().createAndHandleError(
+    'Operation failed',
+    ErrorType.COMPONENT_ERROR,
+    { originalError: error }
+  );
+}
+```
+
+### 安全执行函数
+
+```typescript
+import { ErrorHandler } from 'my-openlayer';
+
+const result = ErrorHandler.safeExecute(
+  () => {
+    // 危险操作
+    return JSON.parse(someJsonString);
+  },
+  'Failed to parse JSON',
+  ErrorType.DATA_ERROR
+);
+```

package/docs/EventManager.md

@@ -1,142 +1,142 @@
-# EventManager 事件管理
-
-`EventManager` 类用于统一管理地图事件，提供简单的 API 来监听、移除和触发地图事件。它对 OpenLayers 的原生事件系统进行了封装，提供了类型安全的事件处理。
-
-## 导入
-
-```typescript
-import { EventManager, MapEventData } from 'my-openlayer';
-```
-
-## 接口定义
-
-### MapEventData 接口
-
-统一的事件数据结构，回调函数会接收此类型的参数。
-
-| 属性名 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| `type` | `MapEventType` | 事件类型 |
-| `originalEvent` | `Event` | 原始 DOM 事件对象 (可选) |
-| `coordinate` | `number[]` | 发生事件的地理坐标 (可选) |
-| `pixel` | `Pixel` | 发生事件的屏幕像素坐标 (可选) |
-| `features` | `FeatureLike[]` | 事件位置处的要素列表 (可选) |
-| `feature` | `FeatureLike` | 事件位置处的第一个要素 (可选) |
-| `zoom` | `number` | 当前地图缩放级别 (可选) |
-| `[key: string]` | `any` | 其他自定义属性 |
-
-### MapEventType 类型
-
-支持的事件类型字符串：
-`'click'` | `'dblclick'` | `'hover'` | `'moveend'` | `'zoomend'` | `'pointermove'` | `'rendercomplete'` | `'error'`
-
-## 构造函数
-
-```typescript
-constructor(map: Map)
-```
-
-| 参数名 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| `map` | `Map` | OpenLayers 地图实例 |
-
-## 方法
-
-### 监听事件
-
-```typescript
-on(type: MapEventType, callback: EventCallback, options?: { once?: boolean; filter?: (event: MapEventData) => boolean; }): string
-```
-
-注册事件监听器。
-
-| 参数名 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| `type` | `MapEventType` | 事件类型 |
-| `callback` | `EventCallback` | 事件回调函数 |
-| `options` | `object` | 监听选项 (可选) |
-| `options.once` | `boolean` | 是否只触发一次 |
-| `options.filter` | `function` | 事件过滤器，返回 false 则不触发回调 |
-
-**返回值**: `string` - 监听器 ID，用于取消监听。
-
-### 移除监听
-
-```typescript
-off(id: string): boolean
-```
-
-根据监听器 ID 移除事件监听。
-
-| 参数名 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| `id` | `string` | 监听器 ID |
-
-**返回值**: `boolean` - 是否成功移除。
-
-### 移除所有监听
-
-```typescript
-clear(): void
-```
-
-移除所有已注册的事件监听器。
-
-## 使用示例
-
-### 基础事件监听
-
-```typescript
-import { MyOl } from 'my-openlayer';
-
-const myOl = new MyOl('map-container');
-const eventManager = myOl.getEventManager();
-
-// 监听点击事件
-const clickId = eventManager.on('click', (event) => {
-  console.log('Clicked at:', event.coordinate);
-  
-  if (event.feature) {
-    console.log('Clicked feature:', event.feature);
-  }
-});
-
-// 监听缩放结束
-eventManager.on('zoomend', (event) => {
-  console.log('Current zoom:', event.zoom);
-});
-```
-
-### 一次性监听
-
-```typescript
-// 只监听一次点击
-eventManager.on('click', (event) => {
-  console.log('First click only');
-}, { once: true });
-```
-
-### 带过滤条件的监听
-
-```typescript
-// 只监听包含特定属性要素的点击
-eventManager.on('click', (event) => {
-  console.log('Clicked special feature');
-}, {
-  filter: (event) => {
-    if (!event.feature) return false;
-    const props = event.feature.getProperties();
-    return props.type === 'special';
-  }
-});
-```
-
-### 移除监听
-
-```typescript
-// 停止监听
-eventManager.off(clickId);
-
-// 或清除所有
-eventManager.clear();
-```
+# EventManager 事件管理
+
+`EventManager` 类用于统一管理地图事件，提供简单的 API 来监听、移除和触发地图事件。它对 OpenLayers 的原生事件系统进行了封装，提供了类型安全的事件处理。
+
+## 导入
+
+```typescript
+import { EventManager, MapEventData } from 'my-openlayer';
+```
+
+## 接口定义
+
+### MapEventData 接口
+
+统一的事件数据结构，回调函数会接收此类型的参数。
+
+| 属性名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `type` | `MapEventType` | 事件类型 |
+| `originalEvent` | `Event` | 原始 DOM 事件对象 (可选) |
+| `coordinate` | `number[]` | 发生事件的地理坐标 (可选) |
+| `pixel` | `Pixel` | 发生事件的屏幕像素坐标 (可选) |
+| `features` | `FeatureLike[]` | 事件位置处的要素列表 (可选) |
+| `feature` | `FeatureLike` | 事件位置处的第一个要素 (可选) |
+| `zoom` | `number` | 当前地图缩放级别 (可选) |
+| `[key: string]` | `any` | 其他自定义属性 |
+
+### MapEventType 类型
+
+支持的事件类型字符串：
+`'click'` | `'dblclick'` | `'hover'` | `'moveend'` | `'zoomend'` | `'pointermove'` | `'rendercomplete'` | `'error'`
+
+## 构造函数
+
+```typescript
+constructor(map: Map)
+```
+
+| 参数名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `map` | `Map` | OpenLayers 地图实例 |
+
+## 方法
+
+### 监听事件
+
+```typescript
+on(type: MapEventType, callback: EventCallback, options?: { once?: boolean; filter?: (event: MapEventData) => boolean; }): string
+```
+
+注册事件监听器。
+
+| 参数名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `type` | `MapEventType` | 事件类型 |
+| `callback` | `EventCallback` | 事件回调函数 |
+| `options` | `object` | 监听选项 (可选) |
+| `options.once` | `boolean` | 是否只触发一次 |
+| `options.filter` | `function` | 事件过滤器，返回 false 则不触发回调 |
+
+**返回值**: `string` - 监听器 ID，用于取消监听。
+
+### 移除监听
+
+```typescript
+off(id: string): boolean
+```
+
+根据监听器 ID 移除事件监听。
+
+| 参数名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `id` | `string` | 监听器 ID |
+
+**返回值**: `boolean` - 是否成功移除。
+
+### 移除所有监听
+
+```typescript
+clear(): void
+```
+
+移除所有已注册的事件监听器。
+
+## 使用示例
+
+### 基础事件监听
+
+```typescript
+import { MyOl } from 'my-openlayer';
+
+const myOl = new MyOl('map-container');
+const eventManager = myOl.getEventManager();
+
+// 监听点击事件
+const clickId = eventManager.on('click', (event) => {
+  console.log('Clicked at:', event.coordinate);
+  
+  if (event.feature) {
+    console.log('Clicked feature:', event.feature);
+  }
+});
+
+// 监听缩放结束
+eventManager.on('zoomend', (event) => {
+  console.log('Current zoom:', event.zoom);
+});
+```
+
+### 一次性监听
+
+```typescript
+// 只监听一次点击
+eventManager.on('click', (event) => {
+  console.log('First click only');
+}, { once: true });
+```
+
+### 带过滤条件的监听
+
+```typescript
+// 只监听包含特定属性要素的点击
+eventManager.on('click', (event) => {
+  console.log('Clicked special feature');
+}, {
+  filter: (event) => {
+    if (!event.feature) return false;
+    const props = event.feature.getProperties();
+    return props.type === 'special';
+  }
+});
+```
+
+### 移除监听
+
+```typescript
+// 停止监听
+eventManager.off(clickId);
+
+// 或清除所有
+eventManager.clear();
+```