huweili-cesium 1.2.2 → 1.2.4

package/index.vue

@@ -1,474 +1,385 @@
-<template>
-  <div class="cesium-map-wrapper">
-    <div class="cesium-container" ref="cesiumContainer" />
-    <WsIndicator />
-  </div>
-</template>
-
-<script setup>
-import * as Cesium from 'cesium'
-import { ref, onMounted, onUnmounted, onActivated, onDeactivated, nextTick, toRaw } from 'vue'
-import { MapConfig, DroneConfig } from './js/config/index'
-import WsIndicator from './components/wsIndicator/wsIndicator.vue'
-import { objectUtils } from './js/utils/cesium/object'
-import { basicConfig } from './js/basis'
-import { useMapStore, MapLoadStatus } from './js/stores/mapStore'
-import { processMapConfigColors } from './js/tileProviders'
-import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery'
-import { createCustomToolbarButtons } from './js/customToolbarButtons'
-
-const { merge } = objectUtils()
-const { mouseController, setInitialCameraView } = basicConfig()
-
-const {
-  addToolbarButton,
-  addToolbarButtons,
-  removeToolbarButtons,
-  createDefaultToolbarButtons,
-} = createCustomToolbarButtons()
-
-/** 根据 props 组装最终要渲染的工具栏按钮配置 */
-function resolveToolbarButtonConfigs() {
-  if (props.toolbarButtons?.length) {
-    return props.toolbarButtons
-  }
-  const configs = []
-  if (props.showDefaultToolbar) {
-    configs.push(...createDefaultToolbarButtons({ mapId: props.mapId }))
-  }
-  if (props.extraToolbarButtons?.length) {
-    configs.push(...props.extraToolbarButtons)
-  }
-  return configs
-}
-
-// 获取store实例，保持响应性
-const mapStore = useMapStore()
-
-// onload事件将在地图渲染后触发
-const emit = defineEmits(["onload"])
-
-// ✅ 正确：纯 JS 写法，去掉 withDefaults
-const props = defineProps({
-  options: {
-    type: Object,
-    default: undefined
-  },
-  mapId: {
-    type: String,
-    default: 'default'
-  },
-  /** 是否挂载 npm 包内置的默认工具栏按钮 */
-  showDefaultToolbar: {
-    type: Boolean,
-    default: true
-  },
-  /**
-   * 完全自定义工具栏按钮配置（传入后不再使用内置默认按钮）
-   * 项格式同 createCustomToolbarButtons 的 addToolbarButton options
-   */
-  toolbarButtons: {
-    type: Array,
-    default: undefined
-  },
-  /** 在默认按钮之后追加的额外按钮（各项目可在此扩展） */
-  extraToolbarButtons: {
-    type: Array,
-    default: () => []
-  }
-})
-
-// 容器引用
-const cesiumContainer = ref(null)
-// 用于存放地球组件实例
-let map = null
-let customButtons = []
-let isMapActive = true
-
-const initCesium = async () => {
-  if (!cesiumContainer.value) return
-  mapStore.setMapLoadSta(MapLoadStatus.LOADING, props.mapId)
-
-  // 获取配置
-  let mapOptions
-  if (MapConfig) {
-    mapOptions = MapConfig
-  }
-
-  if (DroneConfig) {
-    const configOptions = DroneConfig
-    mapStore.setTrailTime(configOptions.trailTime, props.mapId)
-  }
-
-  if (props.options) {
-    // 存在叠加的属性时
-    let exOptions
-    if (props.options.then) {
-      exOptions = toRaw(await props.options)
-    } else {
-      exOptions = toRaw(props.options)
-    }
-
-    if (mapOptions) {
-      mapOptions = merge(mapOptions, exOptions) // 合并配置
-    } else {
-      mapOptions = exOptions
-    }
-  }
-
-  // 统一处理配置中的颜色，将十六进制转换为RGB
-  if (mapOptions) {
-    mapOptions = processMapConfigColors(mapOptions)
-  }
-
-  try {
-    // 初始化 Cesium 地球
-    // ==================== Cesium 配置统一管理 ====================
-    
-    // Viewer 核心配置
-    const viewerOptions = {
-      // 场景模式：固定为 3D 模式
-      sceneMode: Cesium.SceneMode.SCENE3D,
-      // 禁用默认渲染循环，由应用控制渲染时机
-      useDefaultRenderLoop: false,
-      // 底图配置：为 false 时禁用默认底图
-      baseLayer: mapOptions.control.imageryProvider === false ? false : undefined,
-      // 底图选择器
-      baseLayerPicker: mapOptions.control.baseLayerPicker,
-      // 地址搜索
-      geocoder: mapOptions.control.geocoder,
-      // 主页按钮
-      homeButton: mapOptions.control.homeButton,
-      // 场景模式选择器
-      sceneModePicker: mapOptions.control.sceneModePicker,
-      // 导航帮助按钮
-      navigationHelpButton: mapOptions.control.navigationHelpButton,
-      // 动画控件
-      animation: mapOptions.control.animation,
-      // 时间轴
-      timeline: mapOptions.control.timeline,
-      // 信息框
-      infoBox: mapOptions.control.infoBox,
-      // 全屏按钮
-      fullscreenButton: mapOptions.control.fullscreenButton,
-      // VR 按钮
-      vrButton: mapOptions.control.vrButton,
-      // 地形服务配置
-      terrainProvider: mapOptions.terrain.show ? await Cesium.CesiumTerrainProvider.fromUrl(mapOptions.terrain.url, {
-        requestWaterMask: mapOptions.terrain.coastlineData, // 请求水体效果所需要的海岸线数据
-        requestVertexNormals: mapOptions.terrain.lightingData, // 请求地形照明数据
-      }) : undefined,
-      // 地形阴影：只接收阴影，不投射阴影，节省性能
-      terrainShadows: Cesium.ShadowMode.RECEIVE_ONLY,
-      // 隐藏版权水印：用空容器替换
-      creditContainer: document.createElement('div'),
-    }
-
-    // WebGL 上下文配置
-    const contextOptions = {
-      webgl: {
-        alpha: false,                    // 禁用透明度通道
-        depth: true,                     // 启用深度缓冲区
-        stencil: false,                  // 禁用模板缓冲区
-        antialias: true,                 // 启用抗锯齿
-        premultipliedAlpha: true,        // 启用预乘透明度
-        preserveDrawingBuffer: false,    // 不保留绘制缓冲区
-        failIfMajorPerformanceCaveat: false // 允许在性能受限环境中运行
-      },
-      requestWebGl2: true,               // 启用 WebGL 2.0
-      powerPreference: 'high-performance' // 优先使用高性能 GPU
-    }
-
-    // 场景渲染配置（需要在 Viewer 创建后应用）
-    const sceneRenderOptions = {
-      // 显示帧速（FPS）
-      debugShowFramesPerSecond: mapOptions.scene.debugShowFramesPerSecond,
-      // 地球光照效果
-      enableLighting: mapOptions.scene.globe.enableLighting,
-      // 地形深度测试，确保在地形上的实体正确渲染
-      depthTestAgainstTerrain: mapOptions.scene.globe.depthTestAgainstTerrain,
-      // 雾效
-      fogEnabled: mapOptions.scene.fog.enabled,
-      // 大气层光环
-      skyAtmosphereShow: mapOptions.scene.skyAtmosphere.show,
-      // 动态大气光照
-      dynamicAtmosphereLighting: mapOptions.scene.globe.dynamicAtmosphereLighting,
-      // 动态大气光照从太阳开始
-      dynamicAtmosphereLightingFromSun: mapOptions.scene.globe.dynamicAtmosphereLightingFromSun
-    }
-
-    // ==================== 创建 Viewer 实例 ====================
-    map = new Cesium.Viewer(cesiumContainer.value, {
-      ...viewerOptions,
-      contextOptions
-    })
-
-    // 应用场景渲染配置
-    map.scene.debugShowFramesPerSecond = sceneRenderOptions.debugShowFramesPerSecond;
-    map.scene.globe.enableLighting = sceneRenderOptions.enableLighting;
-    map.scene.globe.depthTestAgainstTerrain = sceneRenderOptions.depthTestAgainstTerrain;
-    map.scene.fog.enabled = sceneRenderOptions.fogEnabled;
-    map.scene.skyAtmosphere.show = sceneRenderOptions.skyAtmosphereShow;
-    map.scene.globe.dynamicAtmosphereLighting = sceneRenderOptions.dynamicAtmosphereLighting;
-    map.scene.globe.dynamicAtmosphereLightingFromSun = sceneRenderOptions.dynamicAtmosphereLightingFromSun;
-
-    // 设置地图初始视角（中心点、经纬度、高度、航向等）
-    setInitialCameraView(map, mapOptions.scene.center)
-
-    // 在线底图 + 可选离线共存（城市范围内优先离线瓦片）
-    const activeBasemap = resolveOnlineBasemap(mapOptions)
-    if (activeBasemap) {
-      applyImageryLayers(map, mapOptions, activeBasemap)
-      console.log(`加载在线底图：${activeBasemap.name}，URL：${activeBasemap.url}`)
-      window._currentBasemapId = activeBasemap.id
-    } else {
-      console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
-    }
-
-    // 禁用默认的双击行为 (双击缩放)
-    if (map.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
-      // 移除默认的双击行为
-      map.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK);
-    }
-
-    // 单击 entity 事件
-    if (mapOptions.control.disableEntityClick) {
-      map.selectedEntityChanged.addEventListener(() => {
-        map.selectedEntity = undefined;   // 永远不让实体被选中
-      });
-    }
-
-    // 初始化鼠标控制器
-    mouseController(map, props.mapId); 
-
-    // 保存地图中心点、旋转角度、俯仰角度
-    mapStore.setMapInfo('center', {
-      lng: mapOptions.scene.center.lng,
-      lat: mapOptions.scene.center.lat,
-      heading: mapOptions.scene.center.heading,
-      pitch: mapOptions.scene.center.pitch,
-      roll: mapOptions.scene.center.roll,
-      duration: mapOptions.scene.center.duration,
-      alt: mapOptions.scene.center.alt,
-    }, props.mapId)
-    mapStore.setMap(map, props.mapId)
-
-    // 设置场景模式（2D/3D）
-    const sceneMode = mapOptions.scene.sceneMode || '3D';
-    mapStore.setSceneMode(sceneMode, props.mapId);
-    
-    // 初始化半球区域
-    const center = mapOptions.scene.center || {}
- 
-    // 在主页按钮附近添加工具栏按钮（默认 + 项目扩展，或完全自定义）
-    const toolbarConfigs = resolveToolbarButtonConfigs()
-    if (toolbarConfigs.length) {
-      customButtons = addToolbarButtons(map, toolbarConfigs)
-    }
-
-    // 设置地图加载状态为已加载
-    mapStore.setMapLoadSta(MapLoadStatus.LOADED, props.mapId)
-
-    console.log(`Cesium 地图加载成功，mapId: ${props.mapId}`)
-    emit("onload", {
-      map,
-      center,
-      mapId: props.mapId,
-      toolbar: {
-        addToolbarButton: (opt) => addToolbarButton(map, opt),
-        addToolbarButtons: (opts) => addToolbarButtons(map, opts),
-        removeToolbarButtons,
-      },
-    })
-
-    map.resize()
-    map.render()
-
-    // 添加持续渲染循环，避免浏览器进入节能模式
-    startContinuousRendering(map)
-  } catch (error) {
-    mapStore.setMapLoadSta(MapLoadStatus.FAILED, props.mapId)
-    console.error('Cesium 地图加载失败:', error)
-  }
-}
-
-// 持续渲染循环（避免浏览器节能模式）
-let animationId = null
-let lastActiveTime = Date.now()
-const IDLE_TIMEOUT = 30000 // 30秒无活动后暂停
-
-function startContinuousRendering(viewer) {
-  if (animationId) return
-  function animate() {
-    const now = Date.now()
-    if (
-      isMapActive &&
-      !document.hidden &&
-      map &&
-      !map.isDestroyed?.() &&
-      now - lastActiveTime < IDLE_TIMEOUT
-    ) {
-      viewer.render()
-    }
-    animationId = requestAnimationFrame(animate)
-  }
-  animate()
-}
-
-/**
- * 停止持续渲染循环
- * 
- * 功能说明：
- * - 取消 requestAnimationFrame 创建的动画帧请求
- * - 清空 animationId，防止重复取消
- * - 用于页面失活、组件卸载或需要暂停渲染时释放资源
- * 
- * 使用场景：
- * - 页面被 keep-alive 缓存时（onDeactivated）
- * - 组件卸载时（onUnmounted）
- * - 手动暂停地图渲染以节省性能时
- */
-function stopRenderLoop() {
-  if (animationId) {
-    cancelAnimationFrame(animationId)
-    animationId = null
-  }
-}
-
-// 监听用户活动，重置活跃时间
-function setupActivityListeners() {
-  const activities = ['mousemove', 'keydown', 'touchmove', 'wheel', 'click']
-  activities.forEach(event => {
-    document.addEventListener(event, () => {
-      lastActiveTime = Date.now()
-    })
-  })
-}
-
-/**
- * 从缓存中恢复地图渲染（用于 keep-alive 场景）
- * 
- * 功能说明：
- * - 当页面被 keep-alive 缓存后再次激活时，恢复 Cesium 地图的渲染状态
- * - 重新设置当前地图 ID、激活状态和最后活跃时间
- * - 在下一个 tick 中调整地图大小、触发渲染并重启持续渲染循环
- * 
- * 使用场景：
- * - Vue 路由中使用 keep-alive 缓存包含地图的组件，切换回该页面时调用
- * - 在 onActivated 生命周期钩子中触发
- */
-function resumeMapAfterCache() {
-  if (!map || map.isDestroyed?.()) return
-  mapStore.setCurrentMapId(props.mapId)
-  isMapActive = true
-  lastActiveTime = Date.now()
-  nextTick(() => {
-    if (!map || map.isDestroyed?.()) return
-    map.resize()
-    map.render()
-    if (!animationId) startContinuousRendering(map)
-  })
-}
-
-/**
- * 组件挂载钩子（首次加载时触发）
- * 
- * 触发时机：
- * - 组件首次挂载到 DOM 时
- * - 无论是否使用 keep-alive，首次加载都会触发
- * 
- * 功能说明：
- * - 设置当前地图 ID
- * - 监听用户活动事件
- * - 初始化 Cesium 地图
- */
-onMounted(() => {
-  mapStore.setCurrentMapId(props.mapId)
-  setupActivityListeners()
-  initCesium()
-})
-
-/**
- * keep-alive 组件激活钩子（从缓存中恢复时触发）
- * 
- * 触发时机：
- * - 当前组件被 keep-alive 包裹，用户导航回到该页面时
- * - 组件从缓存状态恢复到活动状态
- * 
- * 功能说明：
- * - 重新设置当前地图 ID
- * - 如果地图已销毁，重新初始化地图
- * - 如果地图还在缓存中，恢复地图渲染
- */
-onActivated(() => {
-  mapStore.setCurrentMapId(props.mapId)
-  if (!map || map.isDestroyed?.()) {
-    isMapActive = true
-    initCesium()
-    return
-  }
-  resumeMapAfterCache()
-})
-
-/**
- * keep-alive 组件失活钩子（页面被缓存时触发）
- * 
- * 触发时机：
- * - 当前组件被 keep-alive 包裹，用户导航离开该页面时
- * - 组件进入缓存状态，但不会被销毁
- * 
- * 功能说明：
- * - 标记地图为非活跃状态
- * - 停止持续渲染循环，节省 CPU 资源
- * 
- * 与 onUnmounted 的区别：
- * - onDeactivated：组件被缓存，可通过 onActivated 恢复
- * - onUnmounted：组件被销毁，需要完全清理资源
- */
-onDeactivated(() => {
-  isMapActive = false
-  stopRenderLoop()
-})
-
-/**
- * 组件卸载钩子（完全销毁时触发）
- * 
- * 触发时机：
- * - 组件被完全移除时
- * - 路由切换且未使用 keep-alive 缓存时
- * 
- * 功能说明：
- * - 停止渲染循环
- * - 移除自定义工具栏按钮
- * - 销毁 Cesium Viewer 实例释放内存
- * - 从 store 中移除地图实例
- */
-onUnmounted(() => {
-  isMapActive = false
-  stopRenderLoop()
-  removeToolbarButtons(customButtons)
-  customButtons = []
-  if (map) {
-    map.destroy()
-    map = null
-  }
-  mapStore.removeMapInstance(props.mapId)
-})
-
-</script>
-
-<style scoped lang="less">
-.cesium-map-wrapper {
-  width: 100%;
-  height: 100%;
-  position: relative;
-}
-
-.cesium-container {
-  width: 100%;
-  height: 100%;
-  position: relative;
-}
-
-
-</style>
+<template>
+  <div class="cesium-map-wrapper" @pointerdown="handleMapPointerDown">
+    <div class="cesium-container" ref="cesiumContainer" />
+    <WsIndicator />
+  </div>
+</template>
+
+<script setup>
+import * as Cesium from 'cesium'
+import { ref, watch, onMounted, onUnmounted, onActivated, onDeactivated, nextTick, toRaw } from 'vue'
+import { MapConfig, DroneConfig } from './config'
+import WsIndicator from './components/wsIndicator/wsIndicator.vue'
+import { objectUtils } from './utils/cesium/object'
+import { basicConfig, teardownOrthographicWheelZoom } from './basis'
+import { useMapStore, MapLoadStatus } from './stores/mapStore'
+import { useEventBus } from './utils/useEventBus'
+import { processMapConfigColors } from './tileProviders'
+import { applyImageryLayers, resolveOnlineBasemap } from './utils/mapImagery'
+import { createCustomToolbarButtons } from './customToolbarButtons'
+import { ensureMapFocus } from './utils/cameraInteraction'
+
+const { merge } = objectUtils()
+const { mouseController, setInitialCameraView, syncCameraInteractionMode } = basicConfig()
+
+const {
+  addToolbarButton,
+  addToolbarButtons,
+  removeToolbarButtons,
+  createDefaultToolbarButtons,
+} = createCustomToolbarButtons()
+
+const mapStore = useMapStore()
+const { on: onEvent, off: offEvent } = useEventBus()
+
+const emit = defineEmits(['onload'])
+
+const props = defineProps({
+  options: {
+    type: Object,
+    default: undefined,
+  },
+  mapId: {
+    type: String,
+    default: 'default',
+  },
+  showDefaultToolbar: {
+    type: Boolean,
+    default: true,
+  },
+  toolbarButtons: {
+    type: Array,
+    default: undefined,
+  },
+  extraToolbarButtons: {
+    type: Array,
+    default: () => [],
+  },
+})
+
+function resolveToolbarButtonConfigs() {
+  if (props.toolbarButtons?.length) {
+    return props.toolbarButtons
+  }
+  const configs = []
+  if (props.showDefaultToolbar) {
+    configs.push(...createDefaultToolbarButtons({ mapId: props.mapId }))
+  }
+  if (props.extraToolbarButtons?.length) {
+    configs.push(...props.extraToolbarButtons)
+  }
+  return configs
+}
+
+const handleSceneModeChange = ({ mapId, sceneMode }) => {
+  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
+  syncCameraInteractionMode(map, mapId, sceneMode)
+}
+
+const handleMapPointerDown = () => {
+  if (map && !map.isDestroyed?.()) {
+    ensureMapFocus(map)
+  }
+}
+
+const cesiumContainer = ref(null)
+let map = null
+let customButtons = []
+let isMapActive = true
+
+function mountToolbarButtons(viewer) {
+  if (!viewer || viewer.isDestroyed?.()) return
+  removeToolbarButtons(customButtons)
+  customButtons = []
+  const toolbarConfigs = resolveToolbarButtonConfigs()
+  if (toolbarConfigs.length) {
+    customButtons = addToolbarButtons(viewer, toolbarConfigs)
+  }
+}
+
+const initCesium = async () => {
+  if (!cesiumContainer.value) return
+  mapStore.setMapLoadSta(MapLoadStatus.LOADING, props.mapId)
+
+  let mapOptions
+  if (MapConfig) {
+    mapOptions = MapConfig
+  }
+
+  if (DroneConfig) {
+    mapStore.setTrailTime(DroneConfig.trailTime, props.mapId)
+  }
+
+  if (props.options) {
+    let exOptions
+    if (props.options.then) {
+      exOptions = toRaw(await props.options)
+    } else {
+      exOptions = toRaw(props.options)
+    }
+
+    if (mapOptions) {
+      mapOptions = merge(mapOptions, exOptions)
+    } else {
+      mapOptions = exOptions
+    }
+  }
+
+  if (mapOptions) {
+    mapOptions = processMapConfigColors(mapOptions)
+  }
+
+  try {
+    const viewerOptions = {
+      sceneMode: Cesium.SceneMode.SCENE3D,
+      useDefaultRenderLoop: false,
+      baseLayer: mapOptions.control.imageryProvider === false ? false : undefined,
+      baseLayerPicker: mapOptions.control.baseLayerPicker,
+      geocoder: mapOptions.control.geocoder,
+      homeButton: mapOptions.control.homeButton,
+      sceneModePicker: mapOptions.control.sceneModePicker,
+      navigationHelpButton: mapOptions.control.navigationHelpButton,
+      animation: mapOptions.control.animation,
+      timeline: mapOptions.control.timeline,
+      infoBox: mapOptions.control.infoBox,
+      fullscreenButton: mapOptions.control.fullscreenButton,
+      vrButton: mapOptions.control.vrButton,
+      terrainProvider: mapOptions.terrain.show
+        ? await Cesium.CesiumTerrainProvider.fromUrl(mapOptions.terrain.url, {
+            requestWaterMask: mapOptions.terrain.coastlineData,
+            requestVertexNormals: mapOptions.terrain.lightingData,
+          })
+        : undefined,
+      terrainShadows: Cesium.ShadowMode.RECEIVE_ONLY,
+      creditContainer: document.createElement('div'),
+    }
+
+    const contextOptions = {
+      webgl: {
+        alpha: false,
+        depth: true,
+        stencil: false,
+        antialias: true,
+        premultipliedAlpha: true,
+        preserveDrawingBuffer: false,
+        failIfMajorPerformanceCaveat: false,
+      },
+      requestWebGl2: true,
+      powerPreference: 'high-performance',
+    }
+
+    const sceneRenderOptions = {
+      debugShowFramesPerSecond: mapOptions.scene.debugShowFramesPerSecond,
+      enableLighting: mapOptions.scene.globe.enableLighting,
+      depthTestAgainstTerrain: mapOptions.scene.globe.depthTestAgainstTerrain,
+      fogEnabled: mapOptions.scene.fog.enabled,
+      skyAtmosphereShow: mapOptions.scene.skyAtmosphere.show,
+      dynamicAtmosphereLighting: mapOptions.scene.globe.dynamicAtmosphereLighting,
+      dynamicAtmosphereLightingFromSun: mapOptions.scene.globe.dynamicAtmosphereLightingFromSun,
+    }
+
+    map = new Cesium.Viewer(cesiumContainer.value, {
+      ...viewerOptions,
+      contextOptions,
+    })
+
+    map.scene.debugShowFramesPerSecond = sceneRenderOptions.debugShowFramesPerSecond
+    map.scene.globe.enableLighting = sceneRenderOptions.enableLighting
+    map.scene.globe.depthTestAgainstTerrain = sceneRenderOptions.depthTestAgainstTerrain
+    map.scene.fog.enabled = sceneRenderOptions.fogEnabled
+    map.scene.skyAtmosphere.show = sceneRenderOptions.skyAtmosphereShow
+    map.scene.globe.dynamicAtmosphereLighting = sceneRenderOptions.dynamicAtmosphereLighting
+    map.scene.globe.dynamicAtmosphereLightingFromSun =
+      sceneRenderOptions.dynamicAtmosphereLightingFromSun
+
+    const sceneMode = mapOptions.scene.sceneMode || '3D'
+
+    const activeBasemap = resolveOnlineBasemap(mapOptions)
+    if (activeBasemap) {
+      applyImageryLayers(map, mapOptions, activeBasemap)
+      console.log(`加载在线底图：${activeBasemap.name}，URL：${activeBasemap.url}`)
+      window._currentBasemapId = activeBasemap.id
+    } else {
+      console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
+    }
+
+    if (map.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
+      map.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
+    }
+
+    if (mapOptions.control.disableEntityClick) {
+      map.selectedEntityChanged.addEventListener(() => {
+        map.selectedEntity = undefined
+      })
+    }
+
+    mouseController(map, props.mapId)
+
+    mapStore.setMapInfo(
+      'center',
+      {
+        lng: mapOptions.scene.center.lng,
+        lat: mapOptions.scene.center.lat,
+        heading: mapOptions.scene.center.heading,
+        pitch: mapOptions.scene.center.pitch,
+        roll: mapOptions.scene.center.roll,
+        duration: mapOptions.scene.center.duration,
+        alt: mapOptions.scene.center.alt,
+      },
+      props.mapId,
+    )
+    mapStore.setMap(map, props.mapId)
+    mapStore.setSceneMode(sceneMode, props.mapId)
+
+    const center = mapOptions.scene.center || {}
+
+    mountToolbarButtons(map)
+    mapStore.setMapLoadSta(MapLoadStatus.LOADED, props.mapId)
+
+    console.log(`Cesium 地图加载成功，mapId: ${props.mapId}`)
+    emit('onload', {
+      map,
+      center,
+      mapId: props.mapId,
+      toolbar: {
+        addToolbarButton: (opt) => addToolbarButton(map, opt),
+        addToolbarButtons: (opts) => addToolbarButtons(map, opts),
+        removeToolbarButtons,
+      },
+      syncCameraInteractionMode: (mode) => syncCameraInteractionMode(map, props.mapId, mode),
+    })
+
+    map.resize()
+    setInitialCameraView(map, mapOptions.scene.center, sceneMode, props.mapId)
+    map.render()
+
+    if (sceneMode === '2D') {
+      nextTick(() => {
+        if (!map || map.isDestroyed?.()) return
+        syncCameraInteractionMode(map, props.mapId, '2D')
+      })
+    }
+
+    startContinuousRendering(map)
+  } catch (error) {
+    mapStore.setMapLoadSta(MapLoadStatus.FAILED, props.mapId)
+    console.error('Cesium 地图加载失败:', error)
+  }
+}
+
+let animationId = null
+let lastActiveTime = Date.now()
+const IDLE_TIMEOUT = 30000
+
+function startContinuousRendering(viewer) {
+  if (animationId) return
+  function animate() {
+    const now = Date.now()
+    if (
+      isMapActive &&
+      !document.hidden &&
+      map &&
+      !map.isDestroyed?.() &&
+      now - lastActiveTime < IDLE_TIMEOUT
+    ) {
+      viewer.render()
+    }
+    animationId = requestAnimationFrame(animate)
+  }
+  animate()
+}
+
+function stopRenderLoop() {
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+    animationId = null
+  }
+}
+
+function setupActivityListeners() {
+  const activities = ['mousemove', 'keydown', 'touchmove', 'wheel', 'click']
+  activities.forEach((event) => {
+    document.addEventListener(event, () => {
+      lastActiveTime = Date.now()
+    })
+  })
+}
+
+function resumeMapAfterCache() {
+  if (!map || map.isDestroyed?.()) return
+  mapStore.setCurrentMapId(props.mapId)
+  isMapActive = true
+  lastActiveTime = Date.now()
+  nextTick(() => {
+    if (!map || map.isDestroyed?.()) return
+    map.resize()
+    const mode = mapStore.getSceneMode(props.mapId)
+    syncCameraInteractionMode(map, props.mapId, mode === '2D' ? '2D' : '3D')
+    map.render()
+    if (!animationId) startContinuousRendering(map)
+  })
+}
+
+watch(
+  () => props.toolbarButtons,
+  () => {
+    if (map && !map.isDestroyed?.()) {
+      mountToolbarButtons(map)
+    }
+  },
+  { deep: true },
+)
+
+onMounted(() => {
+  mapStore.setCurrentMapId(props.mapId)
+  setupActivityListeners()
+  onEvent('map-scene-mode-changed', handleSceneModeChange)
+  initCesium()
+})
+
+onActivated(() => {
+  mapStore.setCurrentMapId(props.mapId)
+  if (!map || map.isDestroyed?.()) {
+    isMapActive = true
+    initCesium()
+    return
+  }
+  resumeMapAfterCache()
+})
+
+onDeactivated(() => {
+  isMapActive = false
+  stopRenderLoop()
+})
+
+onUnmounted(() => {
+  isMapActive = false
+  stopRenderLoop()
+  offEvent('map-scene-mode-changed', handleSceneModeChange)
+  if (map) {
+    teardownOrthographicWheelZoom(map)
+  }
+  removeToolbarButtons(customButtons)
+  customButtons = []
+  if (map) {
+    map.destroy()
+    map = null
+  }
+  mapStore.removeMapInstance(props.mapId)
+})
+</script>
+
+<style scoped lang="less">
+.cesium-map-wrapper {
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.cesium-container {
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+</style>
+

package/js/basis.js

@@ -10,6 +10,11 @@
  */
 import * as Cesium from 'cesium'
 import { useMapStore } from './stores/mapStore.js'
+import {
+  syncCameraInteractionMode,
+  teardownOrthographicWheelZoom,
+  restorePerspectiveControllerState,
+} from './utils/cameraInteraction.js'
 
 export function basicConfig() {
 
@@ -71,29 +76,42 @@ export function basicConfig() {
    *   roll: 0          // 不翻滚
    * })
    */
-  const setInitialCameraView = (viewer, center = {}) => {
-    // 安全检查：确保 viewer 和 camera 对象存在
+  const orthoViewHelpers = () => ({
+    applyOrthographicFrustum,
+    getEffective2DOrthoWidth,
+  })
+
+  /**
+   * 设置 Cesium 地图初始相机视角（支持 2D 正交 / 3D 透视）
+   * @param {Cesium.Viewer} viewer
+   * @param {Object} center
+   * @param {'2D'|'3D'} sceneMode
+   * @param {string=} mapId
+   */
+  const setInitialCameraView = (viewer, center = {}, sceneMode = '3D', mapId) => {
     if (!viewer?.camera) return
 
-    // 从 center 对象中提取参数，使用默认值确保容错性
-    const lng = Number(center.lng) || 0        // 经度，默认 0°
-    const lat = Number(center.lat) || 0        // 纬度，默认 0°
-    const alt = Number(center.alt) || 10000     // 高度，默认 10000 米
-    const heading = Cesium.Math.toRadians(Number(center.heading) || 0)  // 航向角 → 弧度
-    const pitch = Cesium.Math.toRadians(-90)    // 俯仰角，固定 -90°（垂直俯视）
-    const roll = Cesium.Math.toRadians(Number(center.roll) || 0)        // 翻滚角 → 弧度
+    const lng = Number(center.lng) || 0
+    const lat = Number(center.lat) || 0
+    const alt = Number(center.alt) || 10000
+    const heading = Cesium.Math.toRadians(Number(center.heading) || 0)
+    const pitch = Cesium.Math.toRadians(Number(center.pitch) ?? -90)
+    const roll = Cesium.Math.toRadians(Number(center.roll) || 0)
+
+    if (sceneMode === '2D') {
+      const orthoWidth = computeOrthoWidthFromHeight(viewer, alt)
+      if (mapId && orthoWidth > 0) {
+        mapStore.setViewOrthoWidth(orthoWidth, mapId)
+      }
+      set2DView(viewer, lng, lat, alt, orthoWidth, mapId)
+      return
+    }
 
-    // 设置相机视角
     viewer.camera.setView({
-      // 相机目标位置：使用经纬度坐标和高度创建 Cartesian3 坐标
       destination: Cesium.Cartesian3.fromDegrees(lng, lat, alt),
-      // 相机朝向：通过 heading、pitch、roll 三个角度定义
-      orientation: {
-        heading,  // 航向角：绕垂直轴旋转（0=北，90=东，180=南，270=西）
-        pitch,    // 俯仰角：绕水平轴旋转（-90=正下方，0=水平，90=正上方）
-        roll,     // 翻滚角：绕相机朝向轴旋转
-      },
+      orientation: { heading, pitch, roll },
     })
+    syncCameraInteractionMode(viewer, mapId, '3D', orthoViewHelpers())
   }
 
   /**
@@ -102,7 +120,7 @@ export function basicConfig() {
    * 处理地图上的鼠标事件，包括点击、拖动、缩放等、
    * @param map - 地图实例
    */
-  const mouseController = (map) => {
+  const mouseController = (map, _mapId) => {
     // 添加右键点击事件监听
     map.screenSpaceEventHandler.setInputAction((click) => {
       // 获取点击位置的笛卡尔坐标
@@ -181,7 +199,7 @@ export function basicConfig() {
       if (mapId && orthoWidth > 0) {
         mapStore.setViewOrthoWidth(orthoWidth, mapId)
       }
-      set2DView(map, lng, lat, finalAltitude, orthoWidth)
+      set2DView(map, lng, lat, finalAltitude, orthoWidth, mapId)
     } else {
       if (mapId) {
         const pitchDeg = Math.abs(centerInfo.pitch ?? -35)
@@ -189,7 +207,7 @@ export function basicConfig() {
         const range = Math.max(finalAltitude / Math.max(Math.sin(pitchRad), 0.1), 100)
         mapStore.setViewOrthoWidth(rangeToOrthoWidth(map, range), mapId)
       }
-      set3DView(map, lng, lat, centerInfo, finalAltitude, finalTargetAlt)
+      set3DView(map, lng, lat, centerInfo, finalAltitude, finalTargetAlt, undefined, mapId)
     }
   }
 
@@ -240,6 +258,8 @@ export function basicConfig() {
   const restorePerspectiveFrustum = (map) => {
     if (!map) return
 
+    if (map.camera.frustum instanceof Cesium.PerspectiveFrustum) return
+
     const currentFrustum = map.camera.frustum
     const perspectiveFrustum = new Cesium.PerspectiveFrustum()
     perspectiveFrustum.fov = getPerspectiveVerticalFovRadians()
@@ -291,7 +311,6 @@ export function basicConfig() {
     if (!map) return
 
     const canvas = map.canvas
-    const frustum = new Cesium.OrthographicFrustum()
     const width = canvas.clientWidth
     const height = canvas.clientHeight
 
@@ -303,10 +322,22 @@ export function basicConfig() {
     } else if (map.scene.camera.frustum instanceof Cesium.PerspectiveFrustum) {
       const cameraHeight = map.scene.camera.positionCartographic?.height ?? 10000
       widthValue = computeOrthoWidthFromHeight(map, cameraHeight)
+    } else if (map.scene.camera.frustum instanceof Cesium.OrthographicFrustum) {
+      widthValue = map.scene.camera.frustum.width || getEffective2DOrthoWidth(map) || 20000
     } else {
-      widthValue = map.scene.camera.frustum.width || 20000
+      widthValue = 20000
     }
 
+    const currentFrustum = map.scene.camera.frustum
+    if (currentFrustum instanceof Cesium.OrthographicFrustum) {
+      currentFrustum.width = widthValue
+      currentFrustum.aspectRatio = width / height
+      currentFrustum.near = 0.1
+      currentFrustum.far = 10000000.0
+      return
+    }
+
+    const frustum = new Cesium.OrthographicFrustum()
     frustum.width = widthValue
     frustum.aspectRatio = width / height
     frustum.near = 0.1
@@ -322,7 +353,7 @@ export function basicConfig() {
    * @param {number=} height 相机高度
    * @param {number=} orthoWidth 正交可视宽度（米），切换 2D/3D 时传入以保持缩放不变
    */
-  const set2DView = (map, lng, lat, height, orthoWidth) => {
+  const set2DView = (map, lng, lat, height, orthoWidth, mapId) => {
     if (!map) return
 
     const resolvedWidth = Number.isFinite(orthoWidth) && orthoWidth > 0
@@ -337,15 +368,17 @@ export function basicConfig() {
       cameraController.enableTilt = false
       cameraController.enableLook = false
     }
+
     map.camera.setView({
       destination: Cesium.Cartesian3.fromDegrees(lng, lat, resolvedHeight),
       orientation: {
         heading: Cesium.Math.toRadians(0),
         pitch: Cesium.Math.toRadians(-90),
-        roll: Cesium.Math.toRadians(0)
-      }
+        roll: Cesium.Math.toRadians(0),
+      },
     })
     applyOrthographicFrustum(map, undefined, resolvedWidth)
+    syncCameraInteractionMode(map, mapId, '2D', orthoViewHelpers())
   }
 
   /**
@@ -366,7 +399,7 @@ export function basicConfig() {
    * @param {number=} targetAlt 目标点的高度（比如无人机的飞行高度，默认0）
    * @param {number=} slantRange 可选，相机到目标点的直线距离（米）；传入时优先于 altitude 换算
    */
-  const set3DView = (map, lng, lat, centerInfo = {}, altitude = 10000, targetAlt = 0, slantRange) => {
+  const set3DView = (map, lng, lat, centerInfo = {}, altitude = 10000, targetAlt = 0, slantRange, mapId) => {
     // 1. 检查地图实例是否存在，不存在就直接返回
     if (!map) return
 
@@ -418,8 +451,14 @@ export function basicConfig() {
       )
     )
 
-    // 9. 重置相机变换（确保lookAt生效后恢复正常状态）
     map.camera.lookAtTransform(Cesium.Matrix4.IDENTITY)
+
+    if (mapId) {
+      syncCameraInteractionMode(map, mapId, '3D', orthoViewHelpers())
+    } else {
+      teardownOrthographicWheelZoom(map)
+      restorePerspectiveControllerState(map)
+    }
   }
 
   /**
@@ -508,14 +547,14 @@ export function basicConfig() {
     if (Number.isFinite(slantRange) && slantRange > 0) {
       const orthoWidth = Math.max(rangeToOrthoWidth(map, slantRange), 100)
       mapStore.setViewOrthoWidth(orthoWidth, mapId)
-      set3DView(map, lng, lat, centerInfo, undefined, 0, slantRange)
+      set3DView(map, lng, lat, centerInfo, undefined, 0, slantRange, mapId)
       return
     }
 
     const orthoWidth = getEffective2DOrthoWidth(map) || resolveViewOrthoWidth(map, mapId, centerInfo)
     mapStore.setViewOrthoWidth(orthoWidth, mapId)
     const range = Math.max(orthoWidthToRange(map, orthoWidth), 100)
-    set3DView(map, lng, lat, centerInfo, undefined, 0, range)
+    set3DView(map, lng, lat, centerInfo, undefined, 0, range, mapId)
   }
 
   /**
@@ -541,7 +580,7 @@ export function basicConfig() {
       }
     }
 
-    set2DView(map, lng, lat, undefined, orthoWidth)
+    set2DView(map, lng, lat, undefined, orthoWidth, mapId)
   }
 
   /**
@@ -670,6 +709,10 @@ export function basicConfig() {
     set3DView,
     applyOrthographicFrustum,
     restorePerspectiveFrustum,
-    setInitialCameraView
+    setInitialCameraView,
+    syncCameraInteractionMode: (map, mapId, sceneMode) =>
+      syncCameraInteractionMode(map, mapId, sceneMode, orthoViewHelpers()),
   }
-}
+}
+
+export { teardownOrthographicWheelZoom, ensureMapFocus } from './utils/cameraInteraction.js'

package/js/customToolbarButtons.js

@@ -129,6 +129,9 @@ export function createCustomToolbarButtons() {
           const result = toggleViewToRtk(mapId)
           if (result.success && btn) btn.innerText = result.currentMode
           mapStore.setSceneMode(result.currentMode, mapId)
+          if (result.success) {
+            emit('map-scene-mode-changed', { mapId, sceneMode: result.currentMode })
+          }
         }
       },
       { 

package/js/index.js

@@ -30,6 +30,12 @@ export { default as eventBus } from './utils/eventBus.js'
 export { useEventBus } from './utils/useEventBus.js'
 export { getMapCenterPosition } from './utils/getMapCenterPosition.js'
 export { selectDrone, deselectDrone } from './utils/droneSelection.js'
+export { applyOrthographicZoomFactor } from './utils/orthographicCameraZoom.js'
+export {
+  ensureMapFocus,
+  teardownOrthographicWheelZoom,
+  syncCameraInteractionMode,
+} from './utils/cameraInteraction.js'
 
 export {
   BaseConfig,

package/js/utils/cameraInteraction.js

@@ -0,0 +1,101 @@
+/**
+ * 2D 正交 / 3D 透视下的相机交互（滚轮缩放、控制器开关）
+ */
+import * as Cesium from 'cesium'
+import { useMapStore } from '../stores/mapStore.js'
+import { applyOrthographicZoomFactor } from './orthographicCameraZoom.js'
+
+const ORTHO_WHEEL_ZOOM_RATE = 1.1
+const orthoWheelCleanups = new WeakMap()
+
+export function ensureMapFocus(map) {
+  const canvas = map?.canvas
+  if (!canvas) return
+  if (!canvas.hasAttribute('tabindex')) {
+    canvas.setAttribute('tabindex', '0')
+  }
+  canvas.focus({ preventScroll: true })
+}
+
+/** 2D：禁用内置缩放，由自定义滚轮接管 */
+export function syncOrthographicControllerState(map) {
+  const controller = map.scene?.screenSpaceCameraController
+  if (!controller) return
+  controller.enableTilt = false
+  controller.enableLook = false
+  controller.enableZoom = false
+  controller.enableCollisionDetection = false
+  controller.inertiaZoom = 0
+  map.camera.cancelFlight()
+}
+
+/** 3D：恢复 Cesium 默认相机交互（含滚轮缩放） */
+export function restorePerspectiveControllerState(map) {
+  const controller = map.scene?.screenSpaceCameraController
+  if (!controller) return
+  controller.enableTilt = true
+  controller.enableLook = true
+  controller.enableZoom = true
+  controller.enableCollisionDetection = true
+  controller.inertiaZoom = 0.8
+  controller.minimumZoomDistance = 1.0
+  controller.maximumZoomDistance = Number.POSITIVE_INFINITY
+  map.camera.cancelFlight()
+}
+
+function applyOrthographicZoom(map, mapId, delta) {
+  const factor = Math.pow(ORTHO_WHEEL_ZOOM_RATE, -delta / 120)
+  applyOrthographicZoomFactor(map, mapId, factor)
+}
+
+/**
+ * 在 canvas capture 阶段拦截滚轮，绕过 ScreenSpaceCameraController 默认缩放
+ */
+export function setupOrthographicWheelZoom(map, mapId) {
+  if (!map?.canvas) return
+  teardownOrthographicWheelZoom(map)
+  syncOrthographicControllerState(map)
+
+  const onWheel = (event) => {
+    if (!(map.camera.frustum instanceof Cesium.OrthographicFrustum)) return
+    event.preventDefault()
+    event.stopImmediatePropagation()
+    const delta = -(event.deltaY || event.wheelDelta || 0)
+    applyOrthographicZoom(map, mapId, delta)
+  }
+
+  map.canvas.addEventListener('wheel', onWheel, { passive: false, capture: true })
+  orthoWheelCleanups.set(map, () => {
+    map.canvas.removeEventListener('wheel', onWheel, { capture: true })
+    orthoWheelCleanups.delete(map)
+  })
+  ensureMapFocus(map)
+}
+
+export function teardownOrthographicWheelZoom(map) {
+  if (!map || map.isDestroyed?.()) return
+  orthoWheelCleanups.get(map)?.()
+}
+
+/**
+ * 按 2D/3D 切换相机交互
+ * @param {object} helpers.applyOrthographicFrustum
+ * @param {object} helpers.getEffective2DOrthoWidth
+ */
+export function syncCameraInteractionMode(map, mapId, sceneMode, helpers) {
+  if (!map || map.isDestroyed?.()) return
+  const { applyOrthographicFrustum, getEffective2DOrthoWidth } = helpers
+  const mapStore = useMapStore()
+
+  if (sceneMode === '2D') {
+    const orthoWidth = mapStore.getViewOrthoWidth(mapId) || getEffective2DOrthoWidth(map)
+    if (orthoWidth > 0) {
+      applyOrthographicFrustum(map, undefined, orthoWidth)
+    }
+    setupOrthographicWheelZoom(map, mapId)
+  } else {
+    teardownOrthographicWheelZoom(map)
+    restorePerspectiveControllerState(map)
+  }
+  map.scene.requestRender()
+}

package/js/utils/orthographicCameraZoom.js

@@ -0,0 +1,28 @@
+import * as Cesium from 'cesium'
+import { useMapStore } from '../stores/mapStore.js'
+
+/**
+ * 2D 正交缩放：同步修改 frustum.width 与相机高度，不使用 setView（避免首帧透视 dollying）
+ * @returns {boolean} 是否已按正交模式处理
+ */
+export function applyOrthographicZoomFactor(map, mapId, factor) {
+  const camera = map?.camera
+  const frustum = camera?.frustum
+  if (!(frustum instanceof Cesium.OrthographicFrustum)) return false
+
+  frustum.width = Cesium.Math.clamp(frustum.width * factor, 100, 10000000)
+
+  const cartographic = camera.positionCartographic
+  if (cartographic) {
+    const newHeight = Cesium.Math.clamp(cartographic.height * factor, 100, 1000000)
+    const updated = cartographic.clone()
+    updated.height = newHeight
+    camera.position = Cesium.Cartographic.toCartesian(updated)
+  }
+
+  if (mapId) {
+    useMapStore().setViewOrthoWidth(frustum.width, mapId)
+  }
+  map.scene.requestRender()
+  return true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huweili-cesium",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
   "type": "module",
   "main": "./index.js",
@@ -87,16 +87,34 @@
     "./utils/getMapCenterPosition.js": "./js/utils/getMapCenterPosition.js",
     "./utils/droneSelection": "./js/utils/droneSelection.js",
     "./utils/droneSelection.js": "./js/utils/droneSelection.js",
+    "./js/utils/droneSelection": "./js/utils/droneSelection.js",
+    "./js/utils/droneSelection.js": "./js/utils/droneSelection.js",
+    "./utils/orthographicCameraZoom": "./js/utils/orthographicCameraZoom.js",
+    "./utils/orthographicCameraZoom.js": "./js/utils/orthographicCameraZoom.js",
+    "./utils/cameraInteraction": "./js/utils/cameraInteraction.js",
+    "./utils/cameraInteraction.js": "./js/utils/cameraInteraction.js",
+    "./js/utils/orthographicCameraZoom": "./js/utils/orthographicCameraZoom.js",
+    "./js/utils/orthographicCameraZoom.js": "./js/utils/orthographicCameraZoom.js",
     "./utils/cesium/object": "./js/utils/cesium/object.js",
     "./utils/cesium/object.js": "./js/utils/cesium/object.js",
+    "./js/utils/cesium/object": "./js/utils/cesium/object.js",
+    "./js/utils/cesium/object.js": "./js/utils/cesium/object.js",
     "./utils/cesium/json": "./js/utils/cesium/json.js",
     "./utils/cesium/json.js": "./js/utils/cesium/json.js",
+    "./js/utils/cesium/json": "./js/utils/cesium/json.js",
+    "./js/utils/cesium/json.js": "./js/utils/cesium/json.js",
     "./config": "./js/config/index.js",
     "./config/index": "./js/config/index.js",
+    "./js/config": "./js/config/index.js",
+    "./js/config/index": "./js/config/index.js",
     "./config/hooks": "./js/config/hooks.js",
     "./config/hooks.js": "./js/config/hooks.js",
+    "./js/config/hooks": "./js/config/hooks.js",
+    "./js/config/hooks.js": "./js/config/hooks.js",
     "./api/gaode": "./js/api/gaode.js",
-    "./api/gaode.js": "./js/api/gaode.js"
+    "./api/gaode.js": "./js/api/gaode.js",
+    "./js/api/gaode": "./js/api/gaode.js",
+    "./js/api/gaode.js": "./js/api/gaode.js"
   },
   "files": [
     "index.js",
@@ -107,8 +125,7 @@
   ],
   "scripts": {
     "sync": "node scripts/sync-from-source.mjs",
-    "prepublishOnly": "node scripts/verify-files.mjs",
-    "prepare": "node scripts/welcome.js"
+    "prepublishOnly": "node scripts/verify-files.mjs"
   },
   "keywords": [
     "cesium",