cesium-xs-sdk 1.0.16 → 1.0.18

package/dist/cesium-xs-sdk.cjs.js

@@ -3566,6 +3566,58 @@ class EventModule {
     }
 }
 
+/**
+ * 双击判定器
+ *
+ * 背景：Cesium 的 ScreenSpaceEventType.LEFT_DOUBLE_CLICK 唯一来源是 canvas 上的
+ * DOM dblclick 事件，而 DOM dblclick 依赖浏览器/操作系统的双击合成
+ * （时间阈值 + 位移阈值 + 触屏 touch slop + 双击缩放启发式），移动场景下经常
+ * 不触发，导致"双击结束绘制/测量"在移动端静默失效。
+ *
+ * 本判定器在 SDK 自己的 LEFT_CLICK（mouse:click）流水上自维护双击判定：
+ * 连续两次 click 间隔 < 时间阈值 且 屏幕位移 < 位移阈值，即判定为双击。
+ * 如此双击收尾在鼠标、触屏、任何浏览器上行为一致，彻底移除对 DOM dblclick
+ * 合成的依赖（桌面端 DOM dblclick 路径保留作为冗余，二者靠
+ * _isDrawing / _isMeasuring 守卫天然防重）。
+ *
+ * 阈值取向：宁可漏判（用户多点一下），不可误判（把正常快速加点误判成双击收尾）。
+ */
+const DOUBLE_CLICK_INTERVAL_MS = 300; // 时间阈值（ms）
+const DOUBLE_CLICK_DISTANCE_PX = 10;  // 屏幕位移阈值（px）
+
+class DoubleClickDetector {
+  constructor() {
+    /** @type {{timestamp: number, screenPos: {x: number, y: number}} | null} */
+    this._last = null;
+  }
+
+  /**
+   * 清空内部状态。工具 activate / deactivate / 绘制会话结束 / 取消时调用，
+   * 避免跨工具、跨绘制会话的脏状态污染下一次判定。
+   */
+  reset() {
+    this._last = null;
+  }
+
+  /**
+   * 喂入一次 click，返回是否构成双击。
+   * 注意：无论是否构成双击，本次点击都会成为下次判定的"上一次点击"。
+   *
+   * @param {number} timestamp performance.now()
+   * @param {{x: number, y: number}} screenPos 屏幕坐标（取 movement.position）
+   * @returns {boolean} 是否构成双击
+   */
+  feed(timestamp, screenPos) {
+    const prev = this._last;
+    this._last = { timestamp, screenPos };
+    if (!prev) return false;
+    if (timestamp - prev.timestamp > DOUBLE_CLICK_INTERVAL_MS) return false;
+    const dx = screenPos.x - prev.screenPos.x;
+    const dy = screenPos.y - prev.screenPos.y;
+    return Math.hypot(dx, dy) <= DOUBLE_CLICK_DISTANCE_PX;
+  }
+}
+
 const Cesium$d = getCesium();
 
 /**
@@ -3581,6 +3633,8 @@ class BaseTool {
     this._options = options;
     this._isActive = false;
     this._handlers = []; // 注册的事件处理器 ID
+    // 自维护双击判定器（DOM dblclick 在移动端经常不合成，见 DoubleClickDetector 注释）
+    this._doubleClickDetector = new DoubleClickDetector();
   }
 
   /**
@@ -3589,6 +3643,8 @@ class BaseTool {
   activate() {
     if (this._isActive) return;
     this._isActive = true;
+    // 防止跨工具切换时残留上次会话的末次点击，污染本次双击判定
+    this._doubleClickDetector.reset();
     this.onActivate();
   }
 
@@ -3598,6 +3654,7 @@ class BaseTool {
   deactivate() {
     if (!this._isActive) return;
     this._isActive = false;
+    this._doubleClickDetector.reset();
     this.onDeactivate();
     this.clearHandlers();
   }
@@ -3612,6 +3669,19 @@ class BaseTool {
    */
   onDeactivate() { }
 
+  /**
+   * 判定本次 mouse:click 是否构成"双击"（自维护判定，不依赖 DOM dblclick 合成）。
+   * 子类应在"绘制 / 测量进行中"才调用本方法，避免把开启新会话的首次点击误判为双击。
+   * @param {object} movement Cesium click 事件 movement（取 movement.position 作为屏幕坐标）
+   * @returns {boolean}
+   * @protected
+   */
+  _isDoubleClick(movement) {
+    const pos = movement && movement.position;
+    if (!pos) return false;
+    return this._doubleClickDetector.feed(performance.now(), { x: pos.x, y: pos.y });
+  }
+
   /**
    * 注册事件观察者
    * @param {string} eventType 事件类型
@@ -3941,8 +4011,30 @@ class DrawTool extends BaseTool {
     // lngLat 已经是经纬度数组 [lon, lat, height]
     if (!lngLat) return;
 
-    // 优先处理标绘类型
     const plotConfig = PLOT_DRAW_CONFIG[this._drawType];
+
+    // === 自维护双击收尾判定 ===
+    // DOM dblclick 在移动端/触屏经常不被浏览器合成（见 change-log），这里在
+    // LEFT_CLICK 流水上自行判定：绘制中 + 类型支持双击收尾 + 两次 click
+    // 时间/位移在阈值内 → 收尾。本次（双击第二次）点击不加点——双击第一次
+    // 点击已把最后顶点加入 _tempPositions，直接收尾的结果与 DOM dblclick
+    // 路径（_onDoubleClick pop 掉重叠点）逐点一致。
+    // 不满足最小点数时降级为普通加点，落到下方正常逻辑。
+    if (this._isDrawing && this._supportsDoubleClickFinish() && this._isDoubleClick(movement)) {
+      const minPoints = plotConfig ? plotConfig.minPoints
+        : (this._drawType === DrawType.POLYGON ? 3 : 2); // 线 2 / 面 3
+      if (this._tempPositions.length >= minPoints) {
+        if (plotConfig) {
+          this._finishPlotDrawing(plotConfig);
+        } else {
+          this.finishDrawing();
+        }
+        return;
+      }
+      // 不满足最小点数：本次点击降级为普通加点（落到下方逻辑）
+    }
+
+    // 优先处理标绘类型
     if (plotConfig) {
       this._handlePlotClick(lngLat, plotConfig);
       return;
@@ -4082,6 +4174,18 @@ class DrawTool extends BaseTool {
     }
   }
 
+  /**
+   * 当前绘制类型是否支持"双击收尾"：
+   * 仅线 / 面 / 声明了 finishOnDoubleClick 的标绘类型支持；
+   * 点 / 矩形 / 圆保持不响应（与 _onDoubleClick 的语义一致）。
+   * @private
+   */
+  _supportsDoubleClickFinish() {
+    if (this._drawType === DrawType.LINE || this._drawType === DrawType.POLYGON) return true;
+    const plotConfig = PLOT_DRAW_CONFIG[this._drawType];
+    return !!(plotConfig && plotConfig.finishOnDoubleClick);
+  }
+
   /**
    * 双击结束绘制（移动端用：移动端没有右键；桌面端：避免绘制过程中双击误触发放大）
    * 与 _onRightClick 等价，仅线 / 面 / 标绘（声明了 finishOnDoubleClick 的）响应；
@@ -4747,6 +4851,9 @@ class DrawTool extends BaseTool {
     this._tempPositions = [];
     this._previewPlot = null;
 
+    // 绘制会话结束：清空双击判定器，避免下次绘制的开头点击与本次末次点击构成误判
+    this._doubleClickDetector.reset();
+
     this._emitGraphicCreated(config.plotType, id);
   }
 
@@ -4778,6 +4885,8 @@ class DrawTool extends BaseTool {
     this._clickCount = 0;
     this._startPos = null;
     this._currentMousePos = null;
+    // 绘制会话取消：清空双击判定器，避免下次绘制受本次末次点击污染
+    this._doubleClickDetector.reset();
     this._emitDrawCancel();
   }
 
@@ -4833,6 +4942,9 @@ class DrawTool extends BaseTool {
     this._clickCount = 0;
     this._currentMousePos = null;
 
+    // 绘制会话结束：清空双击判定器，避免下次绘制的开头点击与本次末次点击构成误判
+    this._doubleClickDetector.reset();
+
     if (deferredPreviewLine) {
       requestAnimationFrame(() => this.removeTempEntity(deferredPreviewLine));
     }
@@ -7734,7 +7846,7 @@ class MeasureTool extends BaseTool {
     controller.enableRotate = this._originalEnableRotate;
   }
 
-  _onClick(lngLat, _pickedEntity, _movement) {
+  _onClick(lngLat, _pickedEntity, movement) {
     if (!lngLat) return;
 
     // 拖拽刚结束：吞掉紧跟 mouseup 的 click，避免误开新测量
@@ -7743,6 +7855,21 @@ class MeasureTool extends BaseTool {
       return;
     }
 
+    // === 自维护双击收尾判定 ===
+    // DOM dblclick 在移动端/触屏经常不被浏览器合成（见 change-log），这里在
+    // LEFT_CLICK 流水上自行判定：测量中（非拖拽中）+ 两次 click 时间/位移在
+    // 阈值内 → 收尾。本次（双击第二次）点击不加点——双击第一次点击已把最后
+    // 顶点加入 _positions，直接收尾的结果与 DOM dblclick 路径（_onDoubleClick
+    // pop 掉重叠点）逐点一致。不满足最小点数时降级为普通加点。
+    if (this._isMeasuring && !this._isDragging && this._isDoubleClick(movement)) {
+      const minPoints = this._measureType === MeasureType.AREA ? 3 : 2;
+      if (this._positions.length >= minPoints) {
+        this._finishMeasurement();
+        return;
+      }
+      // 不满足最小点数：本次点击降级为普通加点（落到下方逻辑）
+    }
+
     // 同步鼠标位置为本次 click 的经纬度：修复"地图拖动后原地点击 → 预览线
     // 自动连接到旧鼠标位置"的 bug（主要暴露在移动端双击完成测量后）。
     //
@@ -7981,6 +8108,9 @@ class MeasureTool extends BaseTool {
     // 测量已完成 → 恢复地图拖动 / 旋转
     this._restoreCameraAfterMeasuring();
 
+    // 测量会话结束：清空双击判定器，避免下次测量受本次末次点击污染
+    this._doubleClickDetector.reset();
+
     this._emitMeasureComplete(result);
   }
 
@@ -8082,6 +8212,8 @@ class MeasureTool extends BaseTool {
     this.clearMeasurements();
     // 取消时也要恢复地图拖动（与 _finishMeasurement 对称）
     this._restoreCameraAfterMeasuring();
+    // 测量会话取消：清空双击判定器，避免下次测量受本次末次点击污染
+    this._doubleClickDetector.reset();
     this._emitMeasureCancel();
   }
 
@@ -8956,6 +9088,9 @@ class EditorModule {
     this.currentToolName = name;
     this.currentTool.activate();
     this._isActive = true;
+    // 供其他组件（如 Zoom 双击缩放）感知"编辑器工具激活中"，
+    // 工具激活期间双击/右键有工具自身语义，缩放等全局交互应让行
+    this.viewer.xs3dEditorActive = true;
 
     console.log(`工具 ${name} 已激活`);
     return this;
@@ -8972,6 +9107,9 @@ class EditorModule {
     this.currentTool = null;
     this.currentToolName = null;
     this._isActive = false;
+    if (this.viewer) {
+      this.viewer.xs3dEditorActive = false;
+    }
 
     return this;
   }
@@ -9602,10 +9740,13 @@ class LocationBar extends BaseControl {
     // 鼠标移动：更新鼠标位置信息
     const canvas = this._viewer.scene.canvas;
     this._addDomEvent(canvas, 'mousemove', this._onMouseMove.bind(this));
-    this._addDomEvent(canvas, 'mouseleave', this._onMouseLeave.bind(this));
+    // 鼠标移出画布不再重置为 '-'：保留最后拾取的坐标（见 _onMouseMove 说明）
 
     // 相机变化：更新方向/俯仰/视高/层级
     this._addCesiumHandler(this._viewer.camera.changed, this._onCameraChanged.bind(this));
+    // flyTo 动画尾段每帧位移小于 percentageChanged 阈值后 changed 不再触发，
+    // 信息栏会滞后一级；相机停止移动时强制刷新一次
+    this._addCesiumHandler(this._viewer.camera.moveEnd, this._onCameraChanged.bind(this));
 
     // FPS
     if (this._showFPS) {
@@ -9644,16 +9785,10 @@ class LocationBar extends BaseControl {
         lat: Cesium$6.Math.toDegrees(cartographic.latitude).toFixed(this._latDecimal),
         alt: cartographic.height.toFixed(2)
       };
-    } else {
-      this._lastMouseData = { lng: '-', lat: '-', alt: '-' };
+      this._updateContent();
     }
-
-    this._updateContent();
-  }
-
-  _onMouseLeave() {
-    this._lastMouseData = { lng: '-', lat: '-', alt: '-' };
-    this._updateContent();
+    // 拾取不到（鼠标指向太空/地球未加载等）时不刷新，
+    // 保留最后一次成功拾取的坐标，避免信息栏闪现"-"
   }
 
   _onCameraChanged() {
@@ -9735,6 +9870,8 @@ class Zoom extends BaseControl {
   /**
    * @param {object} options
    * @param {number} [options.duration=0.5] 缩放动画时长（秒）
+   * @param {boolean} [options.doubleClickZoomIn=false] 左键双击放大一级（桌面端）
+   * @param {boolean} [options.doubleClickZoomOut=false] 右键双击缩小一级（桌面端）
    */
   constructor(options = {}) {
     super({
@@ -9743,6 +9880,19 @@ class Zoom extends BaseControl {
     });
 
     this._duration = options.duration ?? 0.5;
+    // 本控件发起的缩放飞行目标层级；飞行进行中（含动画尾段）点击按钮时，
+    // 以它而不是相机瞬时位置作为基准层级
+    this._pendingLevel = null;
+    // 双击缩放（默认关闭；开启后会替换 Cesium Viewer 默认的左键双击动作）
+    this._doubleClickZoomIn = options.doubleClickZoomIn ?? false;
+    this._doubleClickZoomOut = options.doubleClickZoomOut ?? false;
+    this._doubleClickEnabled = this._doubleClickZoomIn || this._doubleClickZoomOut;
+    this._doubleClickInstalled = false;
+    this._savedDoubleClickActions = null;
+    // 右键双击判定器：Cesium 的 RIGHT_DOUBLE_CLICK 在桌面端没有任何触发源
+    // （ScreenSpaceEventHandler 的 dblclick 监听只映射左键），
+    // 因此右键双击在 RIGHT_CLICK 流水上自维护（复用工具的 DoubleClickDetector）
+    this._rightDoubleClickDetector = new DoubleClickDetector();
   }
 
   _createContainer() {
@@ -9803,6 +9953,118 @@ class Zoom extends BaseControl {
       e.stopPropagation();
       this._zoomOut();
     });
+
+    // 双击缩放注册到 viewer.screenSpaceEventHandler（而不是 DOM 事件）：
+    // 绘制/量测工具激活时会保存-移除-恢复当前的左键双击动作，
+    // 注册在这里可以让工具自动接管，无需额外协调
+    if (this._doubleClickEnabled) {
+      this._installDoubleClickZoom();
+    }
+  }
+
+  /**
+   * 开启双击缩放（运行期可随时调用，只切换内部开关，不重建事件）
+   * 若初始化时未指定任何方向（两个选项均 false），默认只开左键双击放大
+   * @returns {Zoom}
+   */
+  enableDoubleClickZoom() {
+    this._doubleClickEnabled = true;
+    if (!this._doubleClickZoomIn && !this._doubleClickZoomOut) {
+      this._doubleClickZoomIn = true;
+    }
+    // 初始化时未安装过（选项均为 false）则补注册；
+    // 编辑器工具激活期间不抢占工具的左键双击，等工具结束恢复动作后即可用
+    if (!this._doubleClickInstalled && this._viewer && !this._viewer.xs3dEditorActive) {
+      this._installDoubleClickZoom();
+    }
+    return this;
+  }
+
+  /**
+   * 关闭双击缩放（运行期可随时调用；放大/缩小按钮不受影响）
+   * @returns {Zoom}
+   */
+  disableDoubleClickZoom() {
+    this._doubleClickEnabled = false;
+    return this;
+  }
+
+  /**
+   * 安装左键双击 / 右键双击缩放的输入动作，并保存被替换的原始动作供移除时恢复。
+   * 左键走 Cesium 的 LEFT_DOUBLE_CLICK（桌面端 DOM dblclick）；
+   * 右键 Cesium 无 RIGHT_DOUBLE_CLICK 触发源，改在 RIGHT_CLICK 上用
+   * DoubleClickDetector 自维护判定（连续两次右键间隔 < 300ms 且位移 < 10px）。
+   */
+  _installDoubleClickZoom() {
+    if (this._doubleClickInstalled || !this._viewer) return;
+    const handler = this._viewer.screenSpaceEventHandler;
+    if (!handler) return;
+
+    const EventType = Cesium$5.ScreenSpaceEventType;
+    const saved = {};
+    if (this._doubleClickZoomIn) {
+      saved.left = handler.getInputAction(EventType.LEFT_DOUBLE_CLICK);
+      handler.setInputAction(
+        (movement) => this._onDoubleClickZoom(1, movement),
+        EventType.LEFT_DOUBLE_CLICK
+      );
+    }
+    if (this._doubleClickZoomOut) {
+      saved.right = handler.getInputAction(EventType.RIGHT_CLICK);
+      handler.setInputAction(
+        (movement) => this._onRightClickForDoubleClick(movement),
+        EventType.RIGHT_CLICK
+      );
+    }
+    this._savedDoubleClickActions = saved;
+    this._doubleClickInstalled = true;
+  }
+
+  /**
+   * 右键单击喂入双击判定器，构成双击时缩小一级
+   * @param {object} movement Cesium 右键事件对象
+   */
+  _onRightClickForDoubleClick(movement) {
+    if (!this._doubleClickEnabled || !this._viewer) return;
+    // 编辑器工具激活期间：右键是工具的撤销/结束语义，清状态不喂入，
+    // 避免把两次撤销误判成双击缩放，或把脏状态带到工具结束后
+    if (this._viewer.xs3dEditorActive) {
+      this._rightDoubleClickDetector.reset();
+      return;
+    }
+    const pos = movement?.position;
+    if (!pos) return;
+    if (this._rightDoubleClickDetector.feed(performance.now(), { x: pos.x, y: pos.y })) {
+      this._rightDoubleClickDetector.reset();
+      this._onDoubleClickZoom(-1, movement);
+    }
+  }
+
+  /**
+   * 双击缩放处理：以双击拾取位置为中心步进一级
+   * @param {number} levelDelta +1 放大一级，-1 缩小一级
+   * @param {object} movement Cesium 双击事件对象
+   */
+  _onDoubleClickZoom(levelDelta, movement) {
+    if (!this._doubleClickEnabled || !this._viewer) return;
+    // 绘制/量测/编辑工具激活期间禁用：左键双击是工具的收尾语义，
+    // 右键单击是工具的撤销/结束语义，右键双击不能叠加缩放
+    if (this._viewer.xs3dEditorActive) return;
+
+    const camera = this._viewer.camera;
+    // 以双击位置拾取到的地表点为缩放中心；拾取不到退回相机正下方
+    let cartographic = camera.positionCartographic;
+    if (movement?.position && this._viewer.scene?.globe) {
+      const ray = camera.getPickRay(movement.position);
+      const cartesian = ray ? this._viewer.scene.globe.pick(ray, this._viewer.scene) : null;
+      if (cartesian) {
+        cartographic = Cesium$5.Cartographic.fromCartesian(cartesian);
+      }
+    }
+
+    const currentLevel = this._pendingLevel ?? this._getZoomLevel();
+    const targetLevel = Math.max(0, Math.min(24, currentLevel + levelDelta));
+    this._flyToLevel(targetLevel, cartographic);
   }
 
   _zoomIn() {
@@ -9818,12 +10080,21 @@ class Zoom extends BaseControl {
    * @param {number} levelDelta 层级变化量，+1 放大一级，-1 缩小一级
    */
   _zoomBy(levelDelta) {
-    const camera = this._viewer.camera;
-    const cartographic = camera.positionCartographic;
-    const currentLevel = this._getZoomLevel();
+    const currentLevel = this._pendingLevel ?? this._getZoomLevel();
     const targetLevel = Math.max(0, Math.min(24, currentLevel + levelDelta));
+    this._flyToLevel(targetLevel, this._viewer.camera.positionCartographic);
+  }
+
+  /**
+   * 飞到指定层级（以给定经纬度为中心），并记录 _pendingLevel
+   * @param {number} targetLevel 目标层级
+   * @param {Cesium.Cartographic} cartographic 目的地中心
+   */
+  _flyToLevel(targetLevel, cartographic) {
+    const camera = this._viewer.camera;
     const targetHeight = this._getHeightByZoomLevel(targetLevel);
 
+    this._pendingLevel = targetLevel;
     camera.flyTo({
       destination: Cesium$5.Cartesian3.fromRadians(
         cartographic.longitude,
@@ -9835,7 +10106,13 @@ class Zoom extends BaseControl {
         pitch: camera.pitch,
         roll: camera.roll
       },
-      duration: this._duration
+      duration: this._duration,
+      complete: () => {
+        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
+      },
+      cancel: () => {
+        if (this._pendingLevel === targetLevel) this._pendingLevel = null;
+      }
     });
   }
 
@@ -9854,7 +10131,36 @@ class Zoom extends BaseControl {
 
   _getHeightByZoomLevel(level) {
     const equatorCircumference = 6378137 * 2 * Math.PI;
-    return equatorCircumference / Math.pow(2, Math.max(0, level - 1));
+    // 取层级几何带中心（C / 2^(L-0.5)），而不是分界线高度 C / 2^(L-1)：
+    // 分界线上浮点误差会导致层级反推差一级（实测约 1/3 经纬度位置），
+    // 且动画尾段相机 changed 事件不再触发，信息栏会滞后一级显示。
+    return equatorCircumference / Math.pow(2, Math.max(0, level - 0.5));
+  }
+
+  /**
+   * 销毁：恢复安装双击缩放前的输入动作
+   * 编辑器工具激活期间不恢复（当前动作归工具所有，由工具的恢复链处理；
+   * 工具结束后会放回本控件的 handler，其中 _viewer 已置空，调用即 no-op）
+   */
+  _destroy() {
+    if (this._doubleClickInstalled && this._viewer?.screenSpaceEventHandler) {
+      const handler = this._viewer.screenSpaceEventHandler;
+      const EventType = Cesium$5.ScreenSpaceEventType;
+      const saved = this._savedDoubleClickActions || {};
+      [
+        ['left', EventType.LEFT_DOUBLE_CLICK],
+        ['right', EventType.RIGHT_CLICK]
+      ].forEach(([key, eventType]) => {
+        if (!(key in saved)) return;
+        if (typeof saved[key] === 'function') {
+          handler.setInputAction(saved[key], eventType);
+        } else {
+          handler.removeInputAction(eventType);
+        }
+      });
+    }
+    this._doubleClickInstalled = false;
+    this._savedDoubleClickActions = null;
   }
 }