my-openlayer 2.4.7 → 2.4.9

package/docs/MapTools.md

@@ -1,48 +1,172 @@
-# 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);
-```
+# MapTools 地图工具类
+
+`MapTools` 提供通用的地图操作工具，包括图层查找、移除、显隐控制、地图裁剪和视图自适应等功能。
+
+## 构造函数
+
+```typescript
+const tools = new MapTools(map: Map);
+```
+
+- **map**: OpenLayers 地图实例。
+
+## 方法
+
+### 图层管理
+
+#### getLayerByLayerName
+
+根据名称获取图层对象（支持模糊匹配）。
+
+```typescript
+getLayerByLayerName(layerName: string | string[]): Layer[]
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `layerName` | `string` \| `string[]` | 图层名称或名称数组 |
+
+#### removeLayer
+
+移除指定名称的图层。
+
+```typescript
+removeLayer(layerName: string | string[]): void
+```
+
+#### setLayerVisible
+
+设置图层可见性。
+
+```typescript
+setLayerVisible(layerName: string, visible: boolean): void
+```
+
+### 视图操作
+
+#### locationAction
+
+视图定位动画。
+
+```typescript
+locationAction(lgtd: number, lttd: number, zoom = 20, duration = 3000): boolean
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `lgtd` | `number` | 目标经度 |
+| `lttd` | `number` | 目标纬度 |
+| `zoom` | `number` | 目标缩放层级 |
+| `duration` | `number` | 动画持续时间（毫秒） |
+
+#### fitToLayers
+
+缩放地图以适应指定图层的范围。
+
+```typescript
+fitToLayers(
+  layerNameOrLayers: string | string[] | Layer[], 
+  fitOptions?: {
+    padding?: [number, number, number, number];
+    maxZoom?: number;
+    duration?: number;
+  }
+): boolean
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `layerNameOrLayers` | `string` \| `Layer[]` | 图层名称或图层对象数组 |
+| `fitOptions` | `Object` | 缩放配置：padding (边距), maxZoom, duration |
+
+#### fitByData
+
+缩放地图以适应 GeoJSON 数据的范围。
+
+```typescript
+fitByData(
+  jsonData: MapJSONData, 
+  fitOptions?: {
+    padding?: [number, number, number, number];
+    maxZoom?: number;
+    duration?: number;
+  }
+): boolean
+```
+
+### 高级功能
+
+#### setMapClip
+
+设置地图裁剪区域（基于 Canvas 的裁剪）。
+
+```typescript
+static setMapClip(baseLayer: Layer, data: MapJSONData): Layer
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `baseLayer` | `Layer` | 需要被裁剪的图层 |
+| `data` | `MapJSONData` | 定义裁剪形状的 GeoJSON 数据 |
+
+## 使用示例
+
+### 图层查找与控制
+
+```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.setLayerVisible('background-layer', false);
+```
+
+### 视图定位与缩放
+
+```typescript
+// 定位到指定坐标
+tools.locationAction(120.123, 30.456, 15, 2000);
+
+// 缩放以包含指定图层的所有要素
+tools.fitToLayers('target-layer', {
+  padding: [50, 50, 50, 50], // 上右下左边距
+  duration: 1000
+});
+
+// 缩放以包含 GeoJSON 数据范围
+tools.fitByData(geoJsonData, {
+  maxZoom: 18
+});
+```
+
+### 地图裁剪
+
+```typescript
+// 创建底图图层
+const baseLayer = new TileLayer({ ... });
+
+// 定义裁剪区域（例如一个多边形）
+const clipPolygon = {
+  type: 'FeatureCollection',
+  features: [{
+    type: 'Feature',
+    geometry: {
+      type: 'Polygon',
+      coordinates: [[...]]
+    }
+  }]
+};
+
+// 应用裁剪
+// 注意：这会修改 baseLayer 的渲染行为，使其只在 clipPolygon 范围内显示
+MapTools.setMapClip(baseLayer, clipPolygon);
+map.addLayer(baseLayer);
+```

package/docs/MeasureHandler.md

@@ -1,47 +1,87 @@
-# 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();
-};
-```
+# MeasureHandler 类
+
+`MeasureHandler` 类提供地图上的距离和面积测量功能。
+
+## 构造函数
+
+```typescript
+constructor(map: Map)
+```
+
+- **map**: OpenLayers 地图实例。
+
+## 类型定义
+
+### MeasureHandlerType
+
+```typescript
+type MeasureHandlerType = 'LineString' | 'Polygon';
+```
+
+## 方法
+
+### start
+
+开始测量。
+
+```typescript
+start(type: MeasureHandlerType): void
+```
+
+- **type**: 测量类型，`'LineString'` (测距) 或 `'Polygon'` (测面)。
+- **说明**: 调用此方法后，鼠标在地图上点击开始绘制，双击结束绘制。绘制过程中会显示测量结果的 tooltip。
+
+### end
+
+结束测量绘制交互，但保留测量结果。
+
+```typescript
+end(): void
+```
+
+### clean
+
+清除所有测量结果和交互。
+
+```typescript
+clean(): void
+```
+
+- **说明**: 移除地图上的所有测量绘制、结果标签和 tooltip。
+
+### destroy
+
+销毁实例。
+
+```typescript
+destory(): void
+```
+
+- **说明**: 彻底清理资源，同 `clean`。
+
+## 使用示例
+
+### 测距
+
+```typescript
+import { MeasureHandler } from 'my-openlayers';
+
+const measureTool = new MeasureHandler(map);
+
+// 开始测距
+measureTool.start('LineString');
+```
+
+### 测面
+
+```typescript
+// 开始测面
+measureTool.start('Polygon');
+```
+
+### 清除测量
+
+```typescript
+// 清除所有测量结果
+measureTool.clean();
+```

package/docs/MyOl.md

@@ -1,62 +1,247 @@
-# 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); // 定位到杭州
-```
+# MyOl 类
+
+`MyOl` 是地图的核心类，作为整个库的入口点，负责地图的初始化、配置管理、模块加载以及基础的地图操作（如定位、重置）。它采用了模块化设计，按需加载各个功能模块（如点、线、面要素管理）。
+
+## 导入
+
+```typescript
+import { MyOl } from 'my-openlayer';
+// 或者
+import MyOl from 'my-openlayer';
+```
+
+## 构造函数
+
+```typescript
+constructor(id: string | HTMLElement, options?: Partial<MapInitType>)
+```
+
+初始化一个新的地图实例。
+
+### 参数说明
+
+| 参数名 | 类型 | 必填 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| `id` | `string` \| `HTMLElement` | 是 | - | 地图容器的 DOM ID 字符串或 HTMLElement 对象。 |
+| `options` | `Partial<MapInitType>` | 否 | `{}` | 地图初始化配置选项，详见下表。 |
+
+### MapInitType 配置选项
+
+| 属性名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `center` | `number[]` | 地图初始中心点坐标 `[经度, 纬度]`，默认为 `[0, 0]`。 |
+| `zoom` | `number` | 地图初始缩放级别，默认为 `2`。 |
+| `minZoom` | `number` | 最小缩放级别。 |
+| `maxZoom` | `number` | 最大缩放级别。 |
+| `token` | `string` | 天地图 API Token，用于加载天地图底图。 |
+| `annotation` | `boolean` | 是否显示注记图层（如地名标注），默认为 `false`。 |
+| `layers` | `LayerItem[]` | 自定义初始图层数组。如果设置了此项，内置底图管理可能受到影响。 |
+| `mapClipData` | `MapJSONData` | 地图裁剪数据（GeoJSON 格式），用于仅显示特定区域。 |
+| `enableLog` | `boolean` | 是否启用内部日志输出，默认为 `false`。 |
+| `logLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | 日志级别，默认为 `'error'`。 |
+| `projection` | `object` | 自定义投影坐标系配置。 |
+| `projection.code` | `string` | 投影代码，如 `'EPSG:4549'`。 |
+| `projection.def` | `string` | proj4 定义字符串。 |
+| `projection.extent` | `number[]` | 投影范围。 |
+
+## 静态方法
+
+### createView
+
+创建 OpenLayers 的 `View` 实例。
+
+```typescript
+static createView(options: MapInitType): View
+```
+
+| 参数名 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `options` | `MapInitType` | 地图配置选项，主要使用其中的 `center`, `zoom`, `projection` 等属性。 |
+
+## 实例方法
+
+### 模块获取
+
+`MyOl` 提供了懒加载的模块获取方法，只有在首次调用时才会初始化对应模块。
+
+#### getPoint
+
+获取点要素操作模块。
+
+```typescript
+getPoint(): Point
+```
+
+**返回值**: `Point` 实例，用于添加、删除、管理点要素。
+
+#### getLine
+
+获取线要素操作模块。
+
+```typescript
+getLine(): Line
+```
+
+**返回值**: `Line` 实例，用于绘制线条。
+
+#### getPolygon
+
+获取面要素操作模块。
+
+```typescript
+getPolygon(): Polygon
+```
+
+**返回值**: `Polygon` 实例，用于绘制多边形。
+
+#### getMapBaseLayers
+
+获取底图管理模块。
+
+```typescript
+getMapBaseLayers(): MapBaseLayers
+```
+
+**返回值**: `MapBaseLayers` 实例，用于切换底图类型（矢量、影像、地形）。
+
+#### getTools
+
+获取地图工具模块。
+
+```typescript
+getTools(): MapTools
+```
+
+**返回值**: `MapTools` 实例，包含地图截图、裁剪等工具。
+
+#### getSelectHandler
+
+获取要素选择处理器模块。
+
+```typescript
+getSelectHandler(): SelectHandler
+```
+
+**返回值**: `SelectHandler` 实例，用于处理地图要素的点击、悬停选择交互。
+
+### 地图操作
+
+#### locationAction
+
+定位到指定坐标，支持动画过渡。
+
+```typescript
+locationAction(longitude: number, latitude: number, zoom: number = 20, duration: number = 3000): void
+```
+
+| 参数名 | 类型 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `longitude` | `number` | - | 目标经度。 |
+| `latitude` | `number` | - | 目标纬度。 |
+| `zoom` | `number` | `20` | 目标缩放级别。 |
+| `duration` | `number` | `3000` | 动画持续时间（毫秒）。 |
+
+#### resetPosition
+
+重置地图位置到初始化时设置的中心点。
+
+```typescript
+resetPosition(duration: number = 3000): void
+```
+
+| 参数名 | 类型 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `duration` | `number` | `3000` | 动画持续时间（毫秒）。 |
+
+### 管理器访问
+
+#### getEventManager
+
+获取事件管理器，用于监听地图事件。
+
+```typescript
+getEventManager(): EventManager
+```
+
+#### getErrorHandler
+
+获取错误处理器，用于自定义错误处理逻辑。
+
+```typescript
+getErrorHandler(): ErrorHandler
+```
+
+#### getConfigManager
+
+获取配置管理器。
+
+```typescript
+getConfigManager(): ConfigManager
+```
+
+#### getMapOptions
+
+获取当前地图的只读配置副本。
+
+```typescript
+getMapOptions(): Readonly<MapInitType>
+```
+
+### 销毁
+
+#### destroy
+
+销毁地图实例，清理所有事件监听和资源。
+
+```typescript
+destroy(): void
+```
+
+## 使用示例
+
+### 完整初始化
+
+```typescript
+import { MyOl } from 'my-openlayer';
+
+// 定义配置
+const options = {
+  // 杭州市中心
+  center: [120.15507, 30.274085],
+  zoom: 12,
+  minZoom: 5,
+  maxZoom: 18,
+  
+  // 天地图 Token
+  token: 'YOUR_TIANDITU_TOKEN',
+  
+  // 开启注记
+  annotation: true,
+  
+  // 开启调试日志
+  enableLog: true,
+  logLevel: 'debug'
+};
+
+// 初始化地图
+const map = new MyOl('map-container', options);
+
+// 监听加载完成
+map.getEventManager().on('rendercomplete', () => {
+  console.log('Map loaded!');
+});
+```
+
+### 使用自定义投影
+
+```typescript
+import { MyOl } from 'my-openlayer';
+
+const map = new MyOl('map', {
+  projection: {
+    code: 'EPSG:4549', // CGCS2000 3度带
+    def: '+proj=tmerc +lat_0=0 +lon_0=120 +k=1 +x_0=500000 +y_0=0 +ellps=GRS80 +units=m +no_defs',
+    extent: [...] // 可选
+  }
+});
+```