my-openlayer 2.4.7 → 2.4.9

package/docs/VueTemplatePoint.md

@@ -1,85 +1,214 @@
-# VueTemplatePoint Vue 组件点位类
-
-`VueTemplatePoint` 允许将 Vue 组件直接渲染为地图上的点位覆盖物（Overlay），支持 Vue 2 和 Vue 3。
-
-## 方法
-
-- **addVueTemplatePoint(pointDataList: any[], template: any, options?)**: 添加 Vue 组件点位。
-  - `pointDataList`: 点位数据列表。
-  - `template`: Vue 组件对象。
-  - `options`:
-    - `positioning`: 覆盖物定位点（如 `'center-center'`）。
-    - `stopEvent`: 是否阻止事件冒泡。
-
-### 返回值
-
-该方法返回一个控制对象，包含以下方法：
-
-- **setVisible(visible: boolean)**: 设置所有点位的可见性。
-- **setOneVisibleByProp(propName: string, propValue: any, visible: boolean)**: 根据属性值控制特定点位的可见性。
-- **remove()**: 移除所有点位并销毁组件实例。
-- **getPoints()**: 获取底层点位实例列表。
-
-## 使用示例
-
-### Vue 3 示例
-
-```typescript
-import { MyOl } from 'my-openlayer';
-import MyPopup from './MyPopup.vue'; // 你的 Vue 组件
-
-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(
-  pointData,
-  MyPopup,
-  {
-    positioning: 'bottom-center',
-    stopEvent: true // 允许点击组件交互
-  }
-);
-
-// 控制显示隐藏
-vuePoints.setVisible(false);
-
-// 根据属性控制
-vuePoints.setOneVisibleByProp('status', 'warning', true);
-
-// 移除
-// vuePoints.remove();
-```
-
-### Vue 组件编写规范 (MyPopup.vue)
-
-组件会接收 `pointData` 作为 props。
-
-```vue
-<template>
-  <div class="popup">
-    <h3>{{ pointData.title }}</h3>
-    <p>状态: {{ pointData.status }}</p>
-  </div>
-</template>
-
-<script setup>
-defineProps({
-  pointData: {
-    type: Object,
-    required: true
-  }
-});
-</script>
-
-<style scoped>
-.popup {
-  background: white;
-  padding: 10px;
-  border-radius: 4px;
-  box-shadow: 0 2px 10px rgba(0,0,0,0.2);
-}
-</style>
-```
+# VueTemplatePoint Vue 组件点位类
+
+`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
+
+添加一组 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
+
+获取所有管理的点位实例。
+
+```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 元素。 |
+
+## 使用示例
+
+### Vue 3 示例
+
+```typescript
+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' }
+];
+
+// 1. 添加组件点位
+const pointsController = vuePointManager.addVueTemplatePoint(
+  pointData,
+  MyPopup,
+  {
+    positioning: 'bottom-center',
+    stopEvent: 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');
+}
+
+// 5. 移除这组点位
+// pointsController.remove();
+```
+
+### Vue 组件编写规范 (MyPopup.vue)
+
+组件会接收 `pointData` 作为 props，内容为传入 `pointDataList` 中的对应数据项。
+
+```vue
+<template>
+  <div class="popup" :class="pointData.status">
+    <h3>{{ pointData.title }}</h3>
+    <p>状态: {{ pointData.status }}</p>
+    <button @click="handleClick">详情</button>
+  </div>
+</template>
+
+<script setup>
+import { defineProps } from 'vue';
+
+const props = defineProps({
+  pointData: {
+    type: Object,
+    required: true
+  }
+});
+
+const handleClick = () => {
+  console.log('Clicked point:', props.pointData.title);
+};
+</script>
+
+<style scoped>
+.popup {
+  background: white;
+  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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "2.4.7",
+  "version": "2.4.9",
   "type": "module",
   "license": "MIT",
   "main": "index.js",
@@ -20,13 +20,12 @@
   "bugs": {
     "url": "https://github.com/cuteyuchen/my-openlayer/issues"
   },
-  "homepage": "https://github.com/cuteyuchen/my-openlayer#readme",
+  "homepage": "https://cuteyuchen.github.io/my-openlayer/",
   "files": [
     "**/*",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
-    "AI_CONTEXT.md",
     "docs",
     "package.json"
   ],
@@ -36,7 +35,10 @@
     "preview": "vite preview",
     "prepare-publish": "node scripts/prepare-publish.cjs",
     "publish-flat": "npm run build && npm run prepare-publish && cd temp-publish && npm publish",
-    "publish-flat-dry": "npm run build && npm run prepare-publish && cd temp-publish && npm publish --dry-run"
+    "publish-flat-dry": "npm run build && npm run prepare-publish && cd temp-publish && npm publish --dry-run",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
     "@turf/turf": "^7.2.0",
@@ -50,6 +52,7 @@
     "vite": "^5.4.10",
     "vite-plugin-css-modules": "^0.0.1",
     "vite-plugin-libcss": "^1.1.1",
+    "vitepress": "^1.6.4",
     "vue-tsc": "^2.0.6"
   },
   "peerDependencies": {

package/types.d.ts

@@ -236,6 +236,8 @@ export interface ClusterOptions extends PointOptions {
  */
 export interface TwinkleItem extends PointData {
     className?: string;
+    /** 自定义DOM元素，可以是HTMLElement或者返回HTMLElement的函数 */
+    element?: HTMLElement | ((item: TwinkleItem) => HTMLElement);
     [key: string]: any;
 }
 /**

package/AI_CONTEXT.md

@@ -1,147 +0,0 @@
-# AI Context for my-openlayer
-
-Use this context to understand how to use the `my-openlayer` library.
-
-## Project Overview
-
-`my-openlayer` is a modern map component library based on OpenLayers, designed for Web GIS applications. It provides a modular, TypeScript-ready wrapper around OpenLayers features.
-
-- **Core Dependency**: `ol` (OpenLayers)
-- **Key Features**: Map initialization, Tianditu (天地图) support, Point/Line/Polygon management, Event handling, Selection, Measurement, Vue component markers.
-
-## Core Architecture
-
-- **MyOl**: The main entry class. Initializes the map and provides access to sub-modules.
-- **Modules** (Lazy loaded via getters):
-  - `MapBaseLayers`: Base map switching (Vector, Image, Terrain) and Annotation layers.
-  - `Point`: Point features, clusters, DOM markers.
-  - `Line`: Line features, river layers.
-  - `Polygon`: Polygon features, heatmaps, image layers, masks.
-  - `MapTools`: General tools (Zoom, Fit, Layer management).
-  - `MeasureHandler`: Distance and Area measurement.
-  - `SelectHandler`: Feature selection interaction.
-  - `EventManager`: Unified event listener management.
-- **Utils**: `ConfigManager`, `ErrorHandler`, `ValidationUtils`.
-
-## Quick Start (Minimal Example)
-
-```typescript
-import MyOl, { MapInitType } from 'my-openlayer';
-
-// 1. Configuration
-const config: MapInitType = {
-  target: 'map-container', // ID of the DIV
-  center: [119.81, 29.969], // [Longitude, Latitude]
-  zoom: 10,
-  token: 'YOUR_TIANDITU_TOKEN', // Required for Tianditu base maps
-  annotation: true // Show annotation layer by default
-};
-
-// 2. Initialize
-const map = new MyOl('map-container', config);
-
-// 3. Access Modules & Add Features
-map.getPoint().addPoint([{ lgtd: 119.81, lttd: 29.969, name: 'Demo' }], {
-  layerName: 'demo-layer',
-  img: 'marker.png'
-});
-```
-
-## API Reference (Condensed)
-
-### `MyOl` (Main Class)
-- `constructor(id: string | HTMLElement, options?: MapInitType)`
-- `getPoint()`: Returns `Point` instance.
-- `getLine()`: Returns `Line` instance.
-- `getPolygon()`: Returns `Polygon` instance.
-- `getMapBaseLayers()`: Returns `MapBaseLayers` instance.
-- `getTools()`: Returns `MapTools` instance.
-- `getSelectHandler()`: Returns `SelectHandler` instance.
-- `getEventManager()`: Returns `EventManager` instance.
-- `locationAction(lon, lat, zoom, duration)`: Animate to location.
-
-### `MapBaseLayers`
-- `switchBaseLayer(type: 'vec_c' | 'img_c' | 'ter_c')`: Switch base map.
-- `setAnnotationVisible(visible: boolean)`: Toggle text annotations.
-- `addGeoServerLayer(url, layerName, options)`: Add WMS layer.
-
-### `Point`
-- `addPoint(data: PointData[], options: PointOptions)`: Add markers.
-- `addClusterPoint(data, options)`: Add clustered markers.
-- `addVueTemplatePoint(data, Component, options)`: Use Vue component as marker.
-
-### `Line`
-- `addLine(geoJson, options)`: Add lines from GeoJSON.
-- `addLineByUrl(url, options)`: Load GeoJSON from URL.
-
-### `Polygon`
-- `addPolygon(geoJson, options)`: Add polygons.
-- `addBorderPolygon(geoJson, options)`: Add boundary lines.
-- `updateFeatureColor(layerName, colorMap, options)`: Update colors dynamically.
-- `addHeatmap(data, options)`: Add heatmap.
-
-### `SelectHandler`
-- `enableSelect(mode: 'click'|'hover', options)`: Enable selection.
-- `selectByIds(ids, options)`: Programmatic selection.
-
-### `MeasureHandler`
-- **Important**: Must be instantiated manually if not exposed via `MyOl`.
-- `new MeasureHandler(map.map)`
-- `start('LineString' | 'Polygon')`
-- `end()`, `clean()`
-
-## Key Type Definitions (TypeScript)
-
-Use these interfaces to ensure type safety.
-
-```typescript
-export interface MapInitType {
-  layers?: LayerItem[] | { [key: string]: LayerItem[] };
-  zoom?: number;
-  center?: number[]; // [lon, lat]
-  minZoom?: number;
-  maxZoom?: number;
-  token?: string; // Tianditu Token
-  annotation?: boolean;
-}
-
-export interface BaseOptions {
-  layerName?: string;
-  zIndex?: number;
-  visible?: boolean;
-  opacity?: number;
-}
-
-export interface PointOptions extends BaseOptions {
-  textKey?: string; // Property key for label text
-  img?: string; // Icon URL
-  scale?: number;
-  textFillColor?: string;
-}
-
-export interface PointData {
-  lgtd: number;
-  lttd: number;
-  [key: string]: any;
-}
-
-export interface LineOptions extends BaseOptions {
-  strokeColor?: string;
-  strokeWidth?: number;
-  lineDash?: number[];
-}
-
-export interface PolygonOptions extends BaseOptions {
-  fillColor?: string;
-  strokeColor?: string;
-  textKey?: string;
-}
-```
-
-## Best Practices
-
-1.  **Use Modules**: Access functionality through `map.getPoint()`, `map.getLine()`, etc., rather than manipulating the `ol.Map` directly when possible.
-2.  **Layer Names**: Always provide a unique `layerName` in options to easily retrieve or remove layers later (`map.getTools().removeLayer('my-layer')`).
-3.  **Coordinate System**: The library defaults to `EPSG:4326` (WGS84) for input coordinates (lon/lat) and `CGCS2000` internally where applicable.
-4.  **Vue Integration**: Use `addVueTemplatePoint` for complex markers requiring interactivity or dynamic content.
-5.  **Event Handling**: Use `map.getEventManager().on('click', ...)` instead of native listeners for better management.