my-openlayer 2.4.2 → 2.4.3

package/AI_CONTEXT.md

@@ -0,0 +1,147 @@
+# 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.

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## [2.4.3] - 2026-01-27
+
+### ✨ Features
+
+- 重构Polygon样式处理并添加示例组件
+- **core:** 添加基于GeoJSON数据的地图定位功能
+- **core:** 添加地图定位功能并重构点位相关方法
+- **Point:** 添加闪烁点功能及示例
+- **core:** 为Polygon添加layerName选项并调整图层添加逻辑
+- **Point:** 添加setOneVisibleByProp方法控制点显示
+- **Polygon:** 优化遮罩功能支持多几何图形处理
+- **测量工具:** 添加测量距离和面积功能及工具栏样式
+- **地图:** 添加自定义投影配置支持
+- **日志管理:** 实现统一日志开关与级别控制
+- **SelectHandler:** 新增要素选择处理器模块
+- upgrade OpenLayers to v10.6.1 and update project to v2.0.0
+- update MapBaseLayers to handle optional token and improve annotation layer management
+- 重新添加已清理的App.vue文件，移除了所有敏感token信息
+- 重构Vue模板点位功能并优化事件管理
+- **Polygon:** 改进图像图层处理逻辑并添加更新功能
+- 添加验证工具类并重构现有验证逻辑
+- **地图工具:** 重构地图工具类并增强错误处理
+- 重构类型系统并增强核心功能
+
+### 🐛 Bug Fixes
+
+- **core:** 改进Vue依赖检测逻辑并更新版本号
+- **VueTemplatePoint:** 修复Vue3环境下pointData的类型定义
+- **core:** 修正Line类中layerName属性设置错误
+- resolve TypeScript build error in MapBaseLayers.ts
+
+### ⚡ Performance
+
+- **Polygon:** 优化GeoJSON解析性能，直接注入layerName
+
+### ♻️ Refactor
+
+- **MapBaseLayers:** 重构图层管理逻辑，优化代码结构和可维护性
+- **ConfigManager:** 集中管理默认配置并移除无用接口
+- **样式处理:** 统一处理自定义样式逻辑并修复代码格式
+- 将nameKey重命名为textKey以提高语义清晰度
+- 更新依赖项并优化类型导出结构
+- **core:** 重构DomPoint和MapBaseLayers类，优化代码结构和功能
+
+### 📝 Documentation
+
+- 添加详细模块文档并更新发布配置
+- update README with branch strategy and add migration guide
+
+All notable changes to this project will be documented in this file.
+