my-openlayer 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [3.1.0] - 2026-06-09
+
+### Features
+
+- **GeoJSON:** 新增 `MyOl.addGeoJSON(data, options)` 综合渲染入口，自动识别点、线、面几何类型并返回统一 `GeoJSONRenderHandle`。
+- **GeoJSON:** 支持单个 GeoJSON、数组、Record 多数据集输入，并支持 `layerName` 使用字符串、数组、Record 或回调自定义。
+- **GeoJSON:** 支持 `groupBy` 分组渲染，以及点要素 `styleByProperties` 按 `properties` 返回逐要素样式。
+- **Point:** `addPoint`、`addClusterPoint`、`addPulsePointLayer` 支持直接传入 GeoJSON 点数据。
+
+### Bug Fixes
+
+- **ErrorHandler:** 修复 `MyOpenLayersError` 被外层 `catch` 二次包装的问题，避免错误类型被覆盖和错误回调重复触发。
+
+### Documentation
+
+- 更新 README、VitePress 文档和 `skills/my-openlayer-helper`，同步 GeoJSON 综合渲染、点 API GeoJSON 输入和统一错误类型说明。
+
+### Tests
+
+- 新增 GeoJSON 渲染、点 GeoJSON 输入、GeoJSON 处理器和错误处理回归测试。
+
 ## [3.0.0] - 2026-05-22
 
 ### 🚀 BREAKING CHANGE: 总览

package/MyOl.d.ts

@@ -7,6 +7,7 @@ import { MapBaseLayers, MapTools, EventManager, ConfigManager } from "./core/map
 import { SelectHandler } from "./core/select";
 import { ErrorHandler } from './utils/ErrorHandler';
 import { MapInitType } from './types';
+import type { AddGeoJSONInput, AddGeoJSONOptions, GeoJSONRenderHandle } from './types';
 /**
  * MyOl 地图核心类
  * 提供完整的地图操作功能，包括点、线、面要素管理，底图切换，工具操作等
@@ -101,11 +102,23 @@ export default class MyOl {
      * @param latitude 纬度
      * @param zoom 缩放级别
      * @param duration 动画持续时间（毫秒）
+     * @param projection
      */
     locationAction(longitude: number, latitude: number, zoom?: number, duration?: number, projection?: {
         dataProjection?: string;
         featureProjection?: string;
     }): void;
+    /**
+     * 综合 GeoJSON 渲染方法。
+     *
+     * 自动识别点/线/面几何类型，按分组创建图层，返回统一句柄。
+     * 支持单个 GeoJSON、GeoJSON 数组、或 `{ key: json }` 对象。
+     *
+     * @param data GeoJSON 输入数据
+     * @param options 配置选项（含 layerName、groupBy、各类型样式）
+     * @returns GeoJSONRenderHandle 统一句柄
+     */
+    addGeoJSON(data: AddGeoJSONInput, options: AddGeoJSONOptions): GeoJSONRenderHandle;
     /**
      * 获取错误处理器实例
      * @returns ErrorHandler 错误处理器

package/MyOl.js

@@ -11,7 +11,8 @@ import { Line } from "./core/line";
 import { MapBaseLayers, MapTools, EventManager, ConfigManager } from "./core/map";
 import { SelectHandler } from "./core/select";
 import { ProjectionManager } from "./core/projection";
-import { ErrorHandler, MyOpenLayersError, ErrorType } from './utils/ErrorHandler';
+import { ErrorHandler, ErrorType, MyOpenLayersError } from './utils/ErrorHandler';
+import { renderGeoJSON } from './core/geojson';
 /**
  * MyOl 地图核心类
  * 提供完整的地图操作功能，包括点、线、面要素管理，底图切换，工具操作等
@@ -56,8 +57,11 @@ class MyOl {
             this.initializeEventListeners();
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`地图初始化失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { id, options }));
-            throw error;
+            // 已处理过的 MyOpenLayersError 直接抛出，避免二次包装和重复触发回调
+            if (error instanceof MyOpenLayersError) {
+                throw error;
+            }
+            throw this.errorHandler.createAndHandleError(`地图初始化失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { id, options });
         }
     }
     /**
@@ -66,18 +70,18 @@ class MyOl {
      */
     validateConstructorParams(id, options) {
         if (!id) {
-            throw new Error('地图容器 ID 或 HTMLElement 不能为空');
+            throw ErrorHandler.getInstance().createAndHandleError('地图容器 ID 或 HTMLElement 不能为空', ErrorType.VALIDATION_ERROR);
         }
         if (typeof id === 'string' && id.trim() === '') {
-            throw new Error('地图容器 ID 必须是非空字符串');
+            throw ErrorHandler.getInstance().createAndHandleError('地图容器 ID 必须是非空字符串', ErrorType.VALIDATION_ERROR);
         }
         if (!options || typeof options !== 'object') {
-            throw new Error('地图配置选项不能为空');
+            throw ErrorHandler.getInstance().createAndHandleError('地图配置选项不能为空', ErrorType.VALIDATION_ERROR);
         }
         // 检查 DOM 元素是否存在
         const element = typeof id === 'string' ? document.getElementById(id) : id;
         if (!element) {
-            throw new Error(typeof id === 'string' ? `找不到 ID 为 '${id}' 的 DOM 元素` : '提供的 DOM 元素无效');
+            throw ErrorHandler.getInstance().createAndHandleError(typeof id === 'string' ? `找不到 ID 为 '${id}' 的 DOM 元素` : '提供的 DOM 元素无效', ErrorType.VALIDATION_ERROR);
         }
     }
     /**
@@ -103,7 +107,7 @@ class MyOl {
         }, { once: true });
         // 地图错误事件
         eventManager.on('error', (eventData) => {
-            this.errorHandler.handleError(new MyOpenLayersError('地图渲染错误', ErrorType.MAP_ERROR, { error: eventData.error }));
+            this.errorHandler.createAndHandleError('地图渲染错误', ErrorType.MAP_ERROR, { error: eventData.error });
         });
     }
     /**
@@ -128,7 +132,11 @@ class MyOl {
             return new View(viewOptions);
         }
         catch (error) {
-            throw new MyOpenLayersError(`视图创建失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { options });
+            // 已处理过的 MyOpenLayersError 直接抛出，避免二次包装和重复触发回调
+            if (error instanceof MyOpenLayersError) {
+                throw error;
+            }
+            throw ErrorHandler.getInstance().createAndHandleError(`视图创建失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { options });
         }
     }
     /**
@@ -155,8 +163,9 @@ class MyOl {
             return this._polygon;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('面要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('面要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     /**
@@ -184,8 +193,9 @@ class MyOl {
             return this._baseLayers;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('基础图层模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('基础图层模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     /**
@@ -201,8 +211,9 @@ class MyOl {
             return this._point;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('点要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('点要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     /**
@@ -218,8 +229,9 @@ class MyOl {
             return this._line;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('线要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('线要素模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     /**
@@ -235,8 +247,9 @@ class MyOl {
             return this._selectHandler;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('要素选择模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('要素选择模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     /**
@@ -252,8 +265,9 @@ class MyOl {
             return this._mapTools;
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError('工具模块初始化失败', ErrorType.COMPONENT_ERROR, { error }));
-            throw error;
+            if (error instanceof MyOpenLayersError)
+                throw error;
+            throw this.errorHandler.createAndHandleError('工具模块初始化失败', ErrorType.COMPONENT_ERROR, { error });
         }
     }
     // ==========================================
@@ -266,13 +280,17 @@ class MyOl {
     resetPosition(duration = 3000) {
         try {
             if (!this.options.center) {
-                throw new Error('未设置中心点，无法重置位置');
+                this.errorHandler.createAndHandleError('未设置中心点，无法重置位置', ErrorType.MAP_ERROR);
+                return;
             }
             const [longitude, latitude] = this.options.center;
             this.locationAction(longitude, latitude, this.options.zoom, duration);
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`重置地图位置失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { center: this.options.center, duration }));
+            if (error instanceof MyOpenLayersError) {
+                return;
+            }
+            this.errorHandler.createAndHandleError(`重置地图位置失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { center: this.options.center, duration });
         }
     }
     /**
@@ -281,23 +299,24 @@ class MyOl {
      * @param latitude 纬度
      * @param zoom 缩放级别
      * @param duration 动画持续时间（毫秒）
+     * @param projection
      */
     locationAction(longitude, latitude, zoom = 20, duration = 3000, projection) {
         try {
             // 参数验证
             if (typeof longitude !== 'number' || typeof latitude !== 'number') {
-                throw new Error('经纬度必须是数字类型');
+                throw ErrorHandler.getInstance().createAndHandleError('经纬度必须是数字类型', ErrorType.VALIDATION_ERROR);
             }
             const hasProjection = !!projection?.dataProjection || !!projection?.featureProjection;
             if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {
-                throw new Error('经纬度必须是有效数字');
+                throw ErrorHandler.getInstance().createAndHandleError('经纬度必须是有效数字', ErrorType.VALIDATION_ERROR);
             }
             if (!hasProjection) {
                 if (longitude < -180 || longitude > 180) {
-                    throw new Error('经度值必须在 -180 到 180 之间');
+                    throw ErrorHandler.getInstance().createAndHandleError('经度值必须在 -180 到 180 之间', ErrorType.COORDINATE_ERROR);
                 }
                 if (latitude < -90 || latitude > 90) {
-                    throw new Error('纬度值必须在 -90 到 90 之间');
+                    throw ErrorHandler.getInstance().createAndHandleError('纬度值必须在 -90 到 90 之间', ErrorType.COORDINATE_ERROR);
                 }
             }
             this.getTools().locationAction(longitude, latitude, zoom, duration, projection);
@@ -310,11 +329,34 @@ class MyOl {
             });
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`地图定位失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { longitude, latitude, zoom, duration }));
-            throw error;
+            // 已处理过的 MyOpenLayersError 直接抛出，避免二次包装和重复触发回调
+            if (error instanceof MyOpenLayersError) {
+                throw error;
+            }
+            throw this.errorHandler.createAndHandleError(`地图定位失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR, { longitude, latitude, zoom, duration });
         }
     }
     // ==========================================
+    // 综合 GeoJSON 渲染
+    // ==========================================
+    /**
+     * 综合 GeoJSON 渲染方法。
+     *
+     * 自动识别点/线/面几何类型，按分组创建图层，返回统一句柄。
+     * 支持单个 GeoJSON、GeoJSON 数组、或 `{ key: json }` 对象。
+     *
+     * @param data GeoJSON 输入数据
+     * @param options 配置选项（含 layerName、groupBy、各类型样式）
+     * @returns GeoJSONRenderHandle 统一句柄
+     */
+    addGeoJSON(data, options) {
+        return renderGeoJSON(data, options, {
+            getPoint: () => this.getPoint(),
+            getLine: () => this.getLine(),
+            getPolygon: () => this.getPolygon(),
+        });
+    }
+    // ==========================================
     // 管理器访问方法
     // ==========================================
     /**
@@ -407,7 +449,7 @@ class MyOl {
             this.errorHandler.debug('地图实例已销毁', { map: this.map });
         }
         catch (error) {
-            this.errorHandler.handleError(new MyOpenLayersError(`销毁地图失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR));
+            this.errorHandler.createAndHandleError(`销毁地图失败: ${error instanceof Error ? error.message : '未知错误'}`, ErrorType.MAP_ERROR);
         }
     }
 }

package/README.md

@@ -16,11 +16,13 @@ my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地
 
 - **统一 LayerHandle** — 真实图层类 `add*` 返回 `{ layer, remove(), setVisible() }` 形态的句柄，跨 Point / Line / Polygon 复用同一套 lifecycle 模型
 - **统一 ControlHandle** — `addDomPoint` / `addVueTemplatePoint` 返回 `{ target, remove(), setVisible() }`，并保留 `anchors` / `getPoints()` 等原有能力
+- **点 API GeoJSON 直接输入** — `addPoint` / `addClusterPoint` / `addPulsePointLayer` 直接接受 `PointData[]`、GeoJSON FeatureCollection、Feature、MultiPoint geometry，内部统一标准化，`*ByUrl` 方法共享同一套解析逻辑
+- **addGeoJSON 综合渲染** — `MyOl.addGeoJSON(data, options)` 自动识别点/线/面几何类型，按分组创建图层，返回统一 `GeoJSONRenderHandle`，支持 `groupBy` 分组、`styleByProperties` 逐要素样式、数组/Record 多数据集输入
 - ***ByUrl 异步化** — `addPointByUrl` / `addLineByUrl` / `addPolygonByUrl` 统一先获取 JSON，再返回完整 Handle
 - **destroy 级联清理** — `MyOl.destroy()` 现在依次调用 `SelectHandler.destroy` / `Line.destroyAllFlowLines` / `Point.destroyAll` / `Polygon.destroyAll`，确保 rAF / Overlay / Vue 实例 / Select interaction 全部释放
 - **ProjectionManager** — 投影逻辑从 MyOl 内部抽取为独立类，支持 `ProjectionManager.register({ code, def })` 在 MyOl 实例之外注册任意 EPSG
 - **ConfigManager.setDefaults** — 运行时修改全局默认配置，所有未提供该字段的后续调用都生效
-- **具体错误类型** — `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError`，方便 `instanceof` 判别
+- **统一错误类型** — 全部 `throw` 使用 `MyOpenLayersError` 并携带 `ErrorType`（`VALIDATION_ERROR` / `MAP_ERROR` / `LAYER_ERROR` / `COORDINATE_ERROR` / `DATA_ERROR` / `COMPONENT_ERROR`），另有 `LayerNotFoundError` / `InvalidGeoJSONError` / `ProjectionError` 子类，方便 `instanceof` 判别
 - **layerName 必填** — 公开 `add*` 方法签名上 `layerName` 变成必填（编译时强制）
 - **PulsePointIconOptions `src` → `img`** — 统一命名，旧 `src` 标 `@deprecated`
 
@@ -47,7 +49,6 @@ my-openlayer 是一个基于 [OpenLayers](https://openlayers.org/) 的现代地
   - **线要素绘制 (Line)**：支持静态线、流光线、流动线图标动画，详见 [Line 动画文档](docs/Line.md#流动线--动态图标线)
   - **面要素 (Polygon)**：面要素绘制、分区高亮、遮罩层
   - **Vue组件支持 (VueTemplatePoint)**：支持将 Vue 组件作为地图点位渲染
-  - **河流图层 (RiverLayerManager)**：支持分级显示的河流图层管理
 
 - **🛠️ 地图工具**
   - **测量工具 (MeasureHandler)**：距离和面积测量
@@ -124,6 +125,14 @@ const handle = point.addPoint(
   { layerName: 'example-point', img: 'marker.png' }
 );
 handle?.remove(); // 统一的生命周期管理
+
+// 也支持直接传 GeoJSON FeatureCollection
+const geoHandle = point.addPoint(
+  { type: 'FeatureCollection', features: [
+    { type: 'Feature', properties: { name: '杭州' }, geometry: { type: 'Point', coordinates: [120.15, 30.27] } }
+  ]},
+  { layerName: 'geojson-points', textKey: 'name' }
+);
 ```
 
 ### 3. 添加高性能闪烁点
@@ -222,6 +231,38 @@ ConfigManager.setDefaults('LINE_OPTIONS', { strokeWidth: 4 });
 ConfigManager.resetDefaults('LINE_OPTIONS');
 ```
 
+### 8. addGeoJSON 综合渲染
+
+自动识别点/线/面几何类型，按分组创建图层，返回统一句柄：
+
+```typescript
+// 混合 FeatureCollection — 自动拆分为点、线、面图层
+const handle = map.addGeoJSON(geojsonData, {
+  layerName: 'risk',
+  groupBy: 'level',                                    // 按 properties.level 分组
+  point: { textKey: 'name', textVisible: true },
+  line:  { strokeColor: '#3b82f6', strokeWidth: 3 },
+  polygon: { fillColor: 'rgba(239,68,68,0.15)' }
+});
+
+// 句柄操作
+handle.setVisible(false);              // 隐藏全部
+handle.setGroupVisible('high', false); // 只隐藏 high 组
+handle.removeGroup('low');             // 只移除 low 组
+handle.remove();                       // 移除全部
+
+// styleByProperties — 按 feature 属性返回不同样式
+map.addGeoJSON(points, {
+  layerName: 'styled',
+  point: {
+    styleByProperties: (props) => ({
+      circleColor: props.risk === 'high' ? '#ef4444' : '#22c55e',
+      circleRadius: props.risk === 'high' ? 10 : 6
+    })
+  }
+});
+```
+
 ## 文档索引
 
 详细文档请访问 **[在线文档](https://cuteyuchen.github.io/my-openlayer/)**，交互式 Demo 请访问 **[Demo 站点](https://cuteyuchen.github.io/my-openlayer/demo/)**。
@@ -236,11 +277,9 @@ ConfigManager.resetDefaults('LINE_OPTIONS');
 
 ### 要素操作
 - **[Point](docs/Point.md)**: 点要素（含聚合、DOM 点位、高性能闪烁点、统一 Handle）。
-- **[Point](docs/Point.md)**: 点要素（含聚合、DOM 点位、高性能闪烁点、统一 Handle）。
 - **[Line](docs/Line.md)**: 线要素（含静态线、流动线、URL 异步加载）。
 - **[Polygon](docs/Polygon.md)**: 面要素（含热力图、图片层、遮罩层、统一 Handle）。
 - **[VueTemplatePoint](docs/VueTemplatePoint.md)**: Vue 组件点位。
-- **[RiverLayerManager](docs/RiverLayerManager.md)**: 河流图层管理。
 
 ### 交互与工具
 - **[SelectHandler](docs/SelectHandler.md)**: 要素选择交互（支持独立样式渲染、多选隔离）。

package/core/geojson/GeoJSONRenderer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * GeoJSON 渲染模块
+ * 负责将混合几何类型的 GeoJSON 数据渲染为点/线/面图层，返回统一句柄。
+ * 从 MyOl.addGeoJSON 提取，保持对外 API 不变。
+ */
+import type { Point } from '../point';
+import type { Line } from '../line';
+import type { Polygon } from '../polygon';
+import type { AddGeoJSONInput, AddGeoJSONOptions, GeoJSONRenderHandle } from '../../types';
+/**
+ * renderGeoJSON 的依赖注入接口
+ * 避免直接依赖 MyOl 实例，便于测试和解耦
+ */
+export interface GeoJSONRenderDeps {
+    getPoint(): Point;
+    getLine(): Line;
+    getPolygon(): Polygon;
+}
+/**
+ * 综合 GeoJSON 渲染
+ *
+ * 自动识别点/线/面几何类型，按分组创建图层，返回统一句柄。
+ * 支持单个 GeoJSON、GeoJSON 数组、或 `{ key: json }` 对象。
+ *
+ * @param data GeoJSON 输入数据
+ * @param options 配置选项（含 layerName、groupBy、各类型样式）
+ * @param deps 依赖注入（getPoint / getLine / getPolygon）
+ * @returns GeoJSONRenderHandle 统一句柄
+ */
+export declare function renderGeoJSON(data: AddGeoJSONInput, options: AddGeoJSONOptions, deps: GeoJSONRenderDeps): GeoJSONRenderHandle;

package/core/geojson/GeoJSONRenderer.js

@@ -0,0 +1,251 @@
+/**
+ * GeoJSON 渲染模块
+ * 负责将混合几何类型的 GeoJSON 数据渲染为点/线/面图层，返回统一句柄。
+ * 从 MyOl.addGeoJSON 提取，保持对外 API 不变。
+ */
+import { normalizeGeoJSONInputs, splitByGroupAndGeometry, } from '../../utils/GeoJSONProcessor';
+/**
+ * 从 feature 中剥离 _datasetKey 元数据
+ */
+function stripDatasetMeta(f) {
+    const { _datasetKey, ...rest } = f;
+    return rest;
+}
+/**
+ * 解析 GeoJSON 图层名称
+ */
+function resolveGeoJSONLayerName(layerName, groupKey, geometryType, datasetKey, index, singleGroup) {
+    if (typeof layerName === 'function') {
+        return layerName({ datasetKey, groupKey, geometryType, index });
+    }
+    // 确定 base 名称
+    let base;
+    if (typeof layerName === 'string') {
+        base = layerName;
+    }
+    else if (Array.isArray(layerName)) {
+        base = layerName[Number(datasetKey)] ?? `${layerName[0] ?? 'geojson'}_${datasetKey}`;
+    }
+    else {
+        base = layerName[datasetKey] ?? datasetKey;
+    }
+    // 单 group 无 groupBy 时省略 groupKey
+    if (singleGroup) {
+        return `${base}__${geometryType}`;
+    }
+    return `${base}__${groupKey}__${geometryType}`;
+}
+/**
+ * 创建点图层 handle（含 styleByProperties 分支）
+ */
+function createPointLayerHandle(pointFeatures, options, groupKey, datasetKey, singleGroup, pointModule) {
+    const pointOpts = options.point;
+    const name = resolveGeoJSONLayerName(options.layerName, groupKey, 'point', datasetKey, 0, singleGroup);
+    if (pointOpts?.styleByProperties) {
+        // 通过 feature style resolver 实现逐 feature 样式，保持单图层
+        const baseOpts = { ...pointOpts };
+        delete baseOpts.styleByProperties;
+        const pointIndexKey = Symbol('geojsonPointIndex');
+        // 为传入点图层的数据挂临时索引标记，
+        // normalizePointData 的 spread 会将标记带入 rawData，
+        // resolver 再用它反查无内部字段的真实 GeoJSON Feature。
+        const cleanPointFeatures = pointFeatures.map(stripDatasetMeta);
+        const taggedPointFeatures = [];
+        for (let i = 0; i < pointFeatures.length; i++) {
+            const feature = cleanPointFeatures[i];
+            const tagged = {
+                ...feature,
+                properties: { ...feature.properties, [pointIndexKey]: i },
+            };
+            taggedPointFeatures.push(tagged);
+        }
+        const styleResolver = ((olFeature) => {
+            const rawProps = (olFeature.get('rawData') ?? {});
+            // 从临时标记读取组内索引，并从 rawData 中移除内部字段
+            const rawWithIndex = rawProps;
+            const idx = Number.isInteger(rawWithIndex[pointIndexKey]) ? rawWithIndex[pointIndexKey] : 0;
+            delete rawWithIndex[pointIndexKey];
+            // 使用 stripped feature 的 properties（不含 lgtd/lttd）作为回调第一个参数
+            const cleanProps = cleanPointFeatures[idx]?.properties ?? rawProps;
+            const override = pointOpts.styleByProperties(cleanProps, {
+                datasetKey,
+                groupKey,
+                // 传入去除了 _datasetKey 元数据的真实 GeoJSON Feature
+                feature: cleanPointFeatures[idx] ?? rawProps,
+                // 传入该 feature 在点分组内的真实索引
+                index: idx,
+            });
+            // rawProps 仍包含 lgtd/lttd，传给 createPointStyle 用于坐标计算
+            return pointModule.createPointStyle(override ? { ...baseOpts, ...override } : baseOpts, rawProps);
+        });
+        const h = pointModule.addPoint(taggedPointFeatures, { ...baseOpts, layerName: name, style: styleResolver });
+        return { handle: h ?? null };
+    }
+    const h = pointModule.addPoint(pointFeatures.map(stripDatasetMeta), { ...pointOpts, layerName: name });
+    return { handle: h ?? null };
+}
+/**
+ * 创建线图层 handle
+ */
+function createLineHandle(lineFeatures, options, groupKey, datasetKey, singleGroup, lineModule) {
+    const name = resolveGeoJSONLayerName(options.layerName, groupKey, 'line', datasetKey, 0, singleGroup);
+    const lineData = { type: 'FeatureCollection', features: lineFeatures.map(stripDatasetMeta) };
+    return lineModule.addLine(lineData, {
+        ...options.line,
+        layerName: name,
+        dataProjection: options.dataProjection,
+        featureProjection: options.featureProjection,
+    }) ?? null;
+}
+/**
+ * 创建面图层 handle
+ */
+function createPolygonHandle(polygonFeatures, options, groupKey, datasetKey, singleGroup, polygonModule) {
+    const name = resolveGeoJSONLayerName(options.layerName, groupKey, 'polygon', datasetKey, 0, singleGroup);
+    const polyData = { type: 'FeatureCollection', features: polygonFeatures.map(stripDatasetMeta) };
+    return polygonModule.addPolygon(polyData, {
+        ...options.polygon,
+        layerName: name,
+        dataProjection: options.dataProjection,
+        featureProjection: options.featureProjection,
+        fitView: options.fitView,
+    }) ?? null;
+}
+/**
+ * 组装 GeoJSONRenderHandle
+ * 通过闭包维护 allHandles / groupHandles / pointMap / lineMap / polygonMap，
+ * removeGroup / remove 不依赖 this 上下文。
+ */
+function createRenderHandle(allHandles, groupHandles, pointMap, lineMap, polygonMap) {
+    return {
+        groups: groupHandles,
+        handles: allHandles,
+        point: pointMap,
+        line: lineMap,
+        polygon: polygonMap,
+        setVisible(visible) {
+            for (const handle of allHandles) {
+                handle.setVisible(visible);
+            }
+        },
+        setGroupVisible(groupKey, visible) {
+            groupHandles[groupKey]?.setVisible(visible);
+        },
+        removeGroup(groupKey) {
+            const gh = groupHandles[groupKey];
+            if (gh) {
+                gh.remove();
+                // 从 allHandles 中移除
+                for (const h of gh.handles) {
+                    const idx = allHandles.indexOf(h);
+                    if (idx >= 0)
+                        allHandles.splice(idx, 1);
+                }
+                delete groupHandles[groupKey];
+                // 同步清理 point/line/polygon 索引
+                delete pointMap[groupKey];
+                delete lineMap[groupKey];
+                delete polygonMap[groupKey];
+            }
+        },
+        remove() {
+            for (const handle of allHandles) {
+                handle.remove();
+            }
+            allHandles.length = 0;
+            for (const key of Object.keys(groupHandles)) {
+                delete groupHandles[key];
+            }
+            for (const key of Object.keys(pointMap)) {
+                delete pointMap[key];
+            }
+            for (const key of Object.keys(lineMap)) {
+                delete lineMap[key];
+            }
+            for (const key of Object.keys(polygonMap)) {
+                delete polygonMap[key];
+            }
+        },
+    };
+}
+/**
+ * 综合 GeoJSON 渲染
+ *
+ * 自动识别点/线/面几何类型，按分组创建图层，返回统一句柄。
+ * 支持单个 GeoJSON、GeoJSON 数组、或 `{ key: json }` 对象。
+ *
+ * @param data GeoJSON 输入数据
+ * @param options 配置选项（含 layerName、groupBy、各类型样式）
+ * @param deps 依赖注入（getPoint / getLine / getPolygon）
+ * @returns GeoJSONRenderHandle 统一句柄
+ */
+export function renderGeoJSON(data, options, deps) {
+    /** *********************输入标准化*********************/
+    const normalized = normalizeGeoJSONInputs(data);
+    const groups = splitByGroupAndGeometry(normalized, options.groupBy);
+    const allHandles = [];
+    const groupHandles = {};
+    const singleGroup = Object.keys(groups).length === 1 && !options.groupBy;
+    // 用于组装返回句柄的索引
+    const pointMap = {};
+    const lineMap = {};
+    const polygonMap = {};
+    /** *********************遍历分组创建图层*********************/
+    for (const [groupKey, { point: pointFeatures, line: lineFeatures, polygon: polygonFeatures }] of Object.entries(groups)) {
+        const groupAllHandles = [];
+        let pointHandle = null;
+        let lineHandle = null;
+        let polygonHandle = null;
+        // 提取各几何类型的 datasetKey（取第一个 feature 的即可，同组内 datasetKey 相同）
+        const pointDatasetKey = pointFeatures[0]?._datasetKey ?? 'default';
+        const lineDatasetKey = lineFeatures[0]?._datasetKey ?? 'default';
+        const polygonDatasetKey = polygonFeatures[0]?._datasetKey ?? 'default';
+        // 点图层
+        if (pointFeatures.length > 0) {
+            const result = createPointLayerHandle(pointFeatures, options, groupKey, pointDatasetKey, singleGroup, deps.getPoint());
+            pointHandle = result.handle;
+            if (pointHandle) {
+                groupAllHandles.push(pointHandle);
+                allHandles.push(pointHandle);
+            }
+        }
+        // 线图层
+        if (lineFeatures.length > 0) {
+            lineHandle = createLineHandle(lineFeatures, options, groupKey, lineDatasetKey, singleGroup, deps.getLine());
+            if (lineHandle) {
+                groupAllHandles.push(lineHandle);
+                allHandles.push(lineHandle);
+            }
+        }
+        // 面图层
+        if (polygonFeatures.length > 0) {
+            polygonHandle = createPolygonHandle(polygonFeatures, options, groupKey, polygonDatasetKey, singleGroup, deps.getPolygon());
+            if (polygonHandle) {
+                groupAllHandles.push(polygonHandle);
+                allHandles.push(polygonHandle);
+            }
+        }
+        /** *********************组装分组句柄*********************/
+        groupHandles[groupKey] = {
+            point: pointHandle,
+            line: lineHandle,
+            polygon: polygonHandle,
+            handles: groupAllHandles,
+            setVisible(visible) {
+                for (const handle of groupAllHandles) {
+                    handle.setVisible(visible);
+                }
+            },
+            remove() {
+                for (const handle of groupAllHandles) {
+                    handle.remove();
+                }
+            },
+        };
+        pointMap[groupKey] = pointHandle;
+        lineMap[groupKey] = lineHandle;
+        polygonMap[groupKey] = polygonHandle;
+    }
+    /** *********************组装总句柄*********************/
+    return createRenderHandle(allHandles, groupHandles, pointMap, lineMap, polygonMap);
+}

package/core/geojson/index.d.ts

@@ -0,0 +1,2 @@
+export { renderGeoJSON } from './GeoJSONRenderer';
+export type { GeoJSONRenderDeps } from './GeoJSONRenderer';

package/core/geojson/index.js

@@ -0,0 +1 @@
+export { renderGeoJSON } from './GeoJSONRenderer';