huweili-cesium 1.2.7 → 1.2.10

package/index.vue

@@ -6,14 +6,6 @@
 </template>
 
 <script setup>
-/**
- * CesiumMap 组件 — 编排层
- *
- * 职责边界：
- * - 本文件：Vue 生命周期、Pinia 注册、渲染循环、工具栏、onload 事件
- * - cesiumMapBootstrap.js：Viewer / Scene / Imagery / Input 分层配置
- * - basis.js + cameraInteraction.js：2D 正交 / 3D 透视相机与交互
- */
 import * as Cesium from 'cesium'
 import { ref, watch, onMounted, onUnmounted, onActivated, onDeactivated, nextTick, toRaw } from 'vue'
 import { MapConfig, DroneConfig } from './js/config/index.js'
@@ -22,21 +14,9 @@ import { objectUtils } from './js/utils/cesium/object.js'
 import { basicConfig, teardownOrthographicWheelZoom } from './js/basis.js'
 import { useMapStore, MapLoadStatus } from './js/stores/mapStore.js'
 import { useEventBus } from './js/utils/useEventBus.js'
+import { processMapConfigColors } from './js/tileProviders.js'
+import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery.js'
 import { createCustomToolbarButtons } from './js/customToolbarButtons.js'
-import {
-  resolveMapOptions,
-  buildViewerOptions,
-  buildContextOptions,
-  buildSceneRenderOptions,
-  applySceneRenderOptions,
-  applyConfiguredImagery,
-  applyViewerInputPolicy,
-  createMapViewer,
-} from './js/utils/cesiumMapBootstrap.js'
-
-// ---------------------------------------------------------------------------
-// 0. 依赖注入（包内模块能力）
-// ---------------------------------------------------------------------------
 const { merge } = objectUtils()
 const { mouseController, setInitialCameraView, syncCameraInteractionMode } = basicConfig()
 const {
@@ -45,38 +25,46 @@ const {
   removeToolbarButtons,
   createDefaultToolbarButtons,
 } = createCustomToolbarButtons()
+
 const mapStore = useMapStore()
 const { on: onEvent, off: offEvent } = useEventBus()
-
-// ---------------------------------------------------------------------------
-// 1. 组件接口
-// ---------------------------------------------------------------------------
 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: () => [] },
+  options: {
+    type: Object,
+    default: undefined,
+  },
+  mapId: {
+    type: String,
+    default: 'default',
+  },
+  showDefaultToolbar: {
+    type: Boolean,
+    default: true,
+  },
+  toolbarButtons: {
+    type: Array,
+    default: undefined,
+  },
+  extraToolbarButtons: {
+    type: Array,
+    default: () => [],
+  },
 })
 
-// ---------------------------------------------------------------------------
-// 2. 运行时状态
-// ---------------------------------------------------------------------------
-const cesiumContainer = ref(null)
-/** @type {import('cesium').Viewer|null} */
-let map = null
-let customButtons = []
-let isMapActive = true
-let animationId = null
-let lastActiveTime = Date.now()
-const IDLE_TIMEOUT = 30000
-
-// ---------------------------------------------------------------------------
-// 3. 工具栏
-// ---------------------------------------------------------------------------
+/**
+ * 解析工具栏按钮配置
+ * 
+ * 优先级规则：
+ * 1. 如果传入了完整的 toolbarButtons 数组，直接使用
+ * 2. 否则组合默认按钮和额外按钮
+ * 
+ * @returns {Array} 工具栏按钮配置数组
+ */
 function resolveToolbarButtonConfigs() {
-  if (props.toolbarButtons?.length) return props.toolbarButtons
+  if (props.toolbarButtons?.length) {
+    return props.toolbarButtons
+  }
   const configs = []
   if (props.showDefaultToolbar) {
     configs.push(...createDefaultToolbarButtons({ mapId: props.mapId }))
@@ -87,132 +75,245 @@ function resolveToolbarButtonConfigs() {
   return configs
 }
 
+/**
+ * 处理场景模式变化（2D/3D 切换）
+ * 
+ * 当 mapStore 中的场景模式发生变化时触发，同步更新相机交互模式
+ * 
+ * @param {Object} param - 场景模式变化事件参数
+ * @param {string} param.mapId - 地图实例ID
+ * @param {string} param.sceneMode - 场景模式（'2D' 或 '3D'）
+ */
+const handleSceneModeChange = ({ mapId, sceneMode }) => {
+  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
+  syncCameraInteractionMode(map, mapId, sceneMode)
+}
+
+const cesiumContainer = ref(null)
+let map = null
+let customButtons = []
+let isMapActive = true
+
+/**
+ * 挂载工具栏按钮到地图
+ * 
+ * 先移除已存在的按钮，再根据配置添加新按钮
+ * 
+ * @param {Cesium.Viewer} viewer - Cesium 地图实例
+ */
 function mountToolbarButtons(viewer) {
   if (!viewer || viewer.isDestroyed?.()) return
-  removeToolbarButtons(customButtons)
+  removeToolbarButtons(customButtons) // 移除已存在的自定义工具栏按钮
   customButtons = []
-  const configs = resolveToolbarButtonConfigs()
-  if (configs.length) {
-    customButtons = addToolbarButtons(viewer, configs)
+  const toolbarConfigs = resolveToolbarButtonConfigs() // 解析工具栏按钮配置
+  if (toolbarConfigs.length) {
+    customButtons = addToolbarButtons(viewer, toolbarConfigs) // 添加自定义工具栏按钮
   }
 }
 
-// ---------------------------------------------------------------------------
-// 4. 场景模式事件（工具栏 2D/3D 切换 → 同步相机交互）
-// ---------------------------------------------------------------------------
-function handleSceneModeChange({ mapId, sceneMode }) {
-  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
-  syncCameraInteractionMode(map, mapId, sceneMode)
-}
+/**
+ * 初始化 Cesium 地图
+ * 
+ * 完整的地图初始化流程：
+ * 1. 设置加载状态
+ * 2. 合并配置（MapConfig + DroneConfig + props.options）
+ * 3. 创建 Cesium Viewer 实例
+ * 4. 初始化地图工具和事件
+ * 5. 触发 onload 事件
+ */
+const initCesium = async () => {
+  if (!cesiumContainer.value) return
+  mapStore.setMapLoadSta(MapLoadStatus.LOADING, props.mapId)
 
-function registerMapContext(viewer, mapOptions) {
-  const center = mapOptions.scene.center || {}
-  const sceneMode = mapOptions.scene.sceneMode || '3D'
-
-  mapStore.setMapInfo(
-    'center',
-    {
-      lng: center.lng,
-      lat: center.lat,
-      heading: center.heading,
-      pitch: center.pitch,
-      roll: center.roll,
-      duration: center.duration,
-      alt: center.alt,
-    },
-    props.mapId,
-  )
-  mapStore.setMap(viewer, props.mapId)
-  mapStore.setSceneMode(sceneMode, props.mapId)
-
-  return { center, sceneMode }
-}
+  let mapOptions
+  if (MapConfig) {
+    mapOptions = MapConfig
+  }
 
-function emitMapReady(viewer, center) {
-  emit('onload', {
-    map: viewer,
-    center,
-    mapId: props.mapId,
-    toolbar: {
-      addToolbarButton: (opt) => addToolbarButton(viewer, opt),
-      addToolbarButtons: (opts) => addToolbarButtons(viewer, opts),
-      removeToolbarButtons,
-    },
-    syncCameraInteractionMode: (mode) => syncCameraInteractionMode(viewer, props.mapId, mode),
-  })
-}
+  if (DroneConfig) {
+    mapStore.setTrailTime(DroneConfig.trailTime, props.mapId)
+  }
 
-function finalizeCameraAndRender(viewer, mapOptions, sceneMode) {
-  viewer.resize()
-  setInitialCameraView(viewer, mapOptions.scene.center, sceneMode, props.mapId)
-  viewer.render()
-}
+  if (props.options) {
+    let exOptions
+    if (props.options.then) {
+      exOptions = toRaw(await props.options)
+    } else {
+      exOptions = toRaw(props.options)
+    }
 
-// ---------------------------------------------------------------------------
-// 5. 地图初始化主流程
-// ---------------------------------------------------------------------------
-async function initCesium() {
-  if (!cesiumContainer.value) return
+    if (mapOptions) {
+      mapOptions = merge(mapOptions, exOptions)
+    } else {
+      mapOptions = exOptions
+    }
+  }
 
-  mapStore.setMapLoadSta(MapLoadStatus.LOADING, props.mapId)
-  if (DroneConfig?.trailTime != null) {
-    mapStore.setTrailTime(DroneConfig.trailTime, props.mapId)
+  if (mapOptions) {
+    mapOptions = processMapConfigColors(mapOptions)
   }
 
-  let mapOptions
   try {
-    mapOptions = await resolveMapOptions({
-      mapConfig: MapConfig,
-      propsOptions: props.options,
-      merge,
-      toRaw,
-    })
-    if (!mapOptions) {
-      throw new Error('缺少地图配置 MapConfig / options')
+    // 1、Viewer 创建参数
+    const viewerOptions = {
+      sceneMode: Cesium.SceneMode.SCENE3D, // 场景模式：固定为 3D（2D/3D 由相机与正交投影切换，不用 Cesium 内置 2D 模式）
+      useDefaultRenderLoop: false, // 禁用默认渲染循环，由应用自行 requestAnimationFrame 渲染
+      baseLayer: mapOptions.control.imageryProvider === false ? false : undefined, // false 时禁用默认底图，后续由 applyImageryLayers 加载
+      baseLayerPicker: mapOptions.control.baseLayerPicker, // 底图图层选择器
+      geocoder: mapOptions.control.geocoder, // 地址搜索框
+      homeButton: mapOptions.control.homeButton, // 回到初始视角按钮
+      sceneModePicker: mapOptions.control.sceneModePicker, // 2D/哥伦布/3D 场景模式切换器
+      navigationHelpButton: mapOptions.control.navigationHelpButton, // 导航操作说明按钮
+      animation: mapOptions.control.animation, // 动画控件
+      timeline: mapOptions.control.timeline, // 时间轴
+      infoBox: mapOptions.control.infoBox, // 实体信息弹窗
+      fullscreenButton: mapOptions.control.fullscreenButton, // 全屏按钮
+      vrButton: mapOptions.control.vrButton, // VR 模式按钮
+      terrainProvider: mapOptions.terrain.show // 地形服务；不开启时为 undefined
+        ? 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'), // 用空容器替换默认版权水印区域
     }
 
-    // 1. Viewer：控件、地形、渲染循环策略
-    const viewerOptions = await buildViewerOptions(mapOptions)
-    const contextOptions = buildContextOptions()
-    map = createMapViewer(cesiumContainer.value, viewerOptions, contextOptions)
+    // 2、WebGL 上下文与 GPU 偏好（传入 Viewer 的 contextOptions）
+    const contextOptions = {
+      webgl: {
+        alpha: false, // 禁用 canvas 透明通道，减少合成开销
+        depth: true, // 启用深度缓冲，保证远近正确遮挡
+        stencil: false, // 关闭模板缓冲，一般地图场景用不到
+        antialias: true, // 开启 MSAA 抗锯齿
+        premultipliedAlpha: true, // 预乘 alpha，与 Cesium 默认混合方式一致
+        preserveDrawingBuffer: false, // 不保留上一帧缓冲（截图需 true）
+        failIfMajorPerformanceCaveat: false, // 低性能 GPU 仍尝试创建上下文，避免直接失败
+      },
+      requestWebGl2: true, // 优先使用 WebGL 2.0
+      powerPreference: 'high-performance', // 提示浏览器选用独显/高性能 GPU
+    }
 
-    // 2. Scene / Globe：光照、雾、大气
-    const sceneRenderOptions = buildSceneRenderOptions(mapOptions)
-    applySceneRenderOptions(map, sceneRenderOptions)
+    // 3、场景渲染项（Viewer 创建后再写到 scene / globe，对应 mapOptions.scene）
+    const sceneRenderOptions = {
+      debugShowFramesPerSecond: mapOptions.scene.debugShowFramesPerSecond, // 左上角 FPS 调试
+      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, // 光照以太阳为参考
+    }
 
-    // 3. Imagery：在线底图
-    applyConfiguredImagery(map, mapOptions)
+    map = new Cesium.Viewer(cesiumContainer.value, {
+      ...viewerOptions, // 控件、地形、底图等 Viewer 级配置
+      contextOptions, // WebGL 创建参数
+    })
 
-    // 4. Input：双击、选中、鼠标扩展
-    applyViewerInputPolicy(map, mapOptions)
-    mouseController(map, props.mapId)
+    // 4、将 sceneRenderOptions 应用到已创建的 Scene / Globe
+    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 activeBasemap = resolveOnlineBasemap(mapOptions) // 解析在线底图
+    if (activeBasemap) {
+      applyImageryLayers(map, mapOptions, activeBasemap) // 应用在线底图
+      console.log(`加载在线底图：${activeBasemap.name}，URL：${activeBasemap.url}`)
+      window._currentBasemapId = activeBasemap.id
+    } else { // 未找到可用底图，Cesium 将使用默认底图或空底图显示
+      console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
+    }
 
-    // 5. 业务上下文：Pinia + 工具栏 + 加载态
-    const { center, sceneMode } = registerMapContext(map, mapOptions)
-    mountToolbarButtons(map)
-    mapStore.setMapLoadSta(MapLoadStatus.LOADED, props.mapId)
+    if (map.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
+      // 移除双击左键事件，防止地图缩放
+      map.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
+    }
 
-    // 6. 相机与首帧（须在容器尺寸稳定后 resize）
-    finalizeCameraAndRender(map, mapOptions, sceneMode)
+    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)
+    const sceneMode = mapOptions.scene.sceneMode || '3D'
+    mapStore.setSceneMode(sceneMode, props.mapId)
+
+    const center = mapOptions.scene.center || {}
+
+    mountToolbarButtons(map) // 挂载工具栏按钮到地图
+    mapStore.setMapLoadSta(MapLoadStatus.LOADED, props.mapId)
 
-    // 7. 通知宿主（相机、工具栏已就绪）
-    emitMapReady(map, center)
     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() // 渲染地图
 
-    // 8. 自管渲染循环（useDefaultRenderLoop: false）
+    // 如果场景模式为 2D，则同步相机交互模式 （因为初始化相机视角时，已经同步了相机交互模式，保险起见再同步一次）
+    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)
-  }
+    mapStore.setMapLoadSta(MapLoadStatus.FAILED, props.mapId) // 设置地图加载状态为失败
+    console.error('Cesium 地图加载失败:', error) 
 }
 
-// ---------------------------------------------------------------------------
-// 6. 渲染循环
-// ---------------------------------------------------------------------------
+let animationId = null
+let lastActiveTime = Date.now()
+const IDLE_TIMEOUT = 30000
+
+/**
+ * 启动持续渲染循环
+ * 
+ * 使用 requestAnimationFrame 维持地图持续渲染，确保动画效果流畅
+ * 渲染条件：
+ * 1. 地图处于活跃状态（isMapActive = true）
+ * 2. 页面未隐藏（document.hidden = false）
+ * 3. 地图实例存在且未销毁
+ * 4. 最近有用户活动（lastActiveTime 小于空闲超时时间）
+ * 
+ * @param {Cesium.Viewer} viewer - Cesium 地图实例
+ */
 function startContinuousRendering(viewer) {
   if (animationId) return
-  const tick = () => {
+  function animate() {
     const now = Date.now()
     if (
       isMapActive &&
@@ -223,11 +324,17 @@ function startContinuousRendering(viewer) {
     ) {
       viewer.render()
     }
-    animationId = requestAnimationFrame(tick)
+    animationId = requestAnimationFrame(animate)
   }
-  tick()
+  animate()
 }
 
+/**
+ * 停止持续渲染循环
+ * 
+ * 取消 requestAnimationFrame，释放资源
+ * 用于 keep-alive 缓存、组件卸载或手动暂停渲染场景
+ */
 function stopRenderLoop() {
   if (animationId) {
     cancelAnimationFrame(animationId)
@@ -235,23 +342,49 @@ function stopRenderLoop() {
   }
 }
 
+/**
+ * 设置用户活动监听器
+ * 
+ * 监听用户的各种交互行为，更新最后活动时间戳
+ * 用于配合持续渲染循环判断是否需要继续渲染地图
+ * 
+ * 监听的事件类型：
+ * - mousemove：鼠标移动
+ * - keydown：键盘按键
+ * - touchmove：触摸移动
+ * - wheel：滚轮滚动
+ * - click：点击
+ */
 function setupActivityListeners() {
-  ;['mousemove', 'keydown', 'touchmove', 'wheel', 'click'].forEach((event) => {
+  const activities = ['mousemove', 'keydown', 'touchmove', 'wheel', 'click']
+  activities.forEach((event) => {
     document.addEventListener(event, () => {
       lastActiveTime = Date.now()
     })
   })
 }
 
-// ---------------------------------------------------------------------------
-// 7. keep-alive 恢复
-// ---------------------------------------------------------------------------
+/**
+ * 从 keep-alive 缓存中恢复地图渲染
+ * 
+ * 当使用 keep-alive 包裹地图组件时，组件被导航离开后会被缓存
+ * 当再次导航回来时，需要恢复地图的活跃状态和渲染循环
+ * 
+ * 恢复步骤：
+ * 1. 设置当前地图ID到store
+ * 2. 标记地图为活跃状态
+ * 3. 更新最后活动时间戳
+ * 4. 在 nextTick 中执行：
+ *    - 调整地图尺寸（确保容器大小正确）
+ *    - 同步相机交互模式（2D/3D）
+ *    - 执行一次渲染
+ *    - 启动持续渲染循环（如果尚未启动）
+ */
 function resumeMapAfterCache() {
   if (!map || map.isDestroyed?.()) return
   mapStore.setCurrentMapId(props.mapId)
   isMapActive = true
   lastActiveTime = Date.now()
-
   nextTick(() => {
     if (!map || map.isDestroyed?.()) return
     map.resize()
@@ -262,51 +395,57 @@ function resumeMapAfterCache() {
   })
 }
 
-// ---------------------------------------------------------------------------
-// 8. 生命周期
-// ---------------------------------------------------------------------------
+// 宿主传入的 toolbarButtons 变化时，重新挂载工具栏（先移除旧按钮再按新配置添加）
 watch(
   () => props.toolbarButtons,
   () => {
-    if (map && !map.isDestroyed?.()) mountToolbarButtons(map)
+    if (map && !map.isDestroyed?.()) { // 如果地图实例存在且未销毁，则重新挂载工具栏
+      mountToolbarButtons(map) // 重新挂载工具栏
+    }
   },
-  { deep: true },
+  { deep: true }, // 深度监听：数组项或按钮对象字段变更也会触发
 )
 
 onMounted(() => {
-  mapStore.setCurrentMapId(props.mapId)
-  setupActivityListeners()
-  onEvent('map-scene-mode-changed', handleSceneModeChange)
-  initCesium()
+  mapStore.setCurrentMapId(props.mapId) // 初始化当前地图ID
+  setupActivityListeners() // 初始化用户活动监听器，用于判断是否需要继续渲染地图，避免空闲超时导致的渲染暂停
+  onEvent('map-scene-mode-changed', handleSceneModeChange) // 监听场景模式变化事件，用于同步相机交互模式
+  initCesium() // 初始化 Cesium 地图实例
 })
 
+// 组件激活时，恢复地图渲染
 onActivated(() => {
-  mapStore.setCurrentMapId(props.mapId)
-  if (!map || map.isDestroyed?.()) {
-    isMapActive = true
-    initCesium()
+  mapStore.setCurrentMapId(props.mapId) // 设置当前地图ID
+  if (!map || map.isDestroyed?.()) { // 如果地图实例不存在或已销毁，则重新初始化地图
+    isMapActive = true // 标记地图为活跃状态
+    initCesium() // 重新初始化地图
     return
   }
-  resumeMapAfterCache()
+  resumeMapAfterCache() // 从 keep-alive 缓存中恢复地图渲染 （恢复地图的活跃状态和渲染循环）
 })
 
+// 组件失活时，停止地图渲染
 onDeactivated(() => {
-  isMapActive = false
-  stopRenderLoop()
+  isMapActive = false // 标记地图为非活跃状态
+  stopRenderLoop() // 停止持续渲染循环，释放资源
 })
 
+// 组件卸载时，销毁地图实例
 onUnmounted(() => {
   isMapActive = false
-  stopRenderLoop()
-  offEvent('map-scene-mode-changed', handleSceneModeChange)
-  if (map) teardownOrthographicWheelZoom(map)
-  removeToolbarButtons(customButtons)
+  stopRenderLoop() // 停止持续渲染循环，释放资源
+  offEvent('map-scene-mode-changed', handleSceneModeChange) // 移除场景模式变化事件监听器
+  if (map) {
+    teardownOrthographicWheelZoom(map) // 移除正交投影滚轮缩放事件监听器
+  }
+  removeToolbarButtons(customButtons) // 移除自定义工具栏按钮
   customButtons = []
   if (map) {
     map.destroy()
     map = null
   }
-  mapStore.removeMapInstance(props.mapId)
+  mapStore.removeMapInstance(props.mapId) // 从 store 中移除地图实例
+  mapStore.setCurrentMapId('') // 重置当前地图ID
 })
 </script>
 

package/js/index.js

@@ -36,16 +36,6 @@ export {
   teardownOrthographicWheelZoom,
   syncCameraInteractionMode,
 } from './utils/cameraInteraction.js'
-export {
-  resolveMapOptions,
-  buildViewerOptions,
-  buildContextOptions,
-  buildSceneRenderOptions,
-  applySceneRenderOptions,
-  applyConfiguredImagery,
-  applyViewerInputPolicy,
-  createMapViewer,
-} from './utils/cesiumMapBootstrap.js'
 
 export {
   BaseConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huweili-cesium",
-  "version": "1.2.7",
+  "version": "1.2.10",
   "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
   "type": "module",
   "main": "./index.js",

package/js/utils/cesiumMapBootstrap.js

@@ -1,164 +0,0 @@
-/**
- * Cesium Viewer 启动配置（按 Cesium 架构分层）
- *
- * 1. Viewer  — 控件、地形、底图策略、渲染循环开关
- * 2. Context — WebGL 上下文
- * 3. Scene   — 光照、雾、大气、调试项
- * 4. Imagery — 在线底图（业务配置驱动）
- * 5. Input   — 双击、实体选中、鼠标扩展
- */
-import * as Cesium from 'cesium'
-import { processMapConfigColors } from '../tileProviders.js'
-import { applyImageryLayers, resolveOnlineBasemap } from './mapImagery.js'
-
-// ---------------------------------------------------------------------------
-// 阶段 0：合并业务配置
-// ---------------------------------------------------------------------------
-
-/**
- * @param {object} params
- * @param {object} [params.mapConfig] MapConfig
- * @param {object} [params.propsOptions] 组件 props.options（支持 Promise）
- * @param {Function} params.merge objectUtils().merge
- * @param {Function} params.toRaw vue toRaw
- */
-export async function resolveMapOptions({ mapConfig, propsOptions, merge, toRaw }) {
-  let mapOptions = mapConfig || undefined
-
-  if (propsOptions) {
-    const exOptions = propsOptions.then
-      ? toRaw(await propsOptions)
-      : toRaw(propsOptions)
-    mapOptions = mapOptions ? merge(mapOptions, exOptions) : exOptions
-  }
-
-  if (mapOptions) {
-    mapOptions = processMapConfigColors(mapOptions)
-  }
-
-  return mapOptions
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 1：Viewer 构造参数
-// ---------------------------------------------------------------------------
-
-export async function buildViewerOptions(mapOptions) {
-  return {
-    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'),
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 2：WebGL Context
-// ---------------------------------------------------------------------------
-
-export function buildContextOptions() {
-  return {
-    webgl: {
-      alpha: false,
-      depth: true,
-      stencil: false,
-      antialias: true,
-      premultipliedAlpha: true,
-      preserveDrawingBuffer: false,
-      failIfMajorPerformanceCaveat: false,
-    },
-    requestWebGl2: true,
-    powerPreference: 'high-performance',
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 3：Scene / Globe 渲染环境
-// ---------------------------------------------------------------------------
-
-export function buildSceneRenderOptions(mapOptions) {
-  return {
-    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,
-  }
-}
-
-export function applySceneRenderOptions(viewer, options) {
-  viewer.scene.debugShowFramesPerSecond = options.debugShowFramesPerSecond
-  viewer.scene.globe.enableLighting = options.enableLighting
-  viewer.scene.globe.depthTestAgainstTerrain = options.depthTestAgainstTerrain
-  viewer.scene.fog.enabled = options.fogEnabled
-  viewer.scene.skyAtmosphere.show = options.skyAtmosphereShow
-  viewer.scene.globe.dynamicAtmosphereLighting = options.dynamicAtmosphereLighting
-  viewer.scene.globe.dynamicAtmosphereLightingFromSun = options.dynamicAtmosphereLightingFromSun
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 4：Imagery 底图
-// ---------------------------------------------------------------------------
-
-/**
- * @returns {string|undefined} 当前底图 id（写入 window._currentBasemapId）
- */
-export function applyConfiguredImagery(viewer, mapOptions) {
-  const activeBasemap = resolveOnlineBasemap(mapOptions)
-  if (activeBasemap) {
-    applyImageryLayers(viewer, mapOptions, activeBasemap)
-    console.log(`加载在线底图：${activeBasemap.name}，URL：${activeBasemap.url}`)
-    if (typeof window !== 'undefined') {
-      window._currentBasemapId = activeBasemap.id
-    }
-    return activeBasemap.id
-  }
-  console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
-  return undefined
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 5：输入与交互策略
-// ---------------------------------------------------------------------------
-
-export function applyViewerInputPolicy(viewer, mapOptions) {
-  if (viewer.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
-    viewer.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
-  }
-
-  if (mapOptions.control.disableEntityClick) {
-    viewer.selectedEntityChanged.addEventListener(() => {
-      viewer.selectedEntity = undefined
-    })
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 阶段 6：创建 Viewer
-// ---------------------------------------------------------------------------
-
-export function createMapViewer(container, viewerOptions, contextOptions) {
-  return new Cesium.Viewer(container, {
-    ...viewerOptions,
-    contextOptions,
-  })
-}