my-openlayer 3.0.1 → 3.1.0

package/core/select/SelectHandler.js

@@ -7,7 +7,7 @@ import Collection from 'ol/Collection';
 import { getUid } from "ol/util";
 import EventManager from "../map/EventManager";
 import ValidationUtils from "../../utils/ValidationUtils";
-import { ErrorHandler, MyOpenLayersError, ErrorType } from "../../utils/ErrorHandler";
+import { ErrorHandler, ErrorType } from "../../utils/ErrorHandler";
 /**
  * 要素选择处理器类
  * 用于在地图上选择和高亮显示要素，支持单选、多选等多种选择模式
@@ -88,8 +88,7 @@ export default class SelectHandler {
             return this;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`启用要素选择失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { mode, options }));
-            throw error;
+            throw this.errorHandler.createAndHandleError(`启用要素选择失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { mode, options });
         }
     }
     /**
@@ -111,8 +110,7 @@ export default class SelectHandler {
             return this;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`禁用要素选择失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR));
-            throw error;
+            throw this.errorHandler.createAndHandleError(`禁用要素选择失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR);
         }
     }
     /**
@@ -160,8 +158,7 @@ export default class SelectHandler {
             return this;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`通过ID选择要素失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { featureIds, options }));
-            throw error;
+            throw this.errorHandler.createAndHandleError(`通过ID选择要素失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { featureIds, options });
         }
     }
     /**
@@ -170,7 +167,7 @@ export default class SelectHandler {
     selectByProperty(propertyName, propertyValue, options) {
         try {
             if (!propertyName)
-                throw new Error('属性名称不能为空');
+                throw ErrorHandler.getInstance().createAndHandleError('属性名称不能为空', ErrorType.VALIDATION_ERROR);
             const selectedFeatures = this.findFeaturesByProperty(propertyName, propertyValue, options?.layerName);
             if (selectedFeatures.length === 0)
                 return this;
@@ -178,8 +175,7 @@ export default class SelectHandler {
             return this;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`通过属性选择要素失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { propertyName, propertyValue, options }));
-            throw error;
+            throw this.errorHandler.createAndHandleError(`通过属性选择要素失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR, { propertyName, propertyValue, options });
         }
     }
     /**
@@ -344,7 +340,7 @@ export default class SelectHandler {
             this.errorHandler.debug('选择处理器已销毁');
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`销毁选择处理器失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR));
+            this.errorHandler.createAndHandleError(`销毁选择处理器失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.COMPONENT_ERROR);
         }
     }
     getSelectCondition(mode) {

package/core/vue-template-point/VueTemplatePoint.js

@@ -84,16 +84,16 @@ export default class VueTemplatePoint {
      */
     addVueTemplatePoint(pointDataList, template, options) {
         if (!pointDataList || !Array.isArray(pointDataList) || pointDataList.length === 0) {
-            throw new Error('Valid point info list is required');
+            throw ErrorHandler.getInstance().createAndHandleError('Valid point info list is required', ErrorType.VALIDATION_ERROR);
         }
         if (!template) {
-            throw new Error('Vue template is required');
+            throw ErrorHandler.getInstance().createAndHandleError('Vue template is required', ErrorType.VALIDATION_ERROR);
         }
         try {
             const instances = [];
             pointDataList.forEach((pointData) => {
                 if (!ValidationUtils.validateLngLat(pointData.lgtd, pointData.lttd)) {
-                    throw new Error('Valid longitude and latitude are required for each point');
+                    throw ErrorHandler.getInstance().createAndHandleError('Valid longitude and latitude are required for each point', ErrorType.VALIDATION_ERROR);
                 }
                 const pointOptions = {
                     Template: template,
@@ -137,7 +137,7 @@ export default class VueTemplatePoint {
             };
         }
         catch (error) {
-            throw new Error(`Failed to create Vue template points: ${error}`);
+            throw ErrorHandler.getInstance().createAndHandleError(`Failed to create Vue template points: ${error}`, ErrorType.COMPONENT_ERROR);
         }
     }
     /**
@@ -217,7 +217,7 @@ class VueTemplatePointInstanceImpl {
         const { Template, lgtd, lttd } = options;
         ValidationUtils.validateRequired(Template, 'Template is required in options');
         if (typeof lgtd !== 'number' || typeof lttd !== 'number') {
-            throw new Error('Longitude and lttd must be numbers');
+            throw ErrorHandler.getInstance().createAndHandleError('Longitude and lttd must be numbers', ErrorType.VALIDATION_ERROR);
         }
         ValidationUtils.validateCoordinate(lgtd, lttd);
     }
@@ -264,7 +264,7 @@ class VueTemplatePointInstanceImpl {
     createVueApp() {
         const { Template, props } = this.options;
         if (!Vue) {
-            throw new Error('Vue is not available. Please ensure Vue is installed in your project.');
+            throw ErrorHandler.getInstance().createAndHandleError('Vue is not available. Please ensure Vue is installed in your project.', ErrorType.COMPONENT_ERROR);
         }
         // 清空DOM内容，确保没有残留
         this.dom.innerHTML = '';
@@ -289,7 +289,7 @@ class VueTemplatePointInstanceImpl {
             }
         }
         catch (error) {
-            throw new Error(`Failed to create Vue app: ${error}`);
+            throw ErrorHandler.getInstance().createAndHandleError(`Failed to create Vue app: ${error}`, ErrorType.COMPONENT_ERROR);
         }
     }
     /**
@@ -323,7 +323,7 @@ class VueTemplatePointInstanceImpl {
      */
     setVisible(visible) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot set visibility on destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot set visibility on destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         ValidationUtils.validateType(visible, 'boolean', 'Visible parameter must be a boolean');
         try {
@@ -350,7 +350,7 @@ class VueTemplatePointInstanceImpl {
      */
     updatePosition(lgtd, lttd) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot update position on destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot update position on destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         ValidationUtils.validateCoordinate(lgtd, lttd);
         try {
@@ -376,7 +376,7 @@ class VueTemplatePointInstanceImpl {
      */
     updateProps(newProps) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot update props on destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot update props on destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         try {
             // 重新创建Vue应用实例。
@@ -409,7 +409,7 @@ class VueTemplatePointInstanceImpl {
      */
     setStyle(styles) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot set style on destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot set style on destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         try {
             Object.assign(this.dom.style, styles);
@@ -426,7 +426,7 @@ class VueTemplatePointInstanceImpl {
      */
     addClass(className) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot add class to destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot add class to destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         ValidationUtils.validateNonEmptyString(className, 'Valid class name is required');
         try {
@@ -444,7 +444,7 @@ class VueTemplatePointInstanceImpl {
      */
     removeClass(className) {
         if (this.state === VueTemplatePointState.DESTROYED) {
-            throw new Error('Cannot remove class from destroyed DOM point');
+            throw ErrorHandler.getInstance().createAndHandleError('Cannot remove class from destroyed DOM point', ErrorType.COMPONENT_ERROR);
         }
         ValidationUtils.validateNonEmptyString(className, 'Valid class name is required');
         try {

package/docs/.vitepress/config.mts

@@ -31,8 +31,7 @@ export default defineConfig({
           { text: 'Point 点要素', link: '/Point' },
           { text: 'Line 线要素', link: '/Line' },
           { text: 'Polygon 面要素', link: '/Polygon' },
-          { text: 'VueTemplatePoint Vue点位', link: '/VueTemplatePoint' },
-          { text: 'RiverLayerManager 河流图层', link: '/RiverLayerManager' }
+          { text: 'VueTemplatePoint Vue点位', link: '/VueTemplatePoint' }
         ]
       },
       {

package/docs/MIGRATION-3.0.md

@@ -117,6 +117,30 @@ const handle = await myOl.getPoint().addPulsePointLayerByUrl('/villages.json', {
 })
 ```
 
+### 2.3.1 点 API 支持 GeoJSON 直接输入
+
+3.0 点 API（`addPoint` / `addClusterPoint` / `addPulsePointLayer`）现在直接接受标准 GeoJSON 点数据，无需手动将 `FeatureCollection` 转为 `PointData[]`：
+
+```ts
+// ❌ 3.0 之前：需要手动转换
+const fc = await fetch('/stations.geojson').then(r => r.json())
+const pointData = fc.features.map(f => ({
+  ...f.properties,
+  lgtd: f.geometry.coordinates[0],
+  lttd: f.geometry.coordinates[1]
+}))
+point.addPoint(pointData, { layerName: 'stations' })
+
+// ✅ 3.0：直接传 GeoJSON
+const fc = await fetch('/stations.geojson').then(r => r.json())
+point.addPoint(fc, { layerName: 'stations' })
+
+// 也支持单个 Feature、MultiPoint geometry 等形态
+point.addPoint({ type: 'Feature', properties: { name: 'A' }, geometry: { type: 'Point', coordinates: [120, 30] } }, { layerName: 'single' })
+```
+
+`*ByUrl` 方法内部已统一使用同一套标准化逻辑，不再各自手写 JSON 映射。
+
 ### 2.4 投影注册抽到 `ProjectionManager`
 
 2.x 用 `options.projection` 注册自定义投影。3.0 仍然支持，**外加**一个独立入口：

package/docs/Point.md

@@ -22,6 +22,8 @@ constructor(map: Map)
 | img | `string` | 图标图片的 URL |
 | scale | `number` | 图标缩放比例 |
 | iconColor | `string` | 图标颜色（用于改变图标色调） |
+| circleColor | `string` | 圆点填充颜色。未设置 img 时生效，与 circleRadius 搭配绘制纯色圆点 |
+| circleRadius | `number` | 圆点半径（像素），默认 6。仅在未设置 img 时生效 |
 | layerName | `string` | 图层名称（必填，继承自 BaseOptions） |
 | zIndex | `number` | 图层层级 |
 | visible | `boolean` | 是否可见 |
@@ -72,6 +74,28 @@ constructor(map: Map)
 | lttd | `number` | 纬度 |
 | [key: string] | `any` | 其他业务数据字段 |
 
+### PointJSONInput
+
+点 API 统一输入类型。`addPoint` / `addClusterPoint` / `addPulsePointLayer` 均接受以下任意形态：
+
+```typescript
+type PointJSONInput =
+  | PointData[]                                    // 传统数组
+  | MapJSONData                                    // GeoJSON FeatureCollection
+  | FeatureData                                    // 单个 GeoJSON Feature
+  | { type: 'Point'; coordinates: number[] }       // 裸 Point geometry
+  | { type: 'MultiPoint'; coordinates: number[][] } // 裸 MultiPoint geometry
+```
+
+标准化规则：
+- `FeatureCollection` 中只提取 `Point` / `MultiPoint` 类型的 Feature，其他 geometry 类型被跳过。
+- `MultiPoint` 会被拆分为多个独立的 `PointData`。
+- GeoJSON Feature 的 `properties` 会被保留，与 `lgtd` / `lttd` 合并。
+- 坐标含 `NaN`、`Infinity` 或缺失的点会被过滤。
+- 不支持 `lng/lat`、`longitude/latitude`、`x/y` 等字段别名。
+
+> 本优化借鉴 [mapshaper](https://github.com/mbloch/mapshaper) 对地理数据输入的统一处理思路，但仅提供轻量点数据标准化能力，不包含拓扑简化、dissolve、clip/erase 等 GIS 编辑功能。
+
 ### VueTemplatePointOptions
 
 | 属性名 | 类型 | 说明 |
@@ -91,25 +115,25 @@ constructor(map: Map)
 
 ### addPoint
 
-添加普通点图层。
+添加普通点图层。支持 `PointJSONInput` 任意形态（`PointData[]`、GeoJSON FeatureCollection、Feature、裸 geometry）。
 
 ```typescript
-addPoint(pointData: PointData[], options: PointOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
+addPoint(pointData: PointJSONInput, options: PointOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
-- **pointData**: 点位数据数组。
+- **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
 - **options**: 配置选项。
 - **返回值**: `{ layer, remove(), setVisible() }` 形态的统一句柄；如果数据无效返回 `null`。
 
 ### addClusterPoint
 
-添加聚合点图层。
+添加聚合点图层。支持 `PointJSONInput` 任意形态。
 
 ```typescript
-addClusterPoint(pointData: PointData[], options: ClusterOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
+addClusterPoint(pointData: PointJSONInput, options: ClusterOptions & { layerName: string }): LayerHandle<VectorLayer<VectorSource>> | null
 ```
 
-- **pointData**: 点位数据数组。
+- **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
 - **options**: 聚合配置选项。
 - **返回值**: `{ layer, remove(), setVisible() }` 形态的统一句柄。
 
@@ -140,13 +164,13 @@ addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
 
 ### addPulsePointLayer
 
-添加高性能闪烁点图层。
+添加高性能闪烁点图层。支持 `PointJSONInput` 任意形态。
 
 ```typescript
-addPulsePointLayer(pointData: PointData[], options: PulsePointOptions): PulsePointLayerHandle | null
+addPulsePointLayer(pointData: PointJSONInput, options: PulsePointOptions & { layerName: string }): PulsePointLayerHandle | null
 ```
 
-- **pointData**: 点位数据数组。
+- **pointData**: 点位数据，支持 `PointData[]` 或标准 GeoJSON 点数据。
 - **options**: 闪烁点配置选项，复用 `addPoint` 的图标、文本和图层参数习惯。
 - **返回值**: 控制对象，包含动画启停、显隐、数据更新和移除方法；如果数据无效返回 `null`。
 
@@ -249,3 +273,34 @@ const ctrl = point.addVueTemplatePoint(data, MyComponent, {
 // 隐藏所有点
 ctrl.setVisible(false);
 ```
+
+### 使用 GeoJSON 数据添加点位
+
+从 3.0 起，点 API 直接接受标准 GeoJSON 点数据，无需手动转换：
+
+```typescript
+// 方式一：GeoJSON FeatureCollection
+const fc = {
+  type: 'FeatureCollection',
+  features: [
+    { type: 'Feature', properties: { name: '北京' }, geometry: { type: 'Point', coordinates: [116.40, 39.90] } },
+    { type: 'Feature', properties: { name: '上海' }, geometry: { type: 'Point', coordinates: [121.47, 31.23] } }
+  ]
+};
+const handle = point.addPoint(fc, { layerName: 'cities', textKey: 'name' });
+
+// 方式二：单个 Feature
+const feature = { type: 'Feature', properties: { name: '杭州' }, geometry: { type: 'Point', coordinates: [120.15, 30.27] } };
+point.addPoint(feature, { layerName: 'single-city' });
+
+// 方式三：MultiPoint Feature（自动拆分为多个点）
+const multiPoint = { type: 'Feature', properties: { region: '华东' }, geometry: { type: 'MultiPoint', coordinates: [[120, 30], [121, 31]] } };
+point.addPoint(multiPoint, { layerName: 'region' });
+
+// 闪烁点同样支持 GeoJSON 输入
+const pulseHandle = point.addPulsePointLayer(fc, {
+  layerName: 'villages',
+  levelKey: 'lev',
+  pulse: { enabled: true, radius: [8, 28] }
+});
+```

package/index.d.ts

@@ -1,8 +1,7 @@
 export { default } from './MyOl';
 export { default as MyOl } from './MyOl';
 export { Point } from './core/point';
-export { Line, RiverLayerManager } from './core/line';
-export type { RiverLayerOptions, RiverLevelWidthMap } from './core/line';
+export { Line } from './core/line';
 export { Polygon } from './core/polygon';
 export { MapBaseLayers, MapTools, MeasureHandler, ConfigManager, EventManager } from './core/map';
 export { VueTemplatePoint } from './core/vue-template-point';
@@ -12,8 +11,10 @@ export type { CustomProjectionRegistration } from './core/projection';
 export type { MapEventType, EventCallback, MapEventData } from './core/map/EventManager';
 export { ErrorHandler, MyOpenLayersError, ErrorType, LayerNotFoundError, InvalidGeoJSONError, ProjectionError } from './utils/ErrorHandler';
 export { default as ValidationUtils } from './utils/ValidationUtils';
+export { normalizePointData } from './utils/GeoJSONProcessor';
+export type { PointJSONInput } from './types';
 export type { BaseOptions, StyleOptions, TextOptions, LayerHandle, AnimatedLayerHandle } from './types';
 export type { PointOptions, LineOptions, FlowLineOptions, FlowLineLayerHandle, PolygonOptions, PulsePointOptions, PulsePointLayerHandle } from './types';
 export type { OptionsType } from './types';
-export type { MapInitType, MapLayersOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions, PointData, PulsePointIconOptions, LineData, ClusterOptions, MeasureHandlerType, VueTemplatePointOptions, VueTemplatePointInstance, TwinkleItem, MapJSONData, FeatureData, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './types';
+export type { MapInitType, MapLayersOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions, FeatureColorUpdateOptions, PointData, PulsePointIconOptions, LineData, ClusterOptions, MeasureHandlerType, VueTemplatePointOptions, VueTemplatePointInstance, TwinkleItem, MapJSONData, FeatureData, AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy, GeoJSONLayerName, AddGeoJSONPointOptions, AddGeoJSONOptions, GeoJSONGroupHandle, GeoJSONRenderHandle, AnnotationType, TiandituType, MapLayers, AnnotationLayerOptions, SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './types';
 export { VueTemplatePointState } from './types';

package/index.js

@@ -2,7 +2,7 @@
 export { default } from './MyOl';
 export { default as MyOl } from './MyOl';
 export { Point } from './core/point';
-export { Line, RiverLayerManager } from './core/line';
+export { Line } from './core/line';
 export { Polygon } from './core/polygon';
 export { MapBaseLayers, MapTools, MeasureHandler, ConfigManager, EventManager } from './core/map';
 export { VueTemplatePoint } from './core/vue-template-point';
@@ -12,5 +12,7 @@ export { ProjectionManager, PROJECTIONS } from './core/projection';
 export { ErrorHandler, MyOpenLayersError, ErrorType, LayerNotFoundError, InvalidGeoJSONError, ProjectionError } from './utils/ErrorHandler';
 // 验证工具
 export { default as ValidationUtils } from './utils/ValidationUtils';
+// GeoJSON 数据标准化
+export { normalizePointData } from './utils/GeoJSONProcessor';
 // Vue 模板点位状态枚举（运行时值，需要单独导出）
 export { VueTemplatePointState } from './types';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-openlayer",
   "private": false,
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "license": "MIT",
   "main": "index.js",

package/types/geojson.d.ts

@@ -0,0 +1,113 @@
+/**
+ * addGeoJSON 综合方法相关类型定义。
+ */
+import type { FeatureData, MapJSONData } from './common';
+import type { PointOptions } from './point';
+import type { LineOptions } from './line';
+import type { PolygonOptions } from './polygon';
+import type { LayerHandle } from './handle';
+/** *********************输入类型*********************/
+/**
+ * 裸 GeoJSON geometry 对象（非 Feature、非 FeatureCollection）。
+ */
+type GeometryLike = {
+    type: string;
+    coordinates: unknown;
+};
+/**
+ * addGeoJSON 统一输入类型。
+ * 支持单个 GeoJSON、数组、或 `{ key: json }` 对象。
+ */
+export type AddGeoJSONInput = MapJSONData | FeatureData | GeometryLike | Array<MapJSONData | FeatureData | GeometryLike> | Record<string, MapJSONData | FeatureData | GeometryLike>;
+/** *********************分组与命名类型*********************/
+/**
+ * GeoJSON 几何分类（简化为三大类）。
+ */
+export type GeoJSONGeometryType = 'point' | 'line' | 'polygon';
+/**
+ * 分组依据：属性名字符串或回调函数。
+ */
+export type GeoJSONGroupBy = string | ((properties: Record<string, unknown>, context: {
+    datasetKey: string;
+    geometryType: GeoJSONGeometryType;
+    feature: FeatureData;
+    index: number;
+}) => string | number | undefined | null);
+/**
+ * 图层命名：字符串、字符串数组、对象映射、或回调函数。
+ */
+export type GeoJSONLayerName = string | string[] | Record<string, string> | ((context: {
+    datasetKey: string;
+    groupKey: string;
+    geometryType: GeoJSONGeometryType;
+    index: number;
+}) => string);
+/** *********************选项类型*********************/
+/**
+ * addGeoJSON 点图层专用选项，扩展了 styleByProperties 回调。
+ */
+export interface AddGeoJSONPointOptions extends PointOptions {
+    /**
+     * 按 feature properties 返回不同样式选项。
+     * properties 为原始 GeoJSON Feature.properties，不包含点坐标转换产生的 lgtd/lttd。
+     * context.feature 为真实 GeoJSON Feature，context.index 为当前点分组内索引。
+     * 回调结果与 base options 合并，回调结果优先（style 字段除外）。
+     */
+    styleByProperties?: (properties: Record<string, unknown>, context: {
+        datasetKey: string;
+        groupKey: string;
+        feature: FeatureData;
+        index: number;
+    }) => Partial<PointOptions> | undefined | null;
+}
+/**
+ * addGeoJSON 方法配置选项。
+ */
+export interface AddGeoJSONOptions {
+    /** 图层命名规则。 */
+    layerName: GeoJSONLayerName;
+    /** 分组依据：属性名或回调函数。 */
+    groupBy?: GeoJSONGroupBy;
+    /** 数据坐标系。 */
+    dataProjection?: string;
+    /** 地图坐标系。 */
+    featureProjection?: string;
+    /** 是否自动缩放到数据范围。 */
+    fitView?: boolean;
+    /** 点图层选项。 */
+    point?: AddGeoJSONPointOptions;
+    /** 线图层选项。 */
+    line?: LineOptions;
+    /** 面图层选项。 */
+    polygon?: PolygonOptions;
+}
+/** *********************句柄类型*********************/
+/**
+ * 单个分组的图层句柄集合。
+ */
+export interface GeoJSONGroupHandle {
+    point: LayerHandle | null;
+    line: LayerHandle | null;
+    polygon: LayerHandle | null;
+    handles: LayerHandle[];
+    setVisible(visible: boolean): void;
+    remove(): void;
+}
+/**
+ * addGeoJSON 返回的总句柄，支持整体和按组控制。
+ */
+export interface GeoJSONRenderHandle {
+    groups: Record<string, GeoJSONGroupHandle>;
+    handles: LayerHandle[];
+    /** 按 groupKey 索引的点图层句柄，方便 handle.point[groupKey] 访问。 */
+    point: Record<string, LayerHandle | null>;
+    /** 按 groupKey 索引的线图层句柄，方便 handle.line[groupKey] 访问。 */
+    line: Record<string, LayerHandle | null>;
+    /** 按 groupKey 索引的面图层句柄，方便 handle.polygon[groupKey] 访问。 */
+    polygon: Record<string, LayerHandle | null>;
+    setVisible(visible: boolean): void;
+    setGroupVisible(groupKey: string, visible: boolean): void;
+    removeGroup(groupKey: string): void;
+    remove(): void;
+}
+export {};

package/types/geojson.js

@@ -0,0 +1,4 @@
+/**
+ * addGeoJSON 综合方法相关类型定义。
+ */
+export {};

package/types/index.d.ts

@@ -2,9 +2,10 @@ export type { BaseOptions, StyleOptions, TextOptions } from './base';
 export type { LayerHandle, AnimatedLayerHandle, ControlHandle } from './handle';
 export type { FeatureData, MapJSONData, OptionsType, MeasureHandlerType, EventType } from './common';
 export type { MapInitType, MapLayersOptions, MapLayers, AnnotationType, TiandituType, AnnotationLayerOptions, HeatMapOptions, ImageLayerData, MaskLayerOptions } from './map';
-export type { PointOptions, PointData, ClusterOptions, PulsePointIconOptions, PulsePointOptions, PulsePointLayerHandle, TwinkleItem } from './point';
+export type { PointOptions, PointData, PointJSONInput, ClusterOptions, PulsePointIconOptions, PulsePointOptions, PulsePointLayerHandle, TwinkleItem } from './point';
 export type { LineOptions, LineData, FlowLineOptions, FlowLineLayerHandle } from './line';
 export type { PolygonOptions, FeatureColorUpdateOptions } from './polygon';
+export type { AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy, GeoJSONLayerName, AddGeoJSONPointOptions, AddGeoJSONOptions, GeoJSONGroupHandle, GeoJSONRenderHandle } from './geojson';
 export type { SelectOptions, SelectMode, SelectCallbackEvent, ProgrammaticSelectOptions } from './select';
 export type { VueInstance, VueApp, VueLegacyInstance, VueTemplatePointOptions, VueTemplatePointInstance } from './vue-template-point';
 export { VueTemplatePointState } from './vue-template-point';

package/types/point.d.ts

@@ -2,17 +2,30 @@ import VectorLayer from "ol/layer/Vector";
 import VectorSource from "ol/source/Vector";
 import type { BaseOptions, StyleOptions, TextOptions } from "./base";
 import type { AnimatedLayerHandle } from "./handle";
+import type { FeatureData, MapJSONData } from "./common";
 export interface PointOptions extends BaseOptions, StyleOptions, TextOptions {
     textKey?: string;
     img?: string;
     scale?: number;
     iconColor?: string;
+    /** 圆点填充颜色。未设置 img 时生效，与 circleRadius 搭配绘制纯色圆点。 */
+    circleColor?: string;
+    /** 圆点半径（像素），默认 6。仅在未设置 img 时生效。 */
+    circleRadius?: number;
 }
 export interface PointData {
     lgtd: number;
     lttd: number;
     [key: string]: unknown;
 }
+/** *********************点 JSON 统一输入类型*********************/
+export type PointJSONInput = PointData[] | MapJSONData | FeatureData | {
+    type: 'Point';
+    coordinates: number[];
+} | {
+    type: 'MultiPoint';
+    coordinates: number[][];
+};
 export interface ClusterOptions extends PointOptions {
     distance?: number;
     minDistance?: number;

package/utils/GeoJSONProcessor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * GeoJSON 数据标准化工具。
+ *
+ * 本模块借鉴 mapshaper 对地理数据输入的统一处理思路，
+ * 但仅提供轻量的点数据标准化能力，不包含拓扑简化、dissolve、clip/erase 等 GIS 编辑功能。
+ * 参见 https://github.com/mbloch/mapshaper (MPL-2.0, Node >=20.11)。
+ */
+import type { PointData, PointJSONInput } from '../types';
+import type { FeatureData } from '../types';
+import type { AddGeoJSONInput, GeoJSONGeometryType, GeoJSONGroupBy } from '../types';
+/** *********************类型定义*********************/
+/**
+ * 点 API 统一输入类型。
+ * 支持 PointData 数组、GeoJSON FeatureCollection、单个 Feature、
+ * 以及裸 GeoJSON Point / MultiPoint geometry 对象。
+ */
+export type { PointJSONInput };
+/** *********************公开 API*********************/
+/**
+ * 将多种形态的点数据输入统一标准化为 `PointData[]`。
+ *
+ * 支持的输入形态：
+ * - `PointData[]`：原样返回（深拷贝后过滤非法坐标）
+ * - GeoJSON `FeatureCollection`：遍历 features，提取 Point / MultiPoint geometry
+ * - 单个 GeoJSON `Feature`：提取其 Point 或 MultiPoint geometry
+ * - 裸 `Point` geometry：转为单元素 PointData 数组
+ * - 裸 `MultiPoint` geometry：拆成多个 PointData
+ *
+ * 过滤规则：
+ * - 非 Point / MultiPoint geometry 的 Feature 会被跳过
+ * - 坐标含 NaN / Infinity / 缺失的点会被跳过
+ * - null / undefined 输入返回空数组
+ *
+ * @param input 任意兼容的点数据输入
+ * @returns 标准化后的 PointData 数组
+ */
+export declare function normalizePointData(input: PointJSONInput | null | undefined): PointData[];
+/** *********************GeoJSON 分组处理*********************/
+/**
+ * 将 GeoJSON geometry 类型归类为简化的三大类。
+ * 无法识别的类型返回 null。
+ */
+export declare function classifyGeometryType(geometryType: string): GeoJSONGeometryType | null;
+/**
+ * 将 addGeoJSON 的多种输入形态统一标准化为带 datasetKey 的 FeatureData 数组。
+ *
+ * - 单个 JSON → datasetKey 为 `'default'`
+ * - 数组 → datasetKey 为字符串索引 `'0'`, `'1'`, ...
+ * - `Record<string, json>` → datasetKey 为 key
+ */
+export declare function normalizeGeoJSONInputs(data: AddGeoJSONInput | null | undefined): Array<{
+    datasetKey: string;
+    features: FeatureData[];
+}>;
+/**
+ * 按 groupBy 和几何类型将 FeatureData 拆分到不同分组。
+ *
+ * - 未配置 groupBy 时，每个 datasetKey 成为一个组
+ * - 配置 groupBy 字符串时，从 properties 中取该字段值作为 groupKey
+ * - 配置 groupBy 回调时，调用回调获取 groupKey
+ * - groupKey 取不到时回退到 datasetKey
+ */
+/**
+ * 附加了 datasetKey 元数据的 FeatureData。
+ * 用于在 splitByGroupAndGeometry 后保留每个 feature 来源信息。
+ */
+export type FeatureWithDatasetKey = FeatureData & {
+    _datasetKey: string;
+};
+export declare function splitByGroupAndGeometry(normalized: Array<{
+    datasetKey: string;
+    features: FeatureData[];
+}>, groupBy?: GeoJSONGroupBy): Record<string, {
+    point: FeatureWithDatasetKey[];
+    line: FeatureWithDatasetKey[];
+    polygon: FeatureWithDatasetKey[];
+}>;