my-openlayer 2.4.6 → 2.4.8

package/docs/SelectHandler.md

@@ -1,126 +1,147 @@
-# SelectHandler 要素选择类
+# SelectHandler 类
 
-`SelectHandler` 负责地图要素的交互选择，支持点击、悬停等多种模式，以及编程式选择。
+`SelectHandler` 类用于处理地图上的要素选择交互，支持点击、悬停、Ctrl+点击等多种模式，并支持编程式选择。
 
-## 核心特性
+## 构造函数
 
-- **独立渲染机制**：采用独立的 Select 实例渲染选中要素，确保样式完全隔离，互不干扰。
-- **静态样式固化**：在选中瞬间计算并固化样式，支持基于原始样式的复杂计算（如 `feature.getStyle()`），彻底避免递归调用风险。
-- **多选隔离**：支持不同要素同时应用完全不同的高亮样式。
-- **自动清理**：自动管理渲染实例的生命周期，防止内存泄漏。
+```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
+
+启用要素选择。
 
-- **enableSelect(mode: SelectMode, options?: SelectOptions)**: 启用选择交互。
-  - `mode`: `'click'` (点击), `'hover'` (悬停), `'ctrl'` (Ctrl+点击)。
-  - `options`:
-    - `multi`: 是否允许多选。
-    - `layerFilter`: 图层过滤器（图层名称数组）。
-    - `onSelect`: 选中回调。
-    - `onDeselect`: 取消选中回调。
-    - `selectStyle`: 选中时的样式。支持 `Style` 对象、数组或函数 `(feature, resolution) => Style`。**推荐使用函数**以实现基于原始样式的动态高亮。
+```typescript
+enableSelect(mode: SelectMode = 'click', options?: SelectOptions): this
+```
+
+- **mode**: 选择模式。
+- **options**: 配置选项。
+- **返回值**: `SelectHandler` 实例，支持链式调用。
+
+### disableSelect
 
-- **disableSelect()**: 禁用选择交互（停止响应用户操作，并清理交互式高亮）。
-- **isSelectEnabled()**: 检查是否已启用。
+禁用要素选择。
+
+```typescript
+disableSelect(): this
+```
+
+- **返回值**: `SelectHandler` 实例。
+
+### clearSelection
+
+清除所有选择（包括交互式和编程式）。
+
+```typescript
+clearSelection(): this
+```
 
-### 编程式选择
+- **返回值**: `SelectHandler` 实例。
 
-- **selectByIds(featureIds: string[], options?)**: 根据 ID 选中要素。
-- **selectByProperty(propertyName: string, propertyValue: any, options?)**: 根据属性值选中要素。
-- **clearSelection()**: 清除当前所有选中状态（包括交互式和编程式）。
-- **getSelectedFeatures()**: 获取当前选中的要素列表（仅包含交互式选择的要素）。
+### 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` 实例。
 
 ## 使用示例
 
-### 1. 基础用法
+### 启用点击选择
 
 ```typescript
-const selectHandler = map.getSelectHandler();
+import { SelectHandler } from 'my-openlayers';
+
+const selectHandler = new SelectHandler(map);
 
-// 启用点击选择
+// 启用点击选择，仅针对 'cities' 图层
 selectHandler.enableSelect('click', {
-  multi: false, // 单选
-  layerFilter: ['target-layer'], // 仅选择特定图层的要素
+  layerFilter: ['cities'],
   onSelect: (event) => {
-    const feature = event.selected[0];
-    console.log('选中要素:', feature.getProperties());
+    console.log('Selected:', event.selected);
   },
   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 })
-    })
-  })
+    console.log('Deselected:', event.deselected);
+  }
 });
 ```
 
-### 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;
-    });
-  }
+selectHandler.enableSelect('hover', {
+  selectStyle: new Style({
+    stroke: new Stroke({ color: 'yellow', width: 4 })
+  })
 });
 ```
 
-### 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 }) })
+// 选择 ID 为 'beijing' 的要素并自动定位
+selectHandler.selectByIds(['beijing'], {
+  fitView: true,
+  fitPadding: 50
 });
 ```
 
-### 4. 禁用与清理
+### 清除选择
 
 ```typescript
-// 禁用用户交互（停止响应点击，但保留编程式高亮）
-selectHandler.disableSelect();
-
-// 清除所有选择（包括交互式和编程式的高亮）
 selectHandler.clearSelection();
 ```

package/docs/ValidationUtils.md

@@ -1,38 +1,83 @@
-# ValidationUtils 验证工具类
+# ValidationUtils 验证工具
 
-`ValidationUtils` 提供了一系列静态方法用于参数校验。
+`ValidationUtils` 提供了一系列静态方法，用于验证地图操作中的各种参数和数据，确保数据的完整性和类型正确性。
 
-## 方法
+## 导入
 
-- **isValidCoordinate(lng, lat)**: 检查坐标是否有效（数字且在范围内）。
-- **validateLngLat(lng, lat)**: 简化的经纬度检查。
-- **validateLayerName(name)**: 验证图层名称非空。
-- **validateGeoJSONData(data)**: 验证 GeoJSON 数据格式。
-- **isValidColor(color)**: 验证颜色字符串格式。
-- **validateVueParams(...)**: 验证 Vue 组件点位所需的参数。
+```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';
 
-// 1. 验证坐标
-const lng = 120.1;
-const lat = 30.2;
+const lng = 120.5;
+const lat = 30.5;
 
 if (ValidationUtils.isValidCoordinate(lng, lat)) {
-  console.log('坐标有效');
+  // 坐标有效，执行操作
+  map.getView().setCenter([lng, lat]);
 } else {
-  console.error('坐标无效');
+  console.error('Invalid coordinates');
 }
+```
+
+### 验证必填参数
 
-// 2. 验证颜色
-if (ValidationUtils.isValidColor('#ff0000')) {
-  // ...
+```typescript
+function initLayer(map, options) {
+  try {
+    ValidationUtils.validateMapInstance(map);
+    ValidationUtils.validateRequired(options, 'Options are required');
+    
+    // 初始化图层
+  } catch (error) {
+    console.error('Initialization failed:', error.message);
+  }
 }
+```
 
-// 3. 验证 GeoJSON
-if (ValidationUtils.validateGeoJSONData(jsonData)) {
-  // 安全地加载数据
+### 验证 Vue 组件参数
+
+```typescript
+if (ValidationUtils.validateVueParams(points, MyComponent, Vue)) {
+  // 创建 Vue 覆盖物
+  new VueTemplatePoint(map).addVueTemplatePoint(points, MyComponent);
 }
 ```

package/docs/VueTemplatePoint.md

@@ -1,24 +1,121 @@
 # VueTemplatePoint Vue 组件点位类
 
-`VueTemplatePoint` 允许将 Vue 组件直接渲染为地图上的点位覆盖物（Overlay），支持 Vue 2 和 Vue 3。
+`VueTemplatePoint` 允许将 Vue 组件直接渲染为地图上的点位覆盖物（Overlay），支持 Vue 2 和 Vue 3。它通过创建 Overlay 并将 Vue 组件挂载到 Overlay 的 DOM 元素中来实现。
+
+## 构造函数
+
+```typescript
+constructor(map: Map)
+```
+
+- **参数**:
+  - `map` (Map): OpenLayers 地图实例。
+
+## 接口定义
+
+### VueTemplatePointOptions
+
+配置 Vue 模版点位的选项接口。
+
+| 属性 | 类型 | 必填 | 默认值 | 描述 |
+| :--- | :--- | :--- | :--- | :--- |
+| Template | `any` | 是 | - | Vue 组件模版对象。 |
+| lgtd | `number` | 是 | - | 经度。 |
+| lttd | `number` | 是 | - | 纬度。 |
+| props | `Record<string, any>` | 否 | - | 传递给组件的 props。 |
+| positioning | `string` | 否 | `'center-center'` | 覆盖物相对于位置的锚点。可选值见 OpenLayers Overlay positioning。 |
+| stopEvent | `boolean` | 否 | `false` | 是否阻止地图事件冒泡。 |
+| zIndex | `number` | 否 | - | DOM 元素的 z-index。 |
+| className | `string` | 否 | - | DOM 元素的 CSS 类名。 |
+| visible | `boolean` | 否 | `true` | 初始可见性。 |
 
 ## 方法
 
-- **addVueTemplatePoint(pointDataList: any[], template: any, options?)**: 添加 Vue 组件点位。
-  - `pointDataList`: 点位数据列表。
-  - `template`: Vue 组件对象。
-  - `options`:
-    - `positioning`: 覆盖物定位点（如 `'center-center'`）。
-    - `stopEvent`: 是否阻止事件冒泡。
+### addVueTemplatePoint
 
-### 返回值
+添加一组 Vue 组件点位。
+
+```typescript
+addVueTemplatePoint(
+  pointDataList: any[], 
+  template: any, 
+  options?: {
+    positioning?: string,
+    stopEvent?: boolean
+  }
+): VueTemplatePointController
+```
+
+- **参数**:
+  - `pointDataList` (any[]): 点位数据列表。列表中的每个对象都必须包含 `lgtd` (经度) 和 `lttd` (纬度) 属性。
+  - `template` (any): Vue 组件对象。
+  - `options` (Object): 可选配置。
+    - `positioning`: 覆盖物定位点（如 `'center-center'`, `'bottom-center'` 等）。
+    - `stopEvent`: 是否阻止事件冒泡（默认 `false`）。
+
+- **返回值**:
+  返回一个控制对象 `VueTemplatePointController`，用于批量管理这组点位。
+
+### VueTemplatePointController 接口
+
+`addVueTemplatePoint` 返回的对象包含以下方法：
+
+| 方法 | 描述 |
+| :--- | :--- |
+| `setVisible(visible: boolean): void` | 设置该组所有点位的可见性。 |
+| `setOneVisibleByProp(propName: string, propValue: any, visible: boolean): void` | 根据点位数据中的属性值控制特定点位的可见性。 |
+| `remove(): void` | 移除该组所有点位并销毁组件实例。 |
+| `getPoints(): VueTemplatePointInstance[]` | 获取该组创建的所有底层点位实例列表。 |
+
+### getPointById
+
+根据 ID 获取单个点位实例。
+
+```typescript
+getPointById(id: string): VueTemplatePointInstance | undefined
+```
 
-该方法返回一个控制对象，包含以下方法：
+### getAllPoints
 
-- **setVisible(visible: boolean)**: 设置所有点位的可见性。
-- **setOneVisibleByProp(propName: string, propValue: any, visible: boolean)**: 根据属性值控制特定点位的可见性。
-- **remove()**: 移除所有点位并销毁组件实例。
-- **getPoints()**: 获取底层点位实例列表。
+获取所有管理的点位实例。
+
+```typescript
+getAllPoints(): VueTemplatePointInstance[]
+```
+
+### removeAllPoints
+
+移除并销毁所有点位。
+
+```typescript
+removeAllPoints(): void
+```
+
+### getPointCount
+
+获取当前管理的点位数量。
+
+```typescript
+getPointCount(): number
+```
+
+## VueTemplatePointInstance 实例方法
+
+单个点位实例 (`VueTemplatePointInstance`) 提供的操作方法：
+
+| 方法 | 描述 |
+| :--- | :--- |
+| `setVisible(visible: boolean): void` | 设置当前点位可见性。 |
+| `isVisible(): boolean` | 获取当前可见性状态。 |
+| `updatePosition(lgtd: number, lttd: number): void` | 更新点位经纬度位置。 |
+| `getPosition(): number[]` | 获取当前位置 `[lgtd, lttd]`。 |
+| `updateProps(newProps: Record<string, any>): void` | 更新传递给组件的 props。 |
+| `setStyle(styles: Partial<CSSStyleDeclaration>): void` | 设置 DOM 元素的 CSS 样式。 |
+| `addClass(className: string): void` | 添加 CSS 类名。 |
+| `removeClass(className: string): void` | 移除 CSS 类名。 |
+| `remove(): void` | 移除并销毁当前点位。 |
+| `getId(): string` | 获取点位唯一 ID。 |
+| `getDomElement(): HTMLElement` | 获取点位对应的 DOM 元素。 |
 
 ## 使用示例
 
@@ -28,50 +125,77 @@
 import { MyOl } from 'my-openlayer';
 import MyPopup from './MyPopup.vue'; // 你的 Vue 组件
 
+const map = new MyOl('map-container');
+const vuePointManager = map.getPoint();
+
 const pointData = [
   { lgtd: 120.1, lttd: 30.2, title: '位置1', status: 'normal' },
   { lgtd: 120.2, lttd: 30.3, title: '位置2', status: 'warning' }
 ];
 
-// 添加组件点位
-const vuePoints = map.getPoint().addVueTemplatePoint(
+// 1. 添加组件点位
+const pointsController = vuePointManager.addVueTemplatePoint(
   pointData,
   MyPopup,
   {
     positioning: 'bottom-center',
-    stopEvent: true // 允许点击组件交互
+    stopEvent: true // 允许点击组件交互，阻止地图点击事件
   }
 );
 
-// 控制显示隐藏
-vuePoints.setVisible(false);
-
-// 根据属性控制
-vuePoints.setOneVisibleByProp('status', 'warning', true);
+// 2. 批量控制显示隐藏
+pointsController.setVisible(false);
+
+// 3. 根据属性控制特定点位
+pointsController.setOneVisibleByProp('status', 'warning', true);
+
+// 4. 获取单个实例进行精细控制
+const instances = pointsController.getPoints();
+if (instances.length > 0) {
+  const firstPoint = instances[0];
+  
+  // 更新位置
+  firstPoint.updatePosition(120.15, 30.25);
+  
+  // 更新 Props
+  firstPoint.updateProps({
+    pointData: { ...pointData[0], title: '更新后的标题' }
+  });
+  
+  // 添加样式类
+  firstPoint.addClass('highlight-point');
+}
 
-// 移除
-// vuePoints.remove();
+// 5. 移除这组点位
+// pointsController.remove();
 ```
 
 ### Vue 组件编写规范 (MyPopup.vue)
 
-组件会接收 `pointData` 作为 props。
+组件会接收 `pointData` 作为 props，内容为传入 `pointDataList` 中的对应数据项。
 
 ```vue
 <template>
-  <div class="popup">
+  <div class="popup" :class="pointData.status">
     <h3>{{ pointData.title }}</h3>
     <p>状态: {{ pointData.status }}</p>
+    <button @click="handleClick">详情</button>
   </div>
 </template>
 
 <script setup>
-defineProps({
+import { defineProps } from 'vue';
+
+const props = defineProps({
   pointData: {
     type: Object,
     required: true
   }
 });
+
+const handleClick = () => {
+  console.log('Clicked point:', props.pointData.title);
+};
 </script>
 
 <style scoped>
@@ -80,6 +204,11 @@ defineProps({
   padding: 10px;
   border-radius: 4px;
   box-shadow: 0 2px 10px rgba(0,0,0,0.2);
+  min-width: 150px;
+  transform: translate(-50%, -100%); /* 配合 bottom-center 定位 */
+}
+.popup.warning {
+  border: 2px solid orange;
 }
 </style>
 ```

package/docs/index.md

@@ -0,0 +1,78 @@
+# My OpenLayers
+
+My OpenLayers 是一个基于 OpenLayers 的轻量级地图封装库，旨在简化地图开发流程，提供开箱即用的常用功能。它集成了点、线、面绘制，测量工具，选择交互，Vue 组件覆盖物等功能，特别优化了 Vue 项目的集成体验。
+
+## 特性
+
+- **开箱即用**: 封装了常用的地图功能，减少样板代码。
+- **Vue 集成**: 支持使用 Vue 组件作为地图覆盖物，轻松创建复杂的交互式标记。
+- **TypeScript**: 完全使用 TypeScript 编写，提供完整的类型定义。
+- **工具丰富**: 内置测量、选择、裁剪、遮罩等实用工具。
+- **扩展性强**: 提供基础类和接口，方便二次封装和扩展。
+
+## 安装
+
+```bash
+npm install my-openlayer
+# 或者
+yarn add my-openlayer
+# 或者
+pnpm add my-openlayer
+```
+
+## 快速开始
+
+```typescript
+import { MyOl } from 'my-openlayer';
+import 'ol/ol.css'; // 引入 OpenLayers 样式
+
+// 初始化地图
+const map = new MyOl('map-container', {
+  center: [120.2, 30.3],
+  zoom: 12,
+  projection: 'EPSG:4326'
+});
+
+// 获取原生 Map 实例
+const olMap = map.map;
+
+// 添加一个点
+const point = map.getPoint();
+point.addPoint([{
+  lgtd: 120.2,
+  lttd: 30.3,
+  style: {
+    icon: 'path/to/icon.png'
+  }
+}]);
+```
+
+## 核心模块
+
+- **[MyOl](./MyOl.md)**: 核心入口类，负责地图初始化和模块管理。
+- **[Point](./Point.md)**: 点位管理，支持图标、文本、聚合等。
+- **[Line](./Line.md)**: 线条绘制，支持不同样式和动画。
+- **[Polygon](./Polygon.md)**: 多边形绘制，支持遮罩、热力图等。
+- **[VueTemplatePoint](./VueTemplatePoint.md)**: 使用 Vue 组件作为地图点位覆盖物。
+
+## 工具模块
+
+- **[MapTools](./MapTools.md)**: 通用地图工具，如裁剪、定位、导出图片等。
+- **[MeasureHandler](./MeasureHandler.md)**: 距离和面积测量工具。
+- **[SelectHandler](./SelectHandler.md)**: 要素选择交互工具。
+- **[MapBaseLayers](./MapBaseLayers.md)**: 底图切换和管理。
+
+## 基础设施
+
+- **[ConfigManager](./ConfigManager.md)**: 全局配置管理。
+- **[EventManager](./EventManager.md)**: 统一事件管理系统。
+- **[ErrorHandler](./ErrorHandler.md)**: 错误处理和日志系统。
+- **[ValidationUtils](./ValidationUtils.md)**: 参数验证工具。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License