@xingm/vmap-cesium-toolbar 0.0.3 → 0.0.4

package/dist/libs/CesiumMapDraw.d.ts

@@ -20,11 +20,7 @@ declare class DrawHelper {
     private publicEntities;
     private _doubleClickPending;
     private lastPreviewPosition;
-    private drawHintEntity;
-    private drawHintText;
-    private drawHintLastPosition;
-    private drawHintOverrideText;
-    private drawHintOverrideUntil;
+    private drawHintHelper;
     private lastLeftClickDebug;
     private static activeDrawingHelper;
     private drawLine;
@@ -56,6 +52,10 @@ declare class DrawHelper {
      * 其它模块（如覆盖物服务）继续触发 pick，引发 ground/worker 相关异常。
      */
     private setPickCooldown;
+    /**
+     * 检查当前是否处于拾取(blocked)状态
+     * @returns {boolean} 如果当前时间小于设定的阻塞时间，则返回true表示拾取被阻塞，否则返回false
+     */
     private isPickBlocked;
     /**
      * 在实体被加入场景后、渲染循环更新前做一次快速校验。
@@ -73,6 +73,11 @@ declare class DrawHelper {
      * @param viewer Cesium Viewer 实例
      */
     constructor(viewer: Cesium.Viewer);
+    /**
+     * 检测并输出可能存在高度限制问题的实体信息
+     * @param tag 标识本次检测的唯一标签
+     * @returns 返回包含检测结果的报告对象
+     */
     private dumpPotentialClampingEntities;
     /**
      * 对新创建的实体进行净化处理，确保其符合渲染要求
@@ -80,7 +85,16 @@ declare class DrawHelper {
      * @param tag - 用于标识来源的标签，会在控制台警告时显示
      */
     private sanitizeNewEntity;
+    /**
+     * 安装实体添加钩子函数，用于在实体被添加到EntityCollection时进行安全检查和处理
+     * 这是一个私有方法，主要用于拦截和修改Cesium中EntityCollection的add方法
+     */
     private installEntitiesAddHook;
+    /**
+     * 卸载实体集合添加钩子函数
+     * 该方法用于移除之前添加到EntityCollection原型中的自定义add方法
+     * 恢复原始的add方法实现
+     */
     private uninstallEntitiesAddHook;
     /**
      * 安装地面几何更新器调试钩子
@@ -95,32 +109,6 @@ declare class DrawHelper {
      * 根据场景模式更新偏移高度
      */
     private updateOffsetHeight;
-    /**
-     * 计算提示文本（随绘制模式 + 点数量变化）
-     */
-    private getDrawHintText;
-    /**
-     * 设置绘制提示覆盖文本及其持续时间
-     * @param text 要显示的提示文本
-     * @param ms 提示文本显示的持续时间（毫秒），默认为1200毫秒
-     */
-    private setDrawHintOverride;
-    /**
-     * 将提示位置转换为显示位置（按当前模式做轻微抬高，避免被地形遮挡）
-     */
-    private toHintDisplayPosition;
-    /**
-     * 创建或更新提示实体的位置与文本
-     */
-    private updateDrawHintPosition;
-    /**
-     * 更新提示文本（不改变位置；通常在点数变化时调用）
-     */
-    private refreshDrawHintTextOnly;
-    /**
-     * 清除绘制提示实体
-     */
-    private clearDrawHint;
     /**
      * 开始绘制线条
      */

package/dist/libs/CesiumMapLoader.d.ts

@@ -8,6 +8,7 @@ interface InitOptions {
     terrain?: Terrain;
     terrainProvider?: TerrainProvider;
     mapType?: string;
+    tdtMapTypeId?: string;
     imageryProvider?: Cesium.UrlTemplateImageryProvider;
     imageryLayers?: Cesium.ImageryLayerCollection;
     terrainShadows?: Cesium.ShadowMode;

package/dist/libs/CesiumMapModel.d.ts

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

package/dist/libs/CesiumOverlayService.d.ts

@@ -36,6 +36,7 @@ export declare class CesiumOverlayService {
     /** 构造参数（用于开关 hover handler 等运行时策略） */
     private readonly options;
     private overlayEditor;
+    private overlayHighlight;
     private lastHoverTargets;
     private hoverPickRAF;
     private hoverPickPos;
@@ -44,10 +45,6 @@ export declare class CesiumOverlayService {
     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;
@@ -70,12 +67,6 @@ export declare class CesiumOverlayService {
      * 需要映射回 overlayMap 内的根覆盖物 id。
      */
     private normalizeOverlayPickId;
-    private getEntityPropertyString;
-    private mapGlowOutlineEntityToRoot;
-    private getClosedPositions;
-    private generateEllipseOutlinePositions;
-    private ensureGlowOutline;
-    private removeGlowOutline;
     private resolveOverlayByPickId;
     private resolvePickedOverlayEntity;
     readonly marker: MapMarker;
@@ -117,6 +108,12 @@ export declare class CesiumOverlayService {
      * 设置实体点击处理器
      */
     private setupEntityClickHandler;
+    /**
+     * 开启或是关闭覆盖物的Hover高亮（鼠标移入高亮，移出取消）。
+     * - 开启后：覆盖物会触发高亮，且高亮状态会在鼠标移出时取消。
+     * - 关闭后：覆盖物不再触发 hover 高亮。
+     */
+    toggleOverlayHoverHighlight(enabled: boolean): void;
     /**
      * 开启/关闭覆盖物编辑模式。
      * - 开启后：点击覆盖物会进入编辑，并显示可拖拽控制点。
@@ -138,16 +135,6 @@ export declare class CesiumOverlayService {
     private setupEntityHoverHandler;
     private getPropertyValue;
     private getNumberProperty;
-    private resolveHighlightOptions;
-    private getActiveHighlightOptions;
-    private setOverlayHighlightReason;
-    private applyOverlayHighlightStyle;
-    /**
-     * 恢复覆盖物的高亮样式
-     * @param entity - 覆盖物实体对象
-     * @returns 无返回值
-     */
-    private restoreOverlayHighlightStyle;
     /**
      * 生成唯一ID
      */

package/dist/libs/CesiumPointClusterLayer.d.ts

@@ -1,4 +1,4 @@
-import { Viewer } from '../../node_modules/cesium';
+import { Viewer, Entity } from '../../node_modules/cesium';
 import * as Cesium from 'cesium';
 export interface ClusterPoint {
     /** 业务 id（可选，建议传以便稳定更新） */
@@ -40,6 +40,17 @@ export interface PointClusterLayerOptions {
     clusterPixelSize?: number;
     /** 聚合点样式分段：用 count 决定颜色/大小 */
     clusterStyleSteps?: ClusterStyleStep[];
+    /** 自定义聚合点渲染（直接修改 cluster entity） */
+    renderCluster?: (args: {
+        cluster: Entity;
+        clusteredEntities: Entity[];
+        count: number;
+    }) => void;
+    /** 自定义单点渲染（直接修改 point entity） */
+    renderSinglePoint?: (args: {
+        entity: Entity;
+        point: ClusterPoint;
+    }) => void;
     /** 点击聚合点回调：返回该聚合内的原始点 */
     onClusterClick?: (points: ClusterPoint[], ctx: {
         screenPosition: Cesium.Cartesian2;
@@ -54,18 +65,25 @@ export interface PointClusterLayerOptions {
     idPrefix?: string;
 }
 export default class CesiumPointClusterLayer {
+    private static readonly CLUSTER_STYLE_MIN_INTERVAL_MS;
     private viewer;
     private readonly options;
     private dataSource;
     private entityIdToPoint;
     private clickHandler;
     private readonly layerId;
+    private pendingClusterStyles;
+    private clusterStyleRAF;
+    private clusterStyleTimer;
+    private lastClusterStyleFlushTime;
     constructor(viewer: Viewer, options?: PointClusterLayerOptions);
     /** 设置/替换点数据（经纬度单位：度） */
     setData(points: ClusterPoint[]): void;
     setVisible(visible: boolean): void;
     setClusteringEnabled(enabled: boolean): void;
     destroy(): void;
+    private enqueueClusterStyle;
+    private flushClusterStyles;
     private applyClusterStyle;
     private pickStyle;
     private installClickHandler;

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

@@ -11,6 +11,7 @@ export declare class DrawCircle extends BaseDraw {
      * 开始绘制
      */
     startDrawing(options?: DrawOptions): void;
+    addPoint(position: Cartesian3): void;
     /**
      * 更新绘制实体（预览）
      */

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

@@ -0,0 +1,32 @@
+import * as Cesium from "cesium";
+type DrawMode = "line" | "polygon" | "rectangle" | "circle" | null;
+type DrawHintState = {
+    isDrawing: boolean;
+    drawMode: DrawMode;
+    tempPositions: Cesium.Cartesian3[];
+    offsetHeight: number;
+};
+export declare class DrawHintHelper {
+    private entities;
+    private getState;
+    private translate;
+    private drawHintEntity;
+    private drawHintText;
+    private drawHintLastPosition;
+    private drawHintOverrideText;
+    private drawHintOverrideUntil;
+    constructor(entities: Cesium.EntityCollection, getState: () => DrawHintState, translate: (key: string, params?: Record<string, any>) => string);
+    handleSceneModeChanged(): void;
+    setOverride(options: Cesium.LabelGraphics | Cesium.LabelGraphics.ConstructorOptions, ms?: number): void;
+    updatePosition(position: Cesium.Cartesian3): void;
+    refreshTextOnly(): void;
+    clear(): void;
+    /**
+     * 获取绘图提示文本的公共方法
+     * 根据当前的绘图状态和模式返回相应的提示信息
+     * @returns {string} 返回对应的提示文本，如果不在绘图状态则返回空字符串
+     */
+    getDrawHintText(): string;
+    private toHintDisplayPosition;
+}
+export {};

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

@@ -3,3 +3,4 @@ export { DrawLine } from './DrawLine';
 export { DrawPolygon } from './DrawPolgon';
 export { DrawRectangle } from './DrawRectangle';
 export { DrawCircle } from './DrawCircle';
+export { DrawHintHelper } from './DrawHint';

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

@@ -62,6 +62,7 @@ export declare class OverlayEditController {
      * @returns true 表示成功进入编辑
      */
     start(entityOrId: (DrawEntity & OverlayEntity) | string): boolean;
+    private resolveEditTarget;
     private detectEditableKind;
     private getPropertyValue;
     private getNumberProperty;
@@ -72,21 +73,22 @@ export declare class OverlayEditController {
     private getEditablePointPosition;
     private getEditableRectangle;
     private getEditableCircleInfo;
-    /**
-     * 确保编辑处理器已初始化
-     * 如果处理器不存在，则创建一个新的 ScreenSpaceEventHandler 并设置各种交互事件处理函数
-     * @private
-     */
-    /**
-     * 确保事件处理器已初始化
-     * 如果处理器不存在，则创建并设置各种事件处理函数
-     * @private
-     */
     /**
      * 确保屏幕空间事件处理器已初始化
      * 如果处理器不存在，则创建一个新的处理器并设置各种交互事件
      */
     private ensureHandler;
+    private beginDrag;
+    private beginMoveDrag;
+    private computeMovedPositions;
+    private emitChange;
+    private prepareOnChangeTarget;
+    private resolveOverlayTypeFromId;
+    private attachMarkerLngLat;
+    private attachPolylineLngLat;
+    private attachCircleLngLat;
+    private attachPolygonLngLat;
+    private attachRectangleLngLat;
     private captureDragSnapshot;
     private isGeometryChangedSinceSnapshot;
     private destroyHandler;
@@ -94,17 +96,8 @@ export declare class OverlayEditController {
     private restoreCameraController;
     private clearHandles;
     private rebuildHandles;
+    private getHandleHelpers;
     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;
@@ -112,10 +105,14 @@ export declare class OverlayEditController {
     private applyEditedPoint;
     private getEditingClampToGround;
     private getCartesianHeight;
+    private convertOutlineToLngLat;
+    private convertPositionToLngLat;
+    private convertCartoToLngLat;
     private pickCartesianOnGlobe;
     private computeSurfaceDistanceMeters;
     private circleRadiusHandlePosition;
     private rectangleToPositions;
+    private rectangleToLngLatPositions;
     private positionsToRectangle;
     private getRectangleEditHeight;
     private computePolygonCenterCartesian;

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

@@ -0,0 +1,63 @@
+import * as Cesium from "cesium";
+/**
+ * 句柄样式（颜色/描边/像素大小）
+ */
+export type HandleStyle = {
+    color: Cesium.Color;
+    outlineColor: Cesium.Color;
+    pixelSize: number;
+};
+/**
+ * 创建编辑句柄实体
+ */
+export type CreateHandle = (position: Cesium.Cartesian3, style: HandleStyle, meta: any) => Cesium.Entity;
+/**
+ * 构建/更新句柄所需的依赖函数集合
+ */
+export interface HandleHelpers {
+    createHandle: CreateHandle;
+    computePolygonCenterCartesian: (positions: Cesium.Cartesian3[]) => Cesium.Cartesian3;
+    computePolylineHandleRadius: (positions: Cesium.Cartesian3[], center: Cesium.Cartesian3) => number;
+    offsetByMeters: (center: Cesium.Cartesian3, meters: number, bearingDeg: number) => Cesium.Cartesian3;
+    circleRadiusHandlePosition: (center: Cesium.Cartesian3, radiusMeters: number) => Cesium.Cartesian3;
+}
+/**
+ * 构建多边形编辑句柄（顶点/中点/整体移动）
+ */
+export declare function buildPolygonHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+/**
+ * 构建矩形编辑句柄（顶点/边中点/整体移动）
+ */
+export declare function buildRectangleHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+/**
+ * 构建折线编辑句柄（顶点/中点/整体移动/旋转/缩放）
+ */
+export declare function buildPolylineHandles(verts: Cesium.Cartesian3[], helpers: HandleHelpers): Cesium.Entity[];
+/**
+ * 构建点编辑句柄
+ */
+export declare function buildPointHandles(pos: Cesium.Cartesian3 | null, helpers: HandleHelpers): Cesium.Entity[];
+/**
+ * 构建圆形编辑句柄（圆心/半径）
+ */
+export declare function buildCircleHandles(center: Cesium.Cartesian3 | null, radiusMeters: number, helpers: HandleHelpers): Cesium.Entity[];
+/**
+ * 更新多边形句柄位置
+ * @returns false 表示句柄数量不匹配，需重建
+ */
+export declare function updatePolygonHandlePositions(verts: Cesium.Cartesian3[], handles: Cesium.Entity[], helpers: HandleHelpers): boolean;
+/**
+ * 更新折线句柄位置
+ * @returns false 表示句柄数量不匹配，需重建
+ */
+export declare function updatePolylineHandlePositions(verts: Cesium.Cartesian3[], handles: Cesium.Entity[], helpers: HandleHelpers): boolean;
+/**
+ * 更新点句柄位置
+ * @returns false 表示句柄数量不匹配或参数为空
+ */
+export declare function updatePointHandlePositions(pos: Cesium.Cartesian3 | null, handles: Cesium.Entity[]): boolean;
+/**
+ * 更新圆形句柄位置
+ * @returns false 表示句柄数量不匹配或参数为空
+ */
+export declare function updateCircleHandlePositions(center: Cesium.Cartesian3 | null, radiusMeters: number, handles: Cesium.Entity[], helpers: HandleHelpers): boolean;

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

@@ -0,0 +1,40 @@
+import { Entity } from '../../../node_modules/cesium';
+import { DrawEntity } from '../drawHelper';
+import { OverlayEntity } from './types';
+import { MapCircle } from './MapCircle';
+import { MapPolygon } from './MapPolygon';
+import { MapRectangle } from './MapRectangle';
+import * as Cesium from "cesium";
+export interface OverlayHighlightHost {
+    getEntities(): Cesium.EntityCollection;
+    getOverlayById(id: string): (DrawEntity & OverlayEntity) | undefined;
+    getPropertyValue<T>(prop: any, fallback: T): T;
+    getNumberProperty(prop: any, fallback: number): number;
+    getCircle(): MapCircle;
+    getPolygon(): MapPolygon;
+    getRectangle(): MapRectangle;
+}
+export declare class OverlayHighlight {
+    private readonly host;
+    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 readonly entities;
+    constructor(host: OverlayHighlightHost);
+    mapGlowOutlineEntityToRoot(entity: Cesium.Entity): (DrawEntity & OverlayEntity) | null;
+    setOverlayHighlightReason(targets: Entity[], reason: "click" | "hover", enabled: boolean): void;
+    toggleOverlayHighlight(entity: OverlayEntity, reason?: "click" | "hover"): void;
+    setOverlayHighlight(entityOrId: OverlayEntity | string, enabled: boolean, reason?: "click" | "hover"): boolean;
+    private getEntityPropertyString;
+    private getPropertyValue;
+    private getNumberProperty;
+    private resolveHighlightOptions;
+    private getActiveHighlightOptions;
+    private getClosedPositions;
+    private generateEllipseOutlinePositions;
+    private ensureGlowOutline;
+    private removeGlowOutline;
+    private applyOverlayHighlightStyle;
+    private restoreOverlayHighlightStyle;
+}

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

@@ -13,21 +13,31 @@ export interface MapLayersServiceConfig {
     i18n?: I18nLike;
     useI18n?: boolean;
     onMapTypeChange?: (mapTypeId: string) => void;
-    onNoFlyZoneToggle?: (isChecked: boolean) => void;
     onShowNoFlyZones?: () => Promise<void> | void;
+    onNoFlyZoneToggle?: (isChecked: boolean) => void;
 }
 /**
  * 图层服务类
  * 负责处理地图图层切换相关的所有逻辑
  */
 export declare class MapLayersService {
+    private static readonly PLACE_NAME_LAYER_TAG;
     private viewer;
     private toolbarElement;
     private config;
     private currentGeoWTFS;
+    private currentMapTypeConfig;
+    private currentMapLayers;
+    private currentPlaceNameProvider;
+    private currentPlaceNameLayer;
+    private isPlaceNameChecked;
     private i18n;
     private useI18n;
     constructor(viewer: Viewer, toolbarElement: HTMLElement, config: MapLayersServiceConfig);
+    /**
+     * 初始化当前地图上下文：用于“初始底图不是通过 switchMapType 加载”时的地名层识别。
+     */
+    private bootstrapCurrentMapContext;
     /**
      * 更新配置
      */
@@ -61,6 +71,13 @@ export declare class MapLayersService {
      * 获取当前地图类型
      */
     getCurrentMapType(): string;
+    private setPlaceNameChecked;
+    private shouldEnablePlaceName;
+    private isSameProvider;
+    private resolveExistingPlaceNameLayer;
+    private ensurePlaceNameProvider;
+    private addPlaceNameLayer;
+    private removePlaceNameLayer;
     /**
      * 关闭图层菜单
      */

package/dist/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@xingm/vmap-cesium-toolbar",
+  "version": "0.0.4",
+  "description": "A powerful Cesium map toolbar plugin with drawing, measurement, and interaction features",
+  "type": "module",
+  "main": "index.es.js",
+  "module": "index.es.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.es.js",
+    "index.umd.js",
+    "index.d.ts",
+    "style.css",
+    "README.md",
+    "geojson"
+  ],
+  "exports": {
+    ".": {
+      "import": "./index.es.js",
+      "default": "./index.es.js"
+    },
+    "./style": "./style.css"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "keywords": [
+    "cesium",
+    "map",
+    "toolbar",
+    "drawing",
+    "measurement",
+    "vue3",
+    "typescript"
+  ],
+  "author": "pengxueyou",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BenXueYou/vmap-cesium-tool.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BenXueYou/vmap-cesium-tool/issues"
+  },
+  "homepage": "https://github.com/BenXueYou/vmap-cesium-tool#readme"
+}