my-openlayer 2.4.7 → 2.4.9

package/docs/Point.md

@@ -1,58 +1,165 @@
-# 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);
-```
+# Point 类
+
+`Point` 类用于在地图上添加和管理点要素，支持普通点、聚合点、DOM 点和 Vue 组件点。
+
+## 构造函数
+
+```typescript
+constructor(map: Map)
+```
+
+- **map**: OpenLayers 地图实例。
+
+## 接口定义
+
+### PointOptions
+
+继承自 `BaseOptions`, `StyleOptions`, `TextOptions`。
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| textKey | `string` | 数据中用于显示文本的字段键名 |
+| img | `string` | 图标图片的 URL |
+| scale | `number` | 图标缩放比例 |
+| iconColor | `string` | 图标颜色（用于改变图标色调） |
+| layerName | `string` | 图层名称（必填，继承自 BaseOptions） |
+| zIndex | `number` | 图层层级 |
+| visible | `boolean` | 是否可见 |
+| style | `Style \| Style[] \| ((feature: FeatureLike) => Style \| Style[])` | 自定义样式函数 |
+
+### ClusterOptions
+
+继承自 `PointOptions`。
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| distance | `number` | 聚合距离（像素），默认为 20 |
+| minDistance | `number` | 最小聚合距离 |
+
+### PointData
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| lgtd | `number` | 经度 |
+| lttd | `number` | 纬度 |
+| [key: string] | `any` | 其他业务数据字段 |
+
+### VueTemplatePointOptions
+
+| 属性名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| Template | `any` | Vue 组件模板 |
+| lgtd | `number` | 经度 |
+| lttd | `number` | 纬度 |
+| props | `any` | 传递给组件的 props |
+| styleType | `'default' \| 'custom'` | 样式类型 |
+| positioning | `string` | 定位方式，如 'bottom-center' |
+| stopEvent | `boolean` | 是否阻止事件冒泡 |
+| visible | `boolean` | 是否可见 |
+| className | `string` | 自定义类名 |
+| zIndex | `number` | 层级 |
+
+## 方法
+
+### addPoint
+
+添加普通点图层。
+
+```typescript
+addPoint(pointData: PointData[], options: PointOptions): VectorLayer<VectorSource> | null
+```
+
+- **pointData**: 点位数据数组。
+- **options**: 配置选项。
+- **返回值**: 创建的向量图层，如果数据无效返回 `null`。
+
+### addClusterPoint
+
+添加聚合点图层。
+
+```typescript
+addClusterPoint(pointData: PointData[], options: ClusterOptions): VectorLayer<VectorSource> | null
+```
+
+- **pointData**: 点位数据数组。
+- **options**: 聚合配置选项。
+- **返回值**: 创建的聚合图层。
+
+### addDomPoint
+
+添加 DOM 元素点（Overlay）。
+
+```typescript
+addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
+  anchors: Overlay[],
+  remove: () => void,
+  setVisible: (visible: boolean) => void
+}
+```
+
+- **twinkleList**: 包含经纬度和类名的数据列表。
+- **callback**: 点击回调函数。
+- **返回值**: 控制对象，包含 `remove` 和 `setVisible` 方法。
+
+### addVueTemplatePoint
+
+添加 Vue 组件作为点位。
+
+```typescript
+addVueTemplatePoint(pointDataList: PointData[], template: any, options?: VueTemplatePointOptions): {
+  setVisible: (visible: boolean) => void,
+  setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void,
+  remove: () => void,
+  getPoints: () => VueTemplatePointInstance[]
+}
+```
+
+- **pointDataList**: 点位数据列表。
+- **template**: Vue 组件。
+- **options**: 配置选项。
+- **返回值**: 控制对象，包含显示/隐藏和移除方法。
+
+## 使用示例
+
+### 添加普通点
+
+```typescript
+import { Point } from 'my-openlayers';
+
+const point = new Point(map);
+const data = [
+  { lgtd: 116.40, lttd: 39.90, name: '北京' },
+  { lgtd: 121.47, lttd: 31.23, name: '上海' }
+];
+
+point.addPoint(data, {
+  layerName: 'cities',
+  img: 'path/to/icon.png',
+  textKey: 'name',
+  scale: 0.8
+});
+```
+
+### 添加聚合点
+
+```typescript
+point.addClusterPoint(data, {
+  layerName: 'clusters',
+  distance: 40,
+  img: 'path/to/cluster-icon.png'
+});
+```
+
+### 添加 Vue 组件点
+
+```typescript
+import MyComponent from './MyComponent.vue';
+
+const ctrl = point.addVueTemplatePoint(data, MyComponent, {
+  positioning: 'bottom-center',
+  props: { status: 'active' }
+});
+
+// 隐藏所有点
+ctrl.setVisible(false);
+```

package/docs/Polygon.md

@@ -1,65 +1,241 @@
-# 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' // 权重字段
-});
-```
+# Polygon 面要素类
+
+`Polygon` 类用于在地图上绘制面要素、热力图、图片图层和遮罩层，支持丰富的数据可视化功能。
+
+## 构造函数
+
+```typescript
+const polygon = new Polygon(map: Map);
+```
+
+- **map**: OpenLayers 地图实例。
+
+## 接口定义
+
+### PolygonOptions
+
+面图层配置项，继承自 `BaseOptions`, `StyleOptions`, `TextOptions`。
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| **基础配置** | | |
+| `layerName` | `string` | 图层名称 |
+| `zIndex` | `number` | 图层层级 |
+| `visible` | `boolean` | 是否可见 |
+| `opacity` | `number` | 透明度 (0-1) |
+| `fitView` | `boolean` | 是否自动缩放视图 |
+| **样式配置** | | |
+| `fillColor` | `string` | 填充颜色 |
+| `fillColorCallBack` | `(feature) => string` | 动态填充颜色回调 |
+| `strokeColor` | `string` | 边框颜色 |
+| `strokeWidth` | `number` | 边框宽度 |
+| `lineDash` | `number[]` | 边框虚线样式 |
+| **文本标注** | | |
+| `textVisible` | `boolean` | 是否显示文本 |
+| `textKey` | `string` | 文本对应的属性字段名 |
+| `textCallBack` | `(feature) => string` | 文本回调函数（优先级高于 textKey） |
+| `textFont` | `string` | 字体样式 |
+| `textFillColor` | `string` | 文本颜色 |
+| `textStrokeColor` | `string` | 文本描边颜色 |
+| **其他** | | |
+| `mask` | `boolean` | 是否作为蒙版（配合 `setOutLayer` 使用） |
+
+### HeatMapOptions
+
+热力图配置项。
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `layerName` | `string` | 图层名称 |
+| `radius` | `number` | 热点半径，默认 8 |
+| `blur` | `number` | 模糊度，默认 15 |
+| `gradient` | `string[]` | 颜色渐变数组 |
+| `opacity` | `number` | 透明度 |
+| `valueKey` | `string` | 权重字段名，默认 'value' |
+
+### ImageLayerData
+
+图片图层数据。
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `img` | `string` | 图片 URL |
+| `extent` | `number[]` | 图片覆盖范围 `[minX, minY, maxX, maxY]` |
+
+## 方法
+
+### addPolygon
+
+添加多边形图层。
+
+```typescript
+addPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `data` | `MapJSONData` | GeoJSON 数据 |
+| `options` | `PolygonOptions` | 配置项 |
+
+### addPolygonByUrl
+
+从 URL 加载多边形图层。
+
+```typescript
+addPolygonByUrl(url: string, options?: PolygonOptions): VectorLayer<VectorSource>
+```
+
+### addBorderPolygon
+
+添加边界图层（通常用于行政区划边界，支持镂空效果）。
+
+```typescript
+addBorderPolygon(data: MapJSONData, options?: PolygonOptions): VectorLayer<VectorSource>
+```
+
+### updateFeatureColor
+
+动态更新面要素颜色，常用于数据可视化展示。
+
+```typescript
+updateFeatureColor(
+  layerName: string, 
+  colorObj?: { [propName: string]: string }, 
+  options?: FeatureColorUpdateOptions
+): void
+```
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `layerName` | `string` | 目标图层名称 |
+| `colorObj` | `Object` | 颜色映射对象 `{ '区域名': '颜色值' }` |
+| `options` | `FeatureColorUpdateOptions` | 包含 textKey 等配置以匹配要素 |
+
+### addImageLayer
+
+添加静态图片图层（如叠加平面图、卫星图）。
+
+```typescript
+addImageLayer(imageData: ImageLayerData, options?: PolygonOptions): ImageLayer<any>
+```
+
+### addHeatmap
+
+添加热力图。
+
+```typescript
+addHeatmap(pointData: PointData[], options?: HeatMapOptions): Heatmap
+```
+
+### setOutLayer
+
+添加遮罩图层（反向裁剪，只高亮指定区域，遮挡外部）。
+
+```typescript
+setOutLayer(data: MapJSONData, options?: {
+  layerName?: string,
+  extent?: any,
+  fillColor?: string,
+  strokeWidth?: number,
+  strokeColor?: string,
+  zIndex?: number
+}): VectorLayer<VectorSource>
+```
+
+## 使用示例
+
+### 基础多边形
+
+```typescript
+const polygonModule = map.getPolygon();
+
+// GeoJSON 数据
+const polygonData = {
+  type: 'FeatureCollection',
+  features: [
+    {
+      type: 'Feature',
+      geometry: {
+        type: 'Polygon',
+        coordinates: [[[120, 30], [121, 30], [121, 31], [120, 31], [120, 30]]]
+      },
+      properties: { name: '区域A', value: 100 }
+    }
+  ]
+};
+
+// 添加半透明蓝色填充、蓝色边框的多边形
+polygonModule.addPolygon(polygonData, {
+  layerName: 'area-layer',
+  fillColor: 'rgba(0, 0, 255, 0.1)',
+  strokeColor: 'blue',
+  strokeWidth: 2,
+  textKey: 'name', // 显示名称
+  textFillColor: '#fff',
+  textStrokeColor: 'blue',
+  textStrokeWidth: 2,
+  fitView: true
+});
+```
+
+### 数据可视化（动态填色）
+
+```typescript
+// 假设 'area-layer' 中的要素有 'name' 属性
+// 我们将 '区域A' 设为红色，其他区域保持默认或设为其他颜色
+polygonModule.updateFeatureColor(
+  'area-layer',
+  {
+    '区域A': 'rgba(255, 0, 0, 0.5)',
+    '区域B': 'rgba(0, 255, 0, 0.5)'
+  },
+  { 
+    textKey: 'name', // 匹配 colorObj 的键
+    strokeColor: '#666', // 统一更新边框颜色
+    strokeWidth: 1
+  }
+);
+```
+
+### 热力图
+
+```typescript
+const heatPoints = [
+  { lgtd: 119.8, lttd: 29.9, value: 100 },
+  { lgtd: 119.9, lttd: 30.0, value: 50 },
+  // ... 更多点
+];
+
+polygonModule.addHeatmap(heatPoints, {
+  layerName: 'heatmap-layer',
+  radius: 20,       // 热点半径
+  blur: 15,         // 边缘模糊
+  valueKey: 'value', // 权重字段
+  gradient: ['#00f', '#0ff', '#0f0', '#ff0', '#f00'] // 自定义渐变色
+});
+```
+
+### 图片图层
+
+```typescript
+// 将图片叠加到指定经纬度范围
+polygonModule.addImageLayer({
+  img: 'https://example.com/plan.png',
+  extent: [120.0, 30.0, 120.1, 30.1] // [minX, minY, maxX, maxY]
+}, {
+  layerName: 'image-overlay',
+  opacity: 0.8
+});
+```
+
+### 遮罩层（反向裁剪）
+
+```typescript
+// 添加遮罩，除了 polygonData 覆盖的区域外，其他区域都会被遮挡
+polygonModule.setOutLayer(polygonData, {
+  layerName: 'mask-layer',
+  fillColor: 'rgba(0, 0, 0, 0.5)', // 黑色半透明遮罩
+  strokeColor: '#fff',
+  strokeWidth: 2
+});
+```