@xingm/vmap-cesium-toolbar 0.0.4 → 0.0.6

package/dist/libs/CesiumMapDraw.d.ts

@@ -30,6 +30,7 @@ declare class DrawHelper {
     private currentDrawer;
     private screenSpaceEventHandler;
     private entityClickHandler;
+    private readonly pickGovernor;
     private terrainRefineQueue;
     private terrainRefineInFlight;
     private terrainRefineLastTick;

package/dist/libs/CesiumMapModel.d.ts

@@ -80,11 +80,11 @@ export interface MapType {
     id: string;
     name: string;
     nameKey?: string;
-    /** 选中态左上角“地名”文案（可选，未配置时走 i18n 默认 key） */
+    /** 选中态左上角“路网”文案（可选，未配置时走 i18n 默认 key） */
     placeNameLabel?: string;
-    /** 选中态左上角“地名”文案 i18n key（可选） */
+    /** 选中态左上角“路网”文案 i18n key（可选） */
     placeNameLabelKey?: string;
-    /** 是否强制始终显示地名层（不受 placeName 开关影响） */
+    /** 是否强制始终显示路网层（不受 placeName 开关影响） */
     forcePlaceName?: boolean;
     thumbnail: string;
     provider: (token: string) => Cesium.ImageryProvider[];

package/dist/libs/CesiumOverlayService.d.ts

@@ -11,6 +11,7 @@ import { MapPolygon, PolygonOptions } from './overlay/MapPolygon';
 import { MapRectangle, RectangleOptions } from './overlay/MapRectangle';
 import { MapCircle, CircleOptions } from './overlay/MapCircle';
 import { MapRing, RingOptions } from './overlay/MapRing';
+import { OverlayEditOptions } from './overlay/OverlayEditHandles';
 export interface CesiumOverlayServiceOptions {
     /**
      * 是否启用实体 hover 处理器（MOUSE_MOVE 下会执行 pick/drillPick 并触发 hover 高亮）。
@@ -23,6 +24,14 @@ export interface CesiumOverlayServiceOptions {
      * 参数为“已回写后的覆盖物 entity”。
      */
     onOverlayEditChange?: (entity: DrawEntity & OverlayEntity) => void;
+    /**
+     * 点击 pick 节流间隔（毫秒）。
+     * 用于降低 “贴地几何 + pick + ground pipeline” 的偶发 DataCloneError 风险。
+     * @default 120
+     */
+    clickPickMinIntervalMs?: number;
+    /** 编辑功能配置项，默认为全开（除 rotate） */
+    overlayEditOptions?: OverlayEditOptions;
 }
 /**
  * Cesium 覆盖物服务类
@@ -42,12 +51,11 @@ export declare class CesiumOverlayService {
     private hoverPickPos;
     private overlayMutationRevision;
     private hoverSuspendUntil;
-    private lastHoverPickTime;
-    private lastHoverPickPos;
     private bulkUpdateDepth;
-    private static readonly HOVER_PICK_MIN_INTERVAL_MS;
-    private static readonly HOVER_PICK_MIN_MOVE_PX;
+    private readonly clickPickMinIntervalMs;
+    private readonly pickGovernor;
     private static readonly HOVER_SUSPEND_AFTER_MUTATION_MS;
+    private static readonly CLICK_PICK_MIN_INTERVAL_MS;
     private markOverlayMutated;
     /**
      * 显式开始一次批量更新：在 begin/end 期间暂停 hover pick。
@@ -80,11 +88,6 @@ export declare class CesiumOverlayService {
     readonly circle: MapCircle;
     readonly ring: MapRing;
     constructor(viewer: Viewer, options?: CesiumOverlayServiceOptions);
-    /**
-     * Cesium 默认可能无法 pick 到半透明覆盖物（例如 alpha < 1 的填充面）。
-     * 开启 pickTranslucentDepth 后，hover/click 才能稳定命中半透明面。
-     */
-    private enableTranslucentPicking;
     /**
      * 尝试从屏幕坐标拾取地表/模型位置并转为 Cartographic
      */
@@ -118,8 +121,10 @@ export declare class CesiumOverlayService {
      * 开启/关闭覆盖物编辑模式。
      * - 开启后：点击覆盖物会进入编辑，并显示可拖拽控制点。
      * - 关闭后：退出编辑并移除控制点。
+     * @param enabled 是否启用编辑模式
+     * @param overlayEditOptions 编辑功能配置项，可选。不传时使用构造函数传入的配置或默认配置
      */
-    setOverlayEditMode(enabled: boolean): void;
+    setOverlayEditMode(enabled: boolean, overlayEditOptions?: OverlayEditOptions): void;
     /** 当前是否处于覆盖物编辑模式（全局开关） */
     getOverlayEditModeEnabled(): boolean;
     /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
@@ -128,7 +133,7 @@ export declare class CesiumOverlayService {
      * 主动开始编辑某个覆盖物。
      * @returns true 表示成功进入编辑
      */
-    startOverlayEdit(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
+    startOverlayEdit(entityOrId: (DrawEntity & OverlayEntity) | string, options?: OverlayEditOptions): boolean;
     /**
      * 设置实体 hover 高亮处理器（鼠标移入高亮，移出取消）
      */

package/dist/libs/CesiumPointClusterLayer.d.ts

@@ -66,6 +66,7 @@ export interface PointClusterLayerOptions {
 }
 export default class CesiumPointClusterLayer {
     private static readonly CLUSTER_STYLE_MIN_INTERVAL_MS;
+    private static readonly CLICK_PICK_MIN_INTERVAL_MS;
     private viewer;
     private readonly options;
     private dataSource;
@@ -76,6 +77,7 @@ export default class CesiumPointClusterLayer {
     private clusterStyleRAF;
     private clusterStyleTimer;
     private lastClusterStyleFlushTime;
+    private readonly pickGovernor;
     constructor(viewer: Viewer, options?: PointClusterLayerOptions);
     /** 设置/替换点数据（经纬度单位：度） */
     setData(points: ClusterPoint[]): void;

package/dist/libs/PickGovernor.d.ts

@@ -0,0 +1,23 @@
+export type PickGovernorKind = 'hover' | 'click' | 'cluster' | 'draw' | 'edit';
+export interface PickGovernorProfile {
+    minIntervalMs: number;
+    minMovePx: number;
+}
+export interface PickGovernorOptions {
+    profiles?: Partial<Record<PickGovernorKind, Partial<PickGovernorProfile>>>;
+}
+type PointLike = {
+    x: number;
+    y: number;
+};
+export declare function isMacPlatform(): boolean;
+export declare class PickGovernor {
+    private readonly profiles;
+    private readonly lastByKind;
+    private suspendUntil;
+    constructor(options?: PickGovernorOptions);
+    shouldPick(kind: PickGovernorKind, point: PointLike, nowMs?: number): boolean;
+    suspend(ms: number): void;
+    private isFinitePoint;
+}
+export {};

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

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

package/dist/libs/i18n/en-US.d.ts

@@ -32,6 +32,9 @@ declare const enUS: {
         overlay: {
             airport: string;
         };
+        map_type: {
+            place_name: string;
+        };
     };
     map_type: {
         normal: string;

package/dist/libs/i18n/zh-CN.d.ts

@@ -32,6 +32,9 @@ declare const zhCN: {
         overlay: {
             airport: string;
         };
+        map_type: {
+            place_name: string;
+        };
     };
     map_type: {
         normal: string;

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

@@ -29,6 +29,8 @@ export interface CircleOptions {
      * - false：填充与边框都使用 position 高度悬空。
      */
     clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
     heightReference?: HeightReference;
     extrudedHeight?: number;
     heightEpsilon?: number;

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

@@ -23,6 +23,8 @@ export interface PolygonOptions {
      * - false：填充与边框都在统一的 baseHeight 上悬空。
      */
     clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
     heightReference?: HeightReference;
     extrudedHeight?: number;
     /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */

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

@@ -9,6 +9,8 @@ export interface PolylineOptions {
     width?: number;
     material?: Cesium.MaterialProperty | Color | string;
     clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
     /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
     clickHighlight?: boolean | {
         color?: Color | string;
@@ -28,6 +30,7 @@ export interface PolylineOptions {
 export declare class MapPolyline {
     private viewer;
     private entities;
+    private readonly avoidGroundPipeline;
     constructor(viewer: Viewer);
     /**
      * 转换位置为 Cartesian3
@@ -41,6 +44,7 @@ export declare class MapPolyline {
      * 解析材质
      */
     private resolveMaterial;
+    private elevatePositions;
     /**
      * 添加 Polyline（折线）
      */

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

@@ -19,6 +19,8 @@ export interface RectangleOptions {
     outlineWidth?: number;
     /** 是否贴地（默认：在粗边框模式下为 true） */
     clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
     /** 悬空时的基准高度（米，clampToGround=false 时有效） */
     height?: number;
     heightReference?: HeightReference;

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

@@ -36,6 +36,8 @@ export interface RingOptions {
     glowPower?: number;
     /** 是否贴地（默认 true） */
     clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
     /** 圆环分段数（默认 128），越大越圆滑 */
     segments?: number;
     /** 覆盖物点击回调 */
@@ -93,7 +95,7 @@ export declare class MapRing {
     /**
      * 更新 Ring 样式
      */
-    updateStyle(entity: Entity, options: Partial<Pick<RingOptions, "color" | "showInnerLine" | "lineColor" | "lineStyle" | "lineMaterialMode" | "stripeRepeat" | "dashLength" | "dashPattern" | "gapColor" | "width" | "glowWidth" | "lineWidth" | "glowPower" | "clampToGround" | "segments">>): void;
+    updateStyle(entity: Entity, options: Partial<Pick<RingOptions, "color" | "showInnerLine" | "lineColor" | "lineStyle" | "lineMaterialMode" | "stripeRepeat" | "dashLength" | "dashPattern" | "gapColor" | "width" | "glowWidth" | "lineWidth" | "glowPower" | "clampToGround" | "segments" | "groundHeightEpsilon">>): void;
     /**
      * 显示/隐藏 Ring
      */

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

@@ -1,6 +1,7 @@
 import { Viewer } from '../../../node_modules/cesium';
 import { DrawEntity } from '../drawHelper';
 import { OverlayEntity } from './types';
+import { OverlayEditOptions } from './OverlayEditHandles';
 import * as Cesium from "cesium";
 export type OverlayEditChangeCallback = (entity: DrawEntity & OverlayEntity) => void;
 export interface OverlayEditControllerOptions {
@@ -9,6 +10,8 @@ export interface OverlayEditControllerOptions {
      * 回调参数为“已回写后的覆盖物 entity”。
      */
     onChange?: OverlayEditChangeCallback;
+    /** 编辑功能配置项，默认为全开（除 rotate） */
+    overlayEditOptions?: OverlayEditOptions;
 }
 export interface OverlayEditHost {
     getViewer(): Viewer;
@@ -27,13 +30,19 @@ export interface OverlayEditHost {
     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 readonly pickGovernor;
     private onChange;
     private editingTarget;
     private editingKind;
+    private editingOptions;
     private editingPositions;
     private editingCircleCenter;
     private editingCircleRadiusMeters;
@@ -49,11 +58,36 @@ export declare class OverlayEditController {
     private rotateStartAngle;
     private scaleStartDistance;
     private cameraBackup;
+    /**
+     * 构造函数
+     * @param host 覆盖物编辑宿主对象
+     * @param options 配置选项
+     */
     constructor(host: OverlayEditHost, options?: OverlayEditControllerOptions);
+    /**
+     * 设置编辑变化回调函数
+     * @param cb 回调函数
+     */
     setOnChange(cb?: OverlayEditChangeCallback | null): void;
-    setEnabled(enabled: boolean): void;
+    /**
+     * 设置编辑器启用状态
+     * @param enabled 是否启用
+     * @param options 编辑功能配置项，可选。不传时使用构造函数传入的配置或默认配置
+     */
+    setEnabled(enabled: boolean, options?: OverlayEditOptions): void;
+    /**
+     * 获取编辑器启用状态
+     * @returns 是否启用
+     */
     getEnabled(): boolean;
+    /**
+     * 判断是否正在编辑
+     * @returns 是否正在编辑
+     */
     isEditing(): boolean;
+    /**
+     * 销毁编辑器
+     */
     destroy(): void;
     /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
     stop(): void;
@@ -61,7 +95,12 @@ export declare class OverlayEditController {
      * 主动开始编辑某个覆盖物。
      * @returns true 表示成功进入编辑
      */
-    start(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
+    start(entityOrId: (DrawEntity & OverlayEntity) | string, options?: OverlayEditOptions): boolean;
+    /**
+     * 解析编辑目标实体，根据特定条件返回合适的实体对象
+     * @param entity 输入的实体对象，需要同时满足DrawEntity和OverlayEntity类型
+     * @returns 返回解析后的实体对象，可能是原始实体或符合条件的其他实体
+     */
     private resolveEditTarget;
     private detectEditableKind;
     private getPropertyValue;
@@ -95,6 +134,10 @@ export declare class OverlayEditController {
     private lockCameraController;
     private restoreCameraController;
     private clearHandles;
+    /**
+     * 重建处理句柄的方法
+     * 根据当前编辑的几何图形类型，调用相应的构建函数创建处理句柄
+     */
     private rebuildHandles;
     private getHandleHelpers;
     private createHandle;

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

@@ -11,6 +11,44 @@ export type HandleStyle = {
  * 创建编辑句柄实体
  */
 export type CreateHandle = (position: Cesium.Cartesian3, style: HandleStyle, meta: any) => Cesium.Entity;
+export interface OverlayEditOptions {
+    vertex: {
+        enable?: boolean;
+        color?: Cesium.Color;
+        outlineColor?: Cesium.Color;
+        outlineWidth?: number;
+        pixelSize?: number;
+    } | boolean;
+    mid: {
+        enable?: boolean;
+        color?: Cesium.Color;
+        outlineColor?: Cesium.Color;
+        outlineWidth?: number;
+        pixelSize?: number;
+    } | boolean;
+    move: {
+        enable?: boolean;
+        color?: Cesium.Color;
+        outlineColor?: Cesium.Color;
+        outlineWidth?: number;
+        pixelSize?: number;
+    } | boolean;
+    rotate: {
+        enable?: boolean;
+        color?: Cesium.Color;
+        outlineColor?: Cesium.Color;
+        outlineWidth?: number;
+        pixelSize?: number;
+    } | boolean;
+    scale: {
+        enable?: boolean;
+        color?: Cesium.Color;
+        outlineColor?: Cesium.Color;
+        outlineWidth?: number;
+        pixelSize?: number;
+    } | boolean;
+}
+export declare const DEFAULT_OPTIONS: OverlayEditOptions;
 /**
  * 构建/更新句柄所需的依赖函数集合
  */
@@ -24,23 +62,23 @@ export interface HandleHelpers {
 /**
  * 构建多边形编辑句柄（顶点/中点/整体移动）
  */
-export declare function buildPolygonHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+export declare function buildPolygonHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers, options: OverlayEditOptions): Cesium.Entity[];
 /**
  * 构建矩形编辑句柄（顶点/边中点/整体移动）
  */
-export declare function buildRectangleHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+export declare function buildRectangleHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers, options: OverlayEditOptions): Cesium.Entity[];
 /**
  * 构建折线编辑句柄（顶点/中点/整体移动/旋转/缩放）
  */
-export declare function buildPolylineHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+export declare function buildPolylineHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers, options: OverlayEditOptions): Cesium.Entity[];
 /**
  * 构建点编辑句柄
  */
-export declare function buildPointHandles(pos: Cesium.Cartesian3 | null, helpers: HandleHelpers): Cesium.Entity[];
+export declare function buildPointHandles(pos: Cesium.Cartesian3 | null, helpers: HandleHelpers, options: OverlayEditOptions): Cesium.Entity[];
 /**
  * 构建圆形编辑句柄（圆心/半径）
  */
-export declare function buildCircleHandles(center: Cesium.Cartesian3 | null, radiusMeters: number, helpers: HandleHelpers): Cesium.Entity[];
+export declare function buildCircleHandles(center: Cesium.Cartesian3 | null, radiusMeters: number, helpers: HandleHelpers, options: OverlayEditOptions): Cesium.Entity[];
 /**
  * 更新多边形句柄位置
  * @returns false 表示句柄数量不匹配，需重建

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

@@ -36,6 +36,7 @@ export declare class CirclePrimitiveBatch {
     setColors(circleId: string, ringColor: Cesium.Color, fillColor: Cesium.Color): void;
     private scheduleApplyColors;
     private scheduleRebuild;
+    private assertCloneableInstanceId;
     private rebuild;
     private applyCurrentColors;
 }

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

@@ -37,6 +37,7 @@ export declare class PolygonPrimitiveBatch {
     private scheduleApplyColors;
     setBorderWidth(polygonId: string, borderWidth: number): void;
     private scheduleRebuild;
+    private assertCloneableInstanceId;
     private rebuild;
     private applyCurrentColors;
 }

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

@@ -35,6 +35,7 @@ export declare class RectanglePrimitiveBatch {
     setColors(rectangleId: string, ringColor: Cesium.Color, fillColor: Cesium.Color): void;
     private scheduleApplyColors;
     private scheduleRebuild;
+    private assertCloneableInstanceId;
     private rebuild;
     private applyCurrentColors;
 }

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

@@ -87,6 +87,8 @@ export interface OverlayEntity extends Entity {
     _clampToGround?: boolean;
     /** 复合形状的基准高度（米，clampToGround=false 时有效） */
     _baseHeight?: number;
+    /** 贴地抬高量（米，clampToGround=true 时有效） */
+    _groundHeightEpsilon?: number;
     _isThickOutline?: boolean;
     _outlineWidth?: number;
     _isRing?: boolean;

package/dist/libs/toolBar/MapLayersService.d.ts

@@ -35,7 +35,7 @@ export declare class MapLayersService {
     private useI18n;
     constructor(viewer: Viewer, toolbarElement: HTMLElement, config: MapLayersServiceConfig);
     /**
-     * 初始化当前地图上下文：用于“初始底图不是通过 switchMapType 加载”时的地名层识别。
+     * 初始化当前地图上下文：用于“初始底图不是通过 switchMapType 加载”时的路网层识别。
      */
     private bootstrapCurrentMapContext;
     /**

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingm/vmap-cesium-toolbar",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "A powerful Cesium map toolbar plugin with drawing, measurement, and interaction features",
   "type": "module",
   "main": "index.es.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingm/vmap-cesium-toolbar",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A powerful Cesium map toolbar plugin with drawing, measurement, and interaction features",
   "type": "module",
   "main": "dist/index.es.js",