@xingm/vmap-cesium-toolbar 0.0.2-alpha.17 → 0.0.2-alpha.19

package/dist/libs/CesiumAutoRecover.d.ts

@@ -0,0 +1,48 @@
+import { Viewer } from '../../node_modules/cesium';
+export interface CesiumAutoRecoverOptions {
+    /** 是否启用自动恢复（默认 false） */
+    enabled?: boolean;
+    /** 最大恢复次数（默认 3） */
+    maxRetries?: number;
+    /** 两次恢复之间的最小间隔（默认 5000ms） */
+    cooldownMs?: number;
+    /** 恢复后是否尝试保留相机视角（默认 true） */
+    preserveCamera?: boolean;
+    /**
+     * 触发恢复的原因与错误信息
+     * - reason: renderError/widgetError/watchdog/windowError 等
+     */
+    onRecovering?: (ctx: {
+        reason: string;
+        error?: unknown;
+        attempt: number;
+    }) => void;
+    /** 恢复成功回调：业务侧应在这里替换引用（非常重要） */
+    onRecovered?: (ctx: {
+        reason: string;
+        error?: unknown;
+        attempt: number;
+        oldViewer: Viewer;
+        newViewer: Viewer;
+    }) => void;
+    /**
+     * 渲染“静默停止”监测：有些错误不一定走 renderError，但会导致不再 postRender。
+     * 注意：若开启了 requestRenderMode（按需渲染），默认不建议启用 watchdog。
+     */
+    watchdog?: {
+        enabled?: boolean;
+        /** 多久没有 postRender 认为卡死（默认 6000ms） */
+        staleMs?: number;
+        /** 检查间隔（默认 2000ms） */
+        checkIntervalMs?: number;
+    };
+}
+type CreateViewer = () => Promise<Viewer>;
+/**
+ * 为已有 Viewer 安装自动恢复：遇到“Rendering has stopped”/NaN render error 等，自动重建 Viewer。
+ * 重要：重建会产生新的 Viewer 实例，业务侧必须在 onRecovered 里替换引用。
+ */
+export declare function enableCesiumAutoRecover(viewer: Viewer, createViewer: CreateViewer, options: CesiumAutoRecoverOptions): {
+    dispose: () => void;
+};
+export {};

package/dist/libs/CesiumHeatmapLayer.d.ts

@@ -18,6 +18,8 @@ export interface HeatmapOptions {
     /** Canvas 分辨率，越大越清晰但开销越大 */
     width?: number;
     height?: number;
+    /** 渲染模式：heat 为热力渐变（默认）；discrete 为严格分段纯色 */
+    mode?: "heat" | "discrete";
     /** 单个点的影响半径（像素） */
     radius?: number;
     /** 低强度提升（伽马矫正），< 1 可增强边缘，默认 0.7 */
@@ -31,6 +33,20 @@ export interface HeatmapOptions {
     opacity?: number;
     /** 颜色梯度 */
     gradient?: HeatmapGradient;
+    /**
+     * 严格分段（仅 mode=discrete 生效）：
+     * thresholds.length + 1 必须等于 colors.length。
+     * 例如 thresholds=[40,60,90,110] colors=[蓝,青,绿,黄,红]
+     * - value < 40 -> colors[0]
+     * - 40 <= value < 60 -> colors[1]
+     * - 60 <= value < 90 -> colors[2]
+     * - 90 <= value < 110 -> colors[3]
+     * - value >= 110 -> colors[4]
+     */
+    discreteThresholds?: number[];
+    discreteColors?: string[];
+    /** 重叠像素的决策：max=取更高分段（默认）；last=后绘制覆盖 */
+    discreteOverlap?: "max" | "last";
 }
 export interface HeatmapAutoUpdateOptions {
     /** 是否启用随视角变化自动重绘（默认 true） */
@@ -64,7 +80,20 @@ export default class CesiumHeatmapLayer {
     private workerReady;
     private pendingUpdate;
     private lastUpdateKey;
+    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/CesiumMapLoader.d.ts

@@ -1,4 +1,5 @@
 import { Viewer as CesiumViewer, Terrain, TerrainProvider } from '../../node_modules/cesium';
+import { CesiumAutoRecoverOptions } from './CesiumAutoRecover';
 import * as Cesium from 'cesium';
 interface InitOptions {
     orderIndependentTranslucency?: boolean;
@@ -50,6 +51,8 @@ interface InitOptions {
     success?: () => void;
     cancel?: () => void;
     mapCenter?: MapCenter;
+    /** 渲染异常自动恢复（可选）：会重建 Viewer，需在回调里替换引用 */
+    autoRecover?: CesiumAutoRecoverOptions;
 }
 interface MapCenter {
     latitude: number;

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,14 @@ 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;
+}
 /**
  * Cesium 覆盖物服务类
  * 统一管理各种覆盖物工具类
@@ -19,11 +28,62 @@ export declare class CesiumOverlayService {
     private entities;
     private overlayMap;
     private infoWindowContainer;
+    /** 构造参数（用于开关 hover handler 等运行时策略） */
+    private readonly options;
+    private overlayEditModeEnabled;
+    private overlayEditHandler;
+    private overlayEditingTarget;
+    private overlayEditingKind;
+    private overlayEditingPositions;
+    private overlayEditingCircleCenter;
+    private overlayEditingCircleRadiusMeters;
+    private overlayEditHandleEntities;
+    private overlayEditDragging;
+    private overlayEditMoveStartCenter;
+    private overlayEditMoveStartPositions;
+    private overlayEditCameraBackup;
     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;
     readonly label: MapLabel;
     readonly icon: MapIcon;
@@ -34,7 +94,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 才能稳定命中半透明面。
@@ -63,6 +123,48 @@ export declare class CesiumOverlayService {
      * 设置实体点击处理器
      */
     private setupEntityClickHandler;
+    /**
+     * 开启/关闭覆盖物编辑模式。
+     * - 开启后：点击覆盖物会进入编辑，并显示可拖拽控制点。
+     * - 关闭后：退出编辑并移除控制点。
+     */
+    setOverlayEditMode(enabled: boolean): void;
+    /** 当前是否处于覆盖物编辑模式（全局开关） */
+    getOverlayEditModeEnabled(): boolean;
+    /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
+    stopOverlayEdit(): void;
+    /**
+     * 主动开始编辑某个覆盖物。
+     * @returns true 表示成功进入编辑
+     */
+    startOverlayEdit(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
+    private detectEditableKind;
+    private getEditablePolygonPositions;
+    private getEditableRectangle;
+    private getEditableCircleInfo;
+    private ensureOverlayEditHandler;
+    private destroyOverlayEditHandler;
+    private lockCameraControllerForOverlayEdit;
+    private restoreCameraControllerForOverlayEdit;
+    private clearOverlayEditHandles;
+    private rebuildEditHandles;
+    private createEditHandle;
+    private buildPolygonEditHandles;
+    private buildRectangleEditHandles;
+    private buildCircleEditHandles;
+    private updatePolygonHandlePositions;
+    private computePolygonCenterCartesian;
+    private computePolygonCenterCartographic;
+    private updateRectangleHandlePositions;
+    private updateCircleHandlePositions;
+    private applyEditedPolygon;
+    private applyEditedRectangle;
+    private applyEditedCircle;
+    private pickCartesianOnGlobe;
+    private computeSurfaceDistanceMeters;
+    private circleRadiusHandlePosition;
+    private rectangleToPositions;
+    private positionsToRectangle;
     /**
      * 设置实体 hover 高亮处理器（鼠标移入高亮，移出取消）
      */

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/drawHelper/DrawPolgon.d.ts

@@ -6,6 +6,11 @@ import { BaseDraw, DrawResult, DrawOptions } from './BaseDraw';
 export declare class DrawPolygon extends BaseDraw {
     private currentPolygonEntity;
     private currentBorderEntity;
+    /**
+     * 结束绘制但未生成最终结果（例如点数不足/自相交被拦截）时的统一清理。
+     * 目标：不留下临时实体/状态副作用（尤其是 depthTestAgainstTerrain）。
+     */
+    private abortFinishCleanup;
     /**
      * 开始绘制
      */

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

@@ -8,6 +8,7 @@ interface I18nLike {
     t(key: string, params?: Record<string, any>, localeOverride?: Locale): string;
     onLocaleChange(cb: (locale: Locale) => void): () => void;
     bindElement(el: HTMLElement, key: string, attr?: "text" | "title" | "placeholder", params?: Record<string, any>): void;
+    updateElement(el: HTMLElement): void;
     updateTree(root: HTMLElement): void;
     addMessages?(locale: Locale, dict: I18nDict, options?: {
         merge?: boolean;

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/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/primitives/CirclePrimitiveLayerStack.d.ts

@@ -5,13 +5,13 @@ export interface CirclePrimitiveLayerCollections {
     ringCollection: Cesium.PrimitiveCollection;
 }
 /**
- * Maintains a stable, ordered layer stack for Circle primitive rendering.
+ * 为 Circle（圆）Primitive 渲染维护一个稳定的有序图层栈。
  *
- * Rendering order:
- * - all fill layers (bottom -> top)
- * - all ring layers (bottom -> top)
+ * 渲染顺序：
+ * - 所有填充图层（从下到上）
+ * - 所有外环图层（从下到上）
  *
- * This ensures boundaries (rings) remain visible even when multiple translucent fills overlap.
+ * 这样可以确保在存在多个半透明填充重叠时，外环边界仍然清晰可见。
  */
 export declare class CirclePrimitiveLayerStack {
     private viewer;

package/dist/libs/overlay/primitives/PolygonPrimitiveLayerStack.d.ts

@@ -5,13 +5,13 @@ export interface PolygonPrimitiveLayerCollections {
     borderCollection: Cesium.PrimitiveCollection;
 }
 /**
- * Maintains a stable, ordered layer stack for Polygon primitive rendering.
+ * 为 Polygon（多边形）Primitive 渲染维护一个稳定的有序图层栈。
  *
- * Rendering order:
- * - all fill layers (bottom -> top)
- * - all border layers (bottom -> top)
+ * 渲染顺序：
+ * - 所有填充图层（从下到上）
+ * - 所有边框图层（从下到上）
  *
- * This ensures borders remain visible even when multiple translucent fills overlap.
+ * 这样可以确保在存在多个半透明填充重叠时，边框仍然清晰可见。
  */
 export declare class PolygonPrimitiveLayerStack {
     private viewer;

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/dist/libs/toolBar/MapToolBarConfig.d.ts

@@ -1,3 +1,10 @@
-import { ButtonConfig } from '../CesiumMapModel';
+import { ButtonConfig, ToolbarConfig } from '../CesiumMapModel';
 export declare const defaultButtonSorts: Record<string, number>;
 export declare const defaultButtons: ButtonConfig[];
+export declare const defaultMeasureItems: {
+    id: string;
+    text: string;
+    textKey: string;
+    icon: string;
+}[];
+export declare const defaultToolBarStyle: ToolbarConfig;

package/dist/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@xingm/vmap-cesium-toolbar",
-  "version": "0.0.2-alpha.17",
+  "version": "0.0.2-alpha.19",
   "description": "A powerful Cesium map toolbar plugin with drawing, measurement, and interaction features",
   "type": "module",
-  "main": "index.js",
-  "module": "index.js",
+  "main": "index.es.js",
+  "module": "index.es.js",
   "types": "index.d.ts",
   "files": [
-    "index.js",
+    "index.es.js",
+    "index.umd.js",
     "index.d.ts",
     "style.css",
     "README.md",
@@ -15,8 +16,8 @@
   ],
   "exports": {
     ".": {
-      "import": "./index.js",
-      "types": "./index.d.ts"
+      "import": "./index.es.js",
+      "default": "./index.es.js"
     },
     "./style": "./style.css"
   },
@@ -36,10 +37,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"
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@xingm/vmap-cesium-toolbar",
-  "version": "0.0.2-alpha.17",
+  "version": "0.0.2-alpha.19",
   "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"
 }