huweili-cesium 1.2.4 → 1.2.7

package/README.md

@@ -86,7 +86,18 @@ export default defineConfig({
 
 事件：`@onload`，参数 `{ map, center, mapId, toolbar }`（`map` 为 Cesium `Viewer` 实例；`toolbar` 可在加载后动态增删按钮）。
 
- ### 各项目自定义工具栏
+### 为何不用 Cesium 内置 2D 模式
+
+Viewer 固定为 `SCENE3D`，业务上的「2D」是 **正交相机 + 俯视**（`basis.js` / `cameraInteraction.js`），不切换 `SCENE2D` / `COLUMBUS_VIEW`。简要优点：
+
+- **2D/3D 切换更顺**：无场景变形（morph），透视与正交互换，缩放与锚点更易对齐（含工具栏切换、RTK 跟飞）。
+- **渲染一致**：无人机、轨迹、围栏等与 3D 同一套规则，少踩 2D 投影下的显示差异。
+- **交互可控**：2D 可锁定俯视、自定义滚轮缩放（正交宽度），避免与内置 2D 控制器行为不一致。
+- **语义清晰**：`mapStore` 的 `2D`/`3D` 表示业务视角，不与 Cesium `SceneMode` 枚举混用。
+
+配置里 `scene.sceneMode: '2D'` 表示初始化俯视正交，而非启用 Cesium 平面地图模式。
+
+### 各项目自定义工具栏
 
 **方式 1：组件 props（推荐）**
 

package/components/wsIndicator/wsIndicator.vue

@@ -21,7 +21,7 @@
    * - 收到无人机数据时绿色高亮闪烁（.active）
    */
   import { ref, computed, onMounted, onUnmounted, nextTick } from 'vue'
-  import { useEventBus } from '../../js/utils/useEventBus'
+  import { useEventBus } from '../../js/utils/useEventBus.js'
   
   const { on, off } = useEventBus()
   

package/index.vue

@@ -1,385 +1,325 @@
-<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>
-
+<template>
+  <div class="cesium-map-wrapper">
+    <div class="cesium-container" ref="cesiumContainer" />
+    <WsIndicator />
+  </div>
+</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'
+import WsIndicator from './components/wsIndicator/wsIndicator.vue'
+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 { 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 {
+  addToolbarButton,
+  addToolbarButtons,
+  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: () => [] },
+})
+
+// ---------------------------------------------------------------------------
+// 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. 工具栏
+// ---------------------------------------------------------------------------
+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
+}
+
+function mountToolbarButtons(viewer) {
+  if (!viewer || viewer.isDestroyed?.()) return
+  removeToolbarButtons(customButtons)
+  customButtons = []
+  const configs = resolveToolbarButtonConfigs()
+  if (configs.length) {
+    customButtons = addToolbarButtons(viewer, configs)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 4. 场景模式事件（工具栏 2D/3D 切换 → 同步相机交互）
+// ---------------------------------------------------------------------------
+function handleSceneModeChange({ mapId, sceneMode }) {
+  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
+  syncCameraInteractionMode(map, mapId, sceneMode)
+}
+
+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 }
+}
+
+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),
+  })
+}
+
+function finalizeCameraAndRender(viewer, mapOptions, sceneMode) {
+  viewer.resize()
+  setInitialCameraView(viewer, mapOptions.scene.center, sceneMode, props.mapId)
+  viewer.render()
+}
+
+// ---------------------------------------------------------------------------
+// 5. 地图初始化主流程
+// ---------------------------------------------------------------------------
+async function initCesium() {
+  if (!cesiumContainer.value) return
+
+  mapStore.setMapLoadSta(MapLoadStatus.LOADING, props.mapId)
+  if (DroneConfig?.trailTime != null) {
+    mapStore.setTrailTime(DroneConfig.trailTime, props.mapId)
+  }
+
+  let mapOptions
+  try {
+    mapOptions = await resolveMapOptions({
+      mapConfig: MapConfig,
+      propsOptions: props.options,
+      merge,
+      toRaw,
+    })
+    if (!mapOptions) {
+      throw new Error('缺少地图配置 MapConfig / options')
+    }
+
+    // 1. Viewer：控件、地形、渲染循环策略
+    const viewerOptions = await buildViewerOptions(mapOptions)
+    const contextOptions = buildContextOptions()
+    map = createMapViewer(cesiumContainer.value, viewerOptions, contextOptions)
+
+    // 2. Scene / Globe：光照、雾、大气
+    const sceneRenderOptions = buildSceneRenderOptions(mapOptions)
+    applySceneRenderOptions(map, sceneRenderOptions)
+
+    // 3. Imagery：在线底图
+    applyConfiguredImagery(map, mapOptions)
+
+    // 4. Input：双击、选中、鼠标扩展
+    applyViewerInputPolicy(map, mapOptions)
+    mouseController(map, props.mapId)
+
+    // 5. 业务上下文：Pinia + 工具栏 + 加载态
+    const { center, sceneMode } = registerMapContext(map, mapOptions)
+    mountToolbarButtons(map)
+    mapStore.setMapLoadSta(MapLoadStatus.LOADED, props.mapId)
+
+    // 6. 相机与首帧（须在容器尺寸稳定后 resize）
+    finalizeCameraAndRender(map, mapOptions, sceneMode)
+
+    // 7. 通知宿主（相机、工具栏已就绪）
+    emitMapReady(map, center)
+    console.log(`Cesium 地图加载成功，mapId: ${props.mapId}`)
+
+    // 8. 自管渲染循环（useDefaultRenderLoop: false）
+    startContinuousRendering(map)
+  } catch (error) {
+    mapStore.setMapLoadSta(MapLoadStatus.FAILED, props.mapId)
+    console.error('Cesium 地图加载失败:', error)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 6. 渲染循环
+// ---------------------------------------------------------------------------
+function startContinuousRendering(viewer) {
+  if (animationId) return
+  const tick = () => {
+    const now = Date.now()
+    if (
+      isMapActive &&
+      !document.hidden &&
+      map &&
+      !map.isDestroyed?.() &&
+      now - lastActiveTime < IDLE_TIMEOUT
+    ) {
+      viewer.render()
+    }
+    animationId = requestAnimationFrame(tick)
+  }
+  tick()
+}
+
+function stopRenderLoop() {
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+    animationId = null
+  }
+}
+
+function setupActivityListeners() {
+  ;['mousemove', 'keydown', 'touchmove', 'wheel', 'click'].forEach((event) => {
+    document.addEventListener(event, () => {
+      lastActiveTime = Date.now()
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// 7. keep-alive 恢复
+// ---------------------------------------------------------------------------
+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)
+  })
+}
+
+// ---------------------------------------------------------------------------
+// 8. 生命周期
+// ---------------------------------------------------------------------------
+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/index.js

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

package/js/utils/cesiumMapBootstrap.js

@@ -0,0 +1,164 @@
+/**
+ * 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,
+  })
+}

package/package.json

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