cesium-xs-sdk 1.0.17 → 1.0.19

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

@@ -845,6 +845,24 @@ class SceneModule {
             }
         });
     }
+
+    /**
+     * 是否开启南北极轴约束
+     * 开启时（Cesium 默认行为）鼠标旋转/缩放无法让相机越过南北极点；
+     * 关闭时（viewer.camera.constrainedAxis = undefined）相机可穿越极点。
+     * @param {boolean} [enabled=true] true 开启约束，false 关闭约束
+     */
+    setPolarAxisConstraint(enabled = true) {
+        this.viewer.camera.constrainedAxis = enabled ? Cesium$h.Cartesian3.UNIT_Z : undefined;
+    }
+
+    /**
+     * 查询南北极轴约束是否开启
+     * @returns {boolean} true 已开启（相机不可穿越极点），false 已关闭
+     */
+    isPolarAxisConstraintEnabled() {
+        return Cesium$h.defined(this.viewer.camera.constrainedAxis);
+    }
 }
 
 const Cesium$g = getCesium();
@@ -9088,6 +9106,9 @@ class EditorModule {
     this.currentToolName = name;
     this.currentTool.activate();
     this._isActive = true;
+    // 供其他组件（如 Zoom 双击缩放）感知"编辑器工具激活中"，
+    // 工具激活期间双击/右键有工具自身语义，缩放等全局交互应让行
+    this.viewer.xs3dEditorActive = true;
 
     console.log(`工具 ${name} 已激活`);
     return this;
@@ -9104,6 +9125,9 @@ class EditorModule {
     this.currentTool = null;
     this.currentToolName = null;
     this._isActive = false;
+    if (this.viewer) {
+      this.viewer.xs3dEditorActive = false;
+    }
 
     return this;
   }
@@ -9734,10 +9758,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) {
@@ -9776,16 +9803,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() {
@@ -9867,6 +9888,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({
@@ -9875,6 +9898,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() {
@@ -9935,42 +9971,242 @@ class Zoom extends BaseControl {
       e.stopPropagation();
       this._zoomOut();
     });
+
+    // 双击缩放注册到 viewer.screenSpaceEventHandler（而不是 DOM 事件）：
+    // 绘制/量测工具激活时会保存-移除-恢复当前的左键双击动作，
+    // 注册在这里可以让工具自动接管，无需额外协调
+    if (this._doubleClickEnabled) {
+      this._installDoubleClickZoom();
+    }
   }
 
-  _zoomIn() {
-    this._zoomBy(1);
+  /**
+   * 开启双击缩放（运行期可随时调用，只切换内部开关，不重建事件）
+   * 若初始化时未指定任何方向（两个选项均 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;
   }
 
-  _zoomOut() {
-    this._zoomBy(-1);
+  /**
+   * 关闭双击缩放（运行期可随时调用；放大/缩小按钮不受影响）
+   * @returns {Zoom}
+   */
+  disableDoubleClickZoom() {
+    this._doubleClickEnabled = false;
+    return this;
   }
 
   /**
-   * 按地图层级步进缩放
-   * @param {number} levelDelta 层级变化量，+1 放大一级，-1 缩小一级
+   * 安装左键双击 / 右键双击缩放的输入动作，并保存被替换的原始动作供移除时恢复。
+   * 左键走 Cesium 的 LEFT_DOUBLE_CLICK（桌面端 DOM dblclick）；
+   * 右键 Cesium 无 RIGHT_DOUBLE_CLICK 触发源，改在 RIGHT_CLICK 上用
+   * DoubleClickDetector 自维护判定（连续两次右键间隔 < 300ms 且位移 < 10px）。
    */
-  _zoomBy(levelDelta) {
+  _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;
-    const cartographic = camera.positionCartographic;
-    const currentLevel = this._getZoomLevel();
+    // 以双击位置拾取到的地表点为缩放中心；拾取不到退回相机正下方
+    let cartographic = camera.positionCartographic;
+    // 锚点缩放需要"点击像素的视线方向"：保持这条视线不变，
+    // 锚点缩放后才仍投影在光标下方（相机中轴方向只在点击点恰为中心时成立）
+    let rayDirection = camera.direction;
+    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 (ray) {
+        rayDirection = ray.direction;
+      }
+      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._flyToLevelKeepScreenPoint(targetLevel, cartographic, rayDirection);
+  }
+
+  /**
+   * 飞到指定层级，且保持 cartographic 对应的地面点在原屏幕位置（锚点缩放）。
+   *
+   * 与 _flyToLevel（以点为中心）不同：这里把相机沿"点击像素的视线方向"反方向
+   * 退到目标高度——同一像素的视线方向只取决于相机姿态、与位置无关，因此相机
+   * 沿该方向移动后，锚点仍投影在双击位置（光标下方），而不是被搬到屏幕中心。
+   * 视线几乎水平（点击靠近地平线/天空）时退化为居中模式。
+   *
+   * @param {number} targetLevel 目标层级
+   * @param {Cesium.Cartographic} cartographic 锚点（双击拾取的地面点）
+   * @param {Cesium.Cartesian3} rayDirection 点击像素的视线方向（ECEF 单位向量）
+   */
+  _flyToLevelKeepScreenPoint(targetLevel, cartographic, rayDirection) {
+    const camera = this._viewer.camera;
     const targetHeight = this._getHeightByZoomLevel(targetLevel);
+    const pitch = camera.pitch;
+
+    let destination = null;
+    // 相机俯角至少 ~60° 才做锚点缩放；更平时后退距离发散，观感也差，退化为中心模式
+    const minPitch = Cesium$5.Math.toRadians(-60);
+    if (pitch <= minPitch && rayDirection) {
+      // 锚点处的本地"上"方向（ECEF）
+      const cosLat = Math.cos(cartographic.latitude);
+      const up = new Cesium$5.Cartesian3(
+        cosLat * Math.cos(cartographic.longitude),
+        cosLat * Math.sin(cartographic.longitude),
+        Math.sin(cartographic.latitude)
+      );
+      // 视线向下的分量
+      const rayUp = Cesium$5.Cartesian3.dot(rayDirection, up);
+      // 相机沿视线到锚点的距离：垂直落差 / 视线向下分量
+      const s = (targetHeight - cartographic.height) / (-rayUp);
+      if (rayUp < -0.05 && Number.isFinite(s) && s > 0) {
+        const anchor = Cesium$5.Cartesian3.fromRadians(
+          cartographic.longitude,
+          cartographic.latitude,
+          cartographic.height
+        );
+        destination = Cesium$5.Cartesian3.add(
+          anchor,
+          Cesium$5.Cartesian3.multiplyByScalar(rayDirection, -s, new Cesium$5.Cartesian3()),
+          new Cesium$5.Cartesian3()
+        );
+      }
+    }
 
-    camera.flyTo({
-      destination: Cesium$5.Cartesian3.fromRadians(
+    if (!destination) {
+      destination = Cesium$5.Cartesian3.fromRadians(
         cartographic.longitude,
         cartographic.latitude,
         targetHeight
-      ),
+      );
+    }
+    this._flyToDestination(targetLevel, destination);
+  }
+
+  /**
+   * 飞到指定层级的目的地（目的地构造交给调用方），并记录 _pendingLevel
+   * @param {number} targetLevel 目标层级
+   * @param {Cesium.Cartesian3} destination 相机最终位置
+   */
+  _flyToDestination(targetLevel, destination) {
+    const camera = this._viewer.camera;
+
+    this._pendingLevel = targetLevel;
+    camera.flyTo({
+      destination,
       orientation: {
         heading: camera.heading,
         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;
+      }
     });
   }
 
+  _zoomIn() {
+    this._zoomBy(1);
+  }
+
+  _zoomOut() {
+    this._zoomBy(-1);
+  }
+
+  /**
+   * 按地图层级步进缩放
+   * @param {number} levelDelta 层级变化量，+1 放大一级，-1 缩小一级
+   */
+  _zoomBy(levelDelta) {
+    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) {
+    this._flyToDestination(
+      targetLevel,
+      Cesium$5.Cartesian3.fromRadians(
+        cartographic.longitude,
+        cartographic.latitude,
+        this._getHeightByZoomLevel(targetLevel)
+      )
+    );
+  }
+
   _getZoomLevel() {
     const positionCartographic = this._viewer.camera.positionCartographic;
     const surfaceCartesian = Cesium$5.Cartesian3.fromRadians(
@@ -9986,7 +10222,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;
   }
 }