huweili-cesium 1.2.6 → 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/index.vue

@@ -1,765 +1,325 @@
 <template>
-
-  <div class="cesium-map-wrapper" @pointerdown="handleMapPointerDown">
-
+  <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 { processMapConfigColors } from './js/tileProviders.js'
-
-import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery.js'
-
 import { createCustomToolbarButtons } from './js/customToolbarButtons.js'
-
-import { ensureMapFocus } from './js/utils/cameraInteraction.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: () => [],
-
-  },
-
+  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
-
-  }
-
+  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 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),
+  })
+}
 
-const initCesium = async () => {
+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)
-
-
-
-  let mapOptions
-
-  if (MapConfig) {
-
-    mapOptions = MapConfig
-
-  }
-
-
-
-  if (DroneConfig) {
-
+  if (DroneConfig?.trailTime != null) {
     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)
-
-  }
-
-
-
+  let 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,
-
+    mapOptions = await resolveMapOptions({
+      mapConfig: MapConfig,
+      propsOptions: props.options,
+      merge,
+      toRaw,
     })
-
-
-
-    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) {
+      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)
 
-    if (mapOptions.control.disableEntityClick) {
-
-      map.selectedEntityChanged.addEventListener(() => {
-
-        map.selectedEntity = undefined
-
-      })
-
-    }
-
-
+    // 3. Imagery：在线底图
+    applyConfiguredImagery(map, mapOptions)
 
+    // 4. Input：双击、选中、鼠标扩展
+    applyViewerInputPolicy(map, mapOptions)
     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 || {}
-
-
-
+    // 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}`)
 
-    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')
-
-      })
-
-    }
-
-
-
+    // 8. 自管渲染循环（useDefaultRenderLoop: false）
     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
-
-
-
+// ---------------------------------------------------------------------------
+// 6. 渲染循环
+// ---------------------------------------------------------------------------
 function startContinuousRendering(viewer) {
-
   if (animationId) return
-
-  function animate() {
-
+  const tick = () => {
     const now = Date.now()
-
     if (
-
       isMapActive &&
-
       !document.hidden &&
-
       map &&
-
       !map.isDestroyed?.() &&
-
       now - lastActiveTime < IDLE_TIMEOUT
-
     ) {
-
       viewer.render()
-
     }
-
-    animationId = requestAnimationFrame(animate)
-
+    animationId = requestAnimationFrame(tick)
   }
-
-  animate()
-
+  tick()
 }
 
-
-
 function stopRenderLoop() {
-
   if (animationId) {
-
     cancelAnimationFrame(animationId)
-
     animationId = null
-
   }
-
 }
 
-
-
 function setupActivityListeners() {
-
-  const activities = ['mousemove', 'keydown', 'touchmove', 'wheel', 'click']
-
-  activities.forEach((event) => {
-
+  ;['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)
-
-    }
-
+    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)
-
-  }
-
+  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.6",
+  "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",