@xingm/vmap-cesium-toolbar 0.0.2 → 0.0.3

package/dist/libs/CesiumHeatmapLayer.d.ts

@@ -83,7 +83,16 @@ export default class CesiumHeatmapLayer {
     private handleWorkerFault;
     constructor(viewer: Cesium.Viewer, options?: HeatmapOptions);
     private parseColorToRGBA;
+    /**
+     * 获取离散桶的索引
+     * @param value - 需要确定桶索引的数值
+     * @return 返回对应的桶索引，如果阈值无效则返回0
+     */
     private getDiscreteBucketIndex;
+    /**
+     * 渲染离散热力图
+     * @param points 热力点数据数组
+     */
     private renderDiscrete;
     /**
      * 设置/替换热力图数据（度为单位）

package/dist/libs/CesiumMapDraw.d.ts

@@ -74,11 +74,19 @@ declare class DrawHelper {
      */
     constructor(viewer: Cesium.Viewer);
     private dumpPotentialClampingEntities;
+    /**
+     * 对新创建的实体进行净化处理，确保其符合渲染要求
+     * @param entity - 需要净化的 Cesium.Entity 对象
+     * @param tag - 用于标识来源的标签，会在控制台警告时显示
+     */
     private sanitizeNewEntity;
     private installEntitiesAddHook;
     private uninstallEntitiesAddHook;
+    /**
+     * 安装地面几何更新器调试钩子
+     * 此方法用于在Cesium GroundGeometryUpdater中安装一个调试钩子，用于捕获和处理渲染错误
+     */
     private installGroundGeometryUpdaterDebugHook;
-    private logRenderErrorDetails;
     /**
      * 外部调用：在场景模式（2D/3D）切换后，更新偏移高度并重算已完成实体
      */
@@ -91,6 +99,11 @@ declare class DrawHelper {
      * 计算提示文本（随绘制模式 + 点数量变化）
      */
     private getDrawHintText;
+    /**
+     * 设置绘制提示覆盖文本及其持续时间
+     * @param text 要显示的提示文本
+     * @param ms 提示文本显示的持续时间（毫秒），默认为1200毫秒
+     */
     private setDrawHintOverride;
     /**
      * 将提示位置转换为显示位置（按当前模式做轻微抬高，避免被地形遮挡）

package/dist/libs/CesiumOverlayService.d.ts

@@ -1,4 +1,5 @@
 import { Viewer, Entity } from '../../node_modules/cesium';
+import { DrawEntity } from './drawHelper';
 import { OverlayEntity, OverlayPosition } from './overlay/types';
 import { MapMarker, MarkerOptions } from './overlay/MapMarker';
 import { MapLabel, LabelOptions } from './overlay/MapLabel';
@@ -10,6 +11,19 @@ import { MapPolygon, PolygonOptions } from './overlay/MapPolygon';
 import { MapRectangle, RectangleOptions } from './overlay/MapRectangle';
 import { MapCircle, CircleOptions } from './overlay/MapCircle';
 import { MapRing, RingOptions } from './overlay/MapRing';
+export interface CesiumOverlayServiceOptions {
+    /**
+     * 是否启用实体 hover 处理器（MOUSE_MOVE 下会执行 pick/drillPick 并触发 hover 高亮）。
+     * 大屏/高负载场景可考虑关闭以规避 Cesium 在 primitive 重建窗口期的边界问题。
+     * @default true
+     */
+    enableHoverHandler?: boolean;
+    /**
+     * 覆盖物处于编辑模式时：一次拖拽结束（LEFT_UP）且几何发生变化会触发。
+     * 参数为“已回写后的覆盖物 entity”。
+     */
+    onOverlayEditChange?: (entity: DrawEntity & OverlayEntity) => void;
+}
 /**
  * Cesium 覆盖物服务类
  * 统一管理各种覆盖物工具类
@@ -19,16 +33,49 @@ export declare class CesiumOverlayService {
     private entities;
     private overlayMap;
     private infoWindowContainer;
+    /** 构造参数（用于开关 hover handler 等运行时策略） */
+    private readonly options;
+    private overlayEditor;
     private lastHoverTargets;
     private hoverPickRAF;
     private hoverPickPos;
+    private overlayMutationRevision;
+    private hoverSuspendUntil;
+    private lastHoverPickTime;
+    private lastHoverPickPos;
+    private bulkUpdateDepth;
     private static readonly DEFAULT_HIGHLIGHT_COLOR;
     private static readonly DEFAULT_HIGHLIGHT_FILL_ALPHA;
+    private static readonly DEFAULT_HIGHLIGHT_GLOW_POWER;
+    private static readonly GLOW_OUTLINE_ROOT_ID_PROP;
+    private static readonly HOVER_PICK_MIN_INTERVAL_MS;
+    private static readonly HOVER_PICK_MIN_MOVE_PX;
+    private static readonly HOVER_SUSPEND_AFTER_MUTATION_MS;
+    private markOverlayMutated;
+    /**
+     * 显式开始一次批量更新：在 begin/end 期间暂停 hover pick。
+     * 建议 websocket 批量 add/remove 覆盖物时包裹使用，降低 Cesium GroundPrimitive 异步重建窗口期的 pick/update 压力。
+     */
+    beginBulkUpdate(): void;
+    /**
+     * 结束一次批量更新。
+     */
+    endBulkUpdate(): void;
+    /**
+     * 批量更新包裹器（自动 begin/end）。
+     */
+    bulkUpdate<T>(fn: () => T): T;
     /**
      * Primitive 模式下，GeometryInstance.id 会是字符串（structured-cloneable），
      * 需要映射回 overlayMap 内的根覆盖物 id。
      */
     private normalizeOverlayPickId;
+    private getEntityPropertyString;
+    private mapGlowOutlineEntityToRoot;
+    private getClosedPositions;
+    private generateEllipseOutlinePositions;
+    private ensureGlowOutline;
+    private removeGlowOutline;
     private resolveOverlayByPickId;
     private resolvePickedOverlayEntity;
     readonly marker: MapMarker;
@@ -41,7 +88,7 @@ export declare class CesiumOverlayService {
     readonly rectangle: MapRectangle;
     readonly circle: MapCircle;
     readonly ring: MapRing;
-    constructor(viewer: Viewer);
+    constructor(viewer: Viewer, options?: CesiumOverlayServiceOptions);
     /**
      * Cesium 默认可能无法 pick 到半透明覆盖物（例如 alpha < 1 的填充面）。
      * 开启 pickTranslucentDepth 后，hover/click 才能稳定命中半透明面。
@@ -70,6 +117,21 @@ export declare class CesiumOverlayService {
      * 设置实体点击处理器
      */
     private setupEntityClickHandler;
+    /**
+     * 开启/关闭覆盖物编辑模式。
+     * - 开启后：点击覆盖物会进入编辑，并显示可拖拽控制点。
+     * - 关闭后：退出编辑并移除控制点。
+     */
+    setOverlayEditMode(enabled: boolean): void;
+    /** 当前是否处于覆盖物编辑模式（全局开关） */
+    getOverlayEditModeEnabled(): boolean;
+    /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
+    stopOverlayEdit(): void;
+    /**
+     * 主动开始编辑某个覆盖物。
+     * @returns true 表示成功进入编辑
+     */
+    startOverlayEdit(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
     /**
      * 设置实体 hover 高亮处理器（鼠标移入高亮，移出取消）
      */

package/dist/libs/CesiumPointClusterLayer.d.ts

@@ -0,0 +1,73 @@
+import { Viewer } from '../../node_modules/cesium';
+import * as Cesium from 'cesium';
+export interface ClusterPoint {
+    /** 业务 id（可选，建议传以便稳定更新） */
+    id?: string;
+    /** 经度（度） */
+    lon: number;
+    /** 纬度（度） */
+    lat: number;
+    /** 高度（米，默认 0） */
+    height?: number;
+    /** 可选：权重/热度值（暂未参与聚类，仅透传给回调） */
+    value?: number;
+    /** 任意业务属性 */
+    properties?: Record<string, unknown>;
+}
+export interface ClusterStyleStep {
+    /** 当 count >= minCount 时命中该样式（按 minCount 从大到小匹配更直观） */
+    minCount: number;
+    color: Cesium.Color | string;
+    /** 聚合点圆点大小（像素），不填则使用 options.clusterPixelSize */
+    pixelSize?: number;
+}
+export interface PointClusterLayerOptions {
+    /** 图层 id（用于 Cesium.DataSourceCollection 里区分） */
+    id?: string;
+    /** 单点渲染：像素大小 */
+    pointPixelSize?: number;
+    /** 单点渲染：颜色 */
+    pointColor?: Cesium.Color | string;
+    /** 单点渲染：是否贴地（height=0 时等价贴地效果更明显） */
+    clampToGround?: boolean;
+    /** 聚类开关（默认 true） */
+    clusteringEnabled?: boolean;
+    /** 聚类像素范围（越大越容易聚合），默认 50 */
+    pixelRange?: number;
+    /** 最小聚类数量，默认 2 */
+    minimumClusterSize?: number;
+    /** 聚合点默认大小（像素） */
+    clusterPixelSize?: number;
+    /** 聚合点样式分段：用 count 决定颜色/大小 */
+    clusterStyleSteps?: ClusterStyleStep[];
+    /** 点击聚合点回调：返回该聚合内的原始点 */
+    onClusterClick?: (points: ClusterPoint[], ctx: {
+        screenPosition: Cesium.Cartesian2;
+        worldPosition?: Cesium.Cartesian3;
+    }) => void;
+    /** 点击单点回调 */
+    onPointClick?: (point: ClusterPoint, ctx: {
+        screenPosition: Cesium.Cartesian2;
+        worldPosition?: Cesium.Cartesian3;
+    }) => void;
+    /** entity id 前缀（用于避免与外部实体冲突） */
+    idPrefix?: string;
+}
+export default class CesiumPointClusterLayer {
+    private viewer;
+    private readonly options;
+    private dataSource;
+    private entityIdToPoint;
+    private clickHandler;
+    private readonly layerId;
+    constructor(viewer: Viewer, options?: PointClusterLayerOptions);
+    /** 设置/替换点数据（经纬度单位：度） */
+    setData(points: ClusterPoint[]): void;
+    setVisible(visible: boolean): void;
+    setClusteringEnabled(enabled: boolean): void;
+    destroy(): void;
+    private applyClusterStyle;
+    private pickStyle;
+    private installClickHandler;
+}
+export { CesiumPointClusterLayer };

package/dist/libs/drawHelper/BaseDraw.d.ts

@@ -59,6 +59,8 @@ export interface DrawOptions {
     };
     /** 是否显示面积标签（多边形/矩形）。默认 true */
     showAreaLabel?: boolean;
+    /** 是否显示长度标签（线条）。默认 true */
+    showDistanceLabel?: boolean;
     /**
      * 是否启用多边形自相交校验。
      * - false/未设置：默认允许交叉（不做校验）

package/dist/libs/drawHelper/DrawLine.d.ts

@@ -9,6 +9,10 @@ export declare class DrawLine extends BaseDraw {
     private currentTotalLabel;
     private currentLinePositions;
     private isTotalLabelWarmedUp;
+    /**
+     * 清理当前线段/总距离标签（不影响线实体本身）
+     */
+    private clearDistanceLabels;
     /**
      * 开始绘制
      */

package/dist/libs/overlay/MapCircle.d.ts

@@ -68,6 +68,11 @@ export declare class MapCircle {
     private getPrimitiveBatchForOverlay;
     private resolveMaterialColor;
     private canUsePrimitive;
+    /**
+     * 添加一个基础的圆形图元
+     * @param options 圆形配置选项
+     * @returns 返回创建的实体对象
+     */
     private addPrimitiveCircle;
     /**
      * 转换位置为 Cartesian3
@@ -90,6 +95,11 @@ export declare class MapCircle {
      * 使用大圆航线公式，segments 越大越平滑。
      */
     private generateCirclePositions;
+    /**
+     * 获取方位角查找表，用于存储正弦和余弦值
+     * @param segments 分段数量，用于确定查找表的精度
+     * @returns 返回一个包含正弦和余弦数组的对象
+     */
     private getBearingTable;
     /**
      * 粗边框模式的默认分段数：平衡“圆滑程度/性能”。

package/dist/libs/overlay/MapInfoWindow.d.ts

@@ -46,12 +46,12 @@ export declare class MapInfoWindow {
     private mergeOptions;
     constructor(viewer: Viewer, container: HTMLElement);
     /**
-     * Set default update interval (ms) for position updates when an InfoWindow doesn't specify `updateInterval`.
-     * 0 means update every frame.
+     * 设置默认的位置更新间隔（毫秒）：当 InfoWindow 未指定 `updateInterval` 时使用。
+     * 0 表示每帧更新。
      */
     setDefaultUpdateInterval(ms: number): void;
     /**
-     * Force immediate update (recompute positions) of all managed info windows.
+     * 强制立即更新（重新计算位置）所有已管理的信息窗。
      */
     forceUpdateAll(): void;
     private convertPosition;

package/dist/libs/overlay/OverlayEditController.d.ts

@@ -0,0 +1,127 @@
+import { Viewer } from '../../../node_modules/cesium';
+import { DrawEntity } from '../drawHelper';
+import { OverlayEntity } from './types';
+import * as Cesium from "cesium";
+export type OverlayEditChangeCallback = (entity: DrawEntity & OverlayEntity) => void;
+export interface OverlayEditControllerOptions {
+    /**
+     * 编辑模式下，拖拽结束（LEFT_UP）且覆盖物几何发生变化时触发。
+     * 回调参数为“已回写后的覆盖物 entity”。
+     */
+    onChange?: OverlayEditChangeCallback;
+}
+export interface OverlayEditHost {
+    getViewer(): Viewer;
+    getEntities(): Cesium.EntityCollection;
+    getOverlayById(id: string): (DrawEntity & OverlayEntity) | undefined;
+    pickCartographic(windowPosition: Cesium.Cartesian2): Cesium.Cartographic | null;
+    /**
+     * 进入编辑前的宿主清理动作（例如清 hover/click 高亮、清 hover 状态等）。
+     * 由宿主决定“高亮系统/hover 系统”如何处理。
+     */
+    prepareEntityForEdit(entity: DrawEntity & OverlayEntity): void;
+    /** 将编辑结果回写到覆盖物 */
+    applyPolygonPositions(entity: DrawEntity & OverlayEntity, positions: Cesium.Cartesian3[]): void;
+    applyRectangleCoordinates(entity: DrawEntity & OverlayEntity, rect: Cesium.Rectangle): void;
+    applyCircle(entity: DrawEntity & OverlayEntity, center: Cesium.Cartesian3, radiusMeters: number): void;
+    applyPolylinePositions(entity: DrawEntity & OverlayEntity, positions: Cesium.Cartesian3[]): void;
+    applyPointPosition(entity: DrawEntity & OverlayEntity, position: Cesium.Cartesian3): void;
+}
+export declare class OverlayEditController {
+    private readonly host;
+    private enabled;
+    private handler;
+    private onChange;
+    private editingTarget;
+    private editingKind;
+    private editingPositions;
+    private editingCircleCenter;
+    private editingCircleRadiusMeters;
+    private editingPointPosition;
+    private handleEntities;
+    private dragging;
+    private dragSnapshot;
+    private dragChanged;
+    private moveStartCenter;
+    private moveStartPositions;
+    private transformStartCenter;
+    private transformStartPositions;
+    private rotateStartAngle;
+    private scaleStartDistance;
+    private cameraBackup;
+    constructor(host: OverlayEditHost, options?: OverlayEditControllerOptions);
+    setOnChange(cb?: OverlayEditChangeCallback | null): void;
+    setEnabled(enabled: boolean): void;
+    getEnabled(): boolean;
+    isEditing(): boolean;
+    destroy(): void;
+    /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
+    stop(): void;
+    /**
+     * 主动开始编辑某个覆盖物。
+     * @returns true 表示成功进入编辑
+     */
+    start(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
+    private detectEditableKind;
+    private getPropertyValue;
+    private getNumberProperty;
+    private resolvePolygonPositions;
+    private resolvePolylinePositions;
+    private getEditablePolygonPositions;
+    private getEditablePolylinePositions;
+    private getEditablePointPosition;
+    private getEditableRectangle;
+    private getEditableCircleInfo;
+    /**
+     * 确保编辑处理器已初始化
+     * 如果处理器不存在，则创建一个新的 ScreenSpaceEventHandler 并设置各种交互事件处理函数
+     * @private
+     */
+    /**
+     * 确保事件处理器已初始化
+     * 如果处理器不存在，则创建并设置各种事件处理函数
+     * @private
+     */
+    /**
+     * 确保屏幕空间事件处理器已初始化
+     * 如果处理器不存在，则创建一个新的处理器并设置各种交互事件
+     */
+    private ensureHandler;
+    private captureDragSnapshot;
+    private isGeometryChangedSinceSnapshot;
+    private destroyHandler;
+    private lockCameraController;
+    private restoreCameraController;
+    private clearHandles;
+    private rebuildHandles;
+    private createHandle;
+    private buildPolygonHandles;
+    private buildRectangleHandles;
+    private buildPolylineHandles;
+    private buildPointHandles;
+    private buildCircleHandles;
+    private updatePolygonHandlePositions;
+    private updateRectangleHandlePositions;
+    private updatePolylineHandlePositions;
+    private updatePointHandlePositions;
+    private updateCircleHandlePositions;
+    private applyEditedPolygon;
+    private applyEditedRectangle;
+    private applyEditedCircle;
+    private applyEditedPolyline;
+    private applyEditedPoint;
+    private getEditingClampToGround;
+    private getCartesianHeight;
+    private pickCartesianOnGlobe;
+    private computeSurfaceDistanceMeters;
+    private circleRadiusHandlePosition;
+    private rectangleToPositions;
+    private positionsToRectangle;
+    private getRectangleEditHeight;
+    private computePolygonCenterCartesian;
+    private computePolygonCenterCartographic;
+    private computePolylineHandleRadius;
+    private offsetByMeters;
+    private getLocalAngleAndDistance;
+    private applyRotateScaleToPositions;
+}

package/dist/libs/overlay/index.d.ts

@@ -1,4 +1,5 @@
 export { CesiumOverlayService } from '../CesiumOverlayService';
+export type { CesiumOverlayServiceOptions } from '../CesiumOverlayService';
 export { MapMarker } from './MapMarker';
 export { MapLabel } from './MapLabel';
 export { MapIcon } from './MapIcon';

package/dist/libs/overlay/types.d.ts

@@ -73,6 +73,8 @@ export interface OverlayEntity extends Entity {
     };
     /** 用于还原高亮前的原始样式 */
     _highlightOriginalStyle?: OverlayHighlightOriginalStyle;
+    /** 高亮时临时创建的“发光边框”实体（由 CesiumOverlayService 管理） */
+    _highlightGlowEntity?: Entity;
     /** 覆盖物类型标识（用于 CesiumOverlayService 做差异化更新/删除） */
     _overlayType?: string;
     /** 信息窗口根 DOM（由 MapInfoWindow / CesiumOverlayService 使用） */
@@ -110,6 +112,8 @@ export interface OverlayEntity extends Entity {
     _primitiveLayerKey?: string;
     _primitiveRingBaseColor?: Color;
     _primitiveFillBaseColor?: Color;
+    /** primitive：用于高亮发光边框的外圈/边界位置（通常为闭合折线） */
+    _primitiveOutlinePositions?: Cartesian3[];
     /** primitive polygon/rectangle: 边框纯色缓存（用于高亮恢复） */
     _primitiveBorderBaseColor?: Color;
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@xingm/vmap-cesium-toolbar",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A powerful Cesium map toolbar plugin with drawing, measurement, and interaction features",
   "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "main": "dist/index.es.js",
+  "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
@@ -15,14 +15,15 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./dist/index.es.js",
+      "default": "./dist/index.es.js"
     },
     "./style": "./dist/style.css"
   },
   "scripts": {
     "dev": "vite --force",
     "build": "vite build --mode lib",
+    "dist": "vite build",
     "build:dts": "vue-tsc -p tsconfig.dts.json",
     "build:plugin": "node scripts/build-plugin.js",
     "docs:dev": "vitepress dev doc",
@@ -63,10 +64,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/benxueyou/vmap-cesium-toolbar.git"
+    "url": "git+https://github.com/BenXueYou/vmap-cesium-tool.git"
   },
   "bugs": {
-    "url": "https://github.com/benxueyou/vmap-cesium-toolbar/issues"
+    "url": "https://github.com/BenXueYou/vmap-cesium-tool/issues"
   },
-  "homepage": "https://github.com/benxueyou/vmap-cesium-toolbar#readme"
+  "homepage": "https://github.com/BenXueYou/vmap-cesium-tool#readme"
 }