huweili-cesium 1.0.13 → 1.0.15

package/dronePlannedRoute.js

@@ -0,0 +1,242 @@
+/**
+ * 无人机规划航迹模块
+ *
+ * 根据前端传入的经纬度+高度数组，在空中绘制航迹连线及航点标注。
+ * 无人机实际位置仍由 WebSocket 数据通过 moveDronePoint 驱动。
+ */
+import * as Cesium from 'cesium'
+import { useMapStore } from './stores/mapStore.js'
+
+const PLANNED_ROUTE_STORE_SUFFIX = '_planned_route'
+const DEFAULT_LINE_COLOR = 'rgba(0, 191, 255, 0.85)'
+const DEFAULT_LINE_WIDTH = 3
+
+/**
+ * 将前端航点数组规范为 { lng, lat, height }
+ * 支持字段：lng/lon/longitude, lat/latitude, height/alt/altitude
+ */
+function normalizeWaypoints(waypoints) {
+  if (!Array.isArray(waypoints)) return []
+
+  return waypoints
+    .map((wp, index) => {
+      const lng = Number(wp?.lng ?? wp?.lon ?? wp?.longitude ?? wp?.LONGITUDE)
+      const lat = Number(wp?.lat ?? wp?.latitude ?? wp?.LATITUDE)
+      const height = Number(wp?.height ?? wp?.alt ?? wp?.altitude ?? wp?.HEIGHT ?? 0)
+      if (!Number.isFinite(lng) || !Number.isFinite(lat)) return null
+      return {
+        lng,
+        lat,
+        height: Number.isFinite(height) ? height : 0,
+        index,
+      }
+    })
+    .filter(Boolean)
+}
+
+function getRouteStoreKey(routeId) {
+  return `${routeId}${PLANNED_ROUTE_STORE_SUFFIX}`
+}
+
+function removeRouteEntities(map, routeData) {
+  if (!map || !routeData) return
+
+  routeData.entities?.forEach((entity) => {
+    if (entity) {
+      map.entities.remove(entity)
+    }
+  })
+  routeData.entities = []
+  routeData.polylineEntity = null
+}
+
+export function dronePlannedRouteConfig() {
+  const mapStore = useMapStore()
+
+  /**
+   * 绘制无人机规划航迹（空中折线 + 航点标注）
+   * @param {Object} options
+   * @param {string} options.routeId 航迹唯一标识，通常与无人机 pointId/uavId 一致
+   * @param {string} [options.pointId] 同 routeId，二选一
+   * @param {string} options.mapId 地图实例 ID
+   * @param {Array<{lng, lat, height}|{longitude, latitude, height}>} options.waypoints 航点数组
+   * @param {string} [options.lineColor] 航迹线颜色，默认青色
+   * @param {number} [options.lineWidth] 航迹线宽度
+   * @param {boolean} [options.showWaypointLabels=true] 是否显示「航点1、航点2…」标签
+   * @param {number} [options.waypointPixelSize=10] 航点圆点大小
+   * @param {boolean} [options.flyToRoute=false] 绘制后是否飞到航迹范围
+   * @returns {Object|null} 航迹数据对象
+   */
+  const setDronePlannedRoute = (options = {}) => {
+    const routeId = options.routeId || options.pointId
+    const { mapId, flyToRoute = false } = options
+
+    if (!routeId) {
+      console.warn('setDronePlannedRoute: 缺少 routeId / pointId')
+      return null
+    }
+
+    const normalized = normalizeWaypoints(options.waypoints)
+    if (normalized.length < 1) {
+      console.warn('setDronePlannedRoute: 航点数组为空或无效')
+      return null
+    }
+
+    const map = mapStore.getMap(mapId)
+    if (!map) {
+      console.error('地图实例不存在')
+      return null
+    }
+
+    // 已存在则先清除再重建，保证航迹与航点一致
+    clearDronePlannedRoute({ routeId, mapId })
+
+    const lineColor = options.lineColor || DEFAULT_LINE_COLOR
+    const lineWidth = Number(options.lineWidth) || DEFAULT_LINE_WIDTH
+    const showWaypointLabels = options.showWaypointLabels !== false
+    const waypointPixelSize = Number(options.waypointPixelSize) || 10
+    const color = Cesium.Color.fromCssColorString(lineColor)
+
+    const positions = normalized.map((wp) =>
+      Cesium.Cartesian3.fromDegrees(wp.lng, wp.lat, wp.height)
+    )
+
+    const routeData = {
+      routeId,
+      mapId,
+      waypoints: normalized,
+      entities: [],
+      polylineEntity: null,
+      isVisible: true,
+    }
+
+    if (normalized.length >= 2) {
+      routeData.polylineEntity = map.entities.add({
+        id: `${routeId}_planned_route_line`,
+        name: `规划航迹：${routeId}`,
+        polyline: {
+          positions,
+          width: lineWidth,
+          material: color,
+          arcType: Cesium.ArcType.NONE,
+          clampToGround: false,
+        },
+      })
+      routeData.entities.push(routeData.polylineEntity)
+    }
+
+    normalized.forEach((wp, i) => {
+      const position = Cesium.Cartesian3.fromDegrees(wp.lng, wp.lat, wp.height)
+      const waypointEntity = map.entities.add({
+        id: `${routeId}_planned_route_wp_${i}`,
+        name: `规划航点${i + 1}：${routeId}`,
+        position,
+        point: {
+          pixelSize: waypointPixelSize,
+          color,
+          outlineColor: Cesium.Color.WHITE,
+          outlineWidth: 2,
+          disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        },
+        label: showWaypointLabels
+          ? {
+              text: `航点${i + 1}`,
+              font: '14px Microsoft YaHei, sans-serif',
+              fillColor: Cesium.Color.WHITE,
+              outlineColor: Cesium.Color.BLACK,
+              outlineWidth: 2,
+              style: Cesium.LabelStyle.FILL_AND_OUTLINE,
+              verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+              pixelOffset: new Cesium.Cartesian2(0, -12),
+              disableDepthTestDistance: Number.POSITIVE_INFINITY,
+            }
+          : undefined,
+      })
+      routeData.entities.push(waypointEntity)
+    })
+
+    routeData.destroy = () => {
+      removeRouteEntities(map, routeData)
+      mapStore.removeGraphicMap(getRouteStoreKey(routeId), mapId)
+    }
+
+    mapStore.setGraphicMap(getRouteStoreKey(routeId), routeData, mapId)
+
+    if (flyToRoute && positions.length > 0) {
+      const boundingSphere = Cesium.BoundingSphere.fromPoints(positions)
+      map.camera.flyToBoundingSphere(boundingSphere, { duration: 1.2 })
+    }
+
+    return routeData
+  }
+
+  /**
+   * 更新规划航迹（等价于清除后重新绘制）
+   */
+  const updateDronePlannedRoute = (options) => setDronePlannedRoute(options)
+
+  /**
+   * 清除规划航迹及航点标注
+   * @param {Object} options
+   * @param {string} options.routeId 航迹 ID（或 pointId）
+   * @param {string} options.mapId 地图实例 ID
+   */
+  const clearDronePlannedRoute = (options = {}) => {
+    const routeId = options.routeId || options.pointId
+    const { mapId } = options
+
+    if (!routeId) {
+      console.warn('clearDronePlannedRoute: 缺少 routeId / pointId')
+      return false
+    }
+
+    const storeKey = getRouteStoreKey(routeId)
+    const routeData = mapStore.getGraphicMap(storeKey, mapId)
+    if (!routeData) return false
+
+    const map = mapStore.getMap(mapId)
+    removeRouteEntities(map, routeData)
+    mapStore.removeGraphicMap(storeKey, mapId)
+    return true
+  }
+
+  /**
+   * 显示/隐藏规划航迹
+   */
+  const toggleDronePlannedRouteVisibility = (options = {}) => {
+    const routeId = options.routeId || options.pointId
+    const { mapId, visible } = options
+
+    if (!routeId || visible === undefined) return false
+
+    const routeData = mapStore.getGraphicMap(getRouteStoreKey(routeId), mapId)
+    if (!routeData) {
+      console.warn(`规划航迹不存在，ID: ${routeId}`)
+      return false
+    }
+
+    routeData.isVisible = visible
+    routeData.entities?.forEach((entity) => {
+      if (entity) entity.show = visible
+    })
+    return true
+  }
+
+  /**
+   * 获取已绘制的规划航迹数据
+   */
+  const getDronePlannedRoute = (options = {}) => {
+    const routeId = options.routeId || options.pointId
+    const { mapId } = options
+    if (!routeId) return null
+    return mapStore.getGraphicMap(getRouteStoreKey(routeId), mapId) || null
+  }
+
+  return {
+    setDronePlannedRoute,
+    updateDronePlannedRoute,
+    clearDronePlannedRoute,
+    toggleDronePlannedRouteVisibility,
+    getDronePlannedRoute,
+  }
+}

package/movePointPlannedRoute.js

@@ -0,0 +1,31 @@
+/**
+ * movePoint 扩展模块（不修改原 movePoint.js）
+ *
+ * 在原有 movePointConfig 能力基础上，组合规划航迹模块，
+ * 并提供同时销毁无人机与规划航迹的方法。
+ */
+import { movePointConfig } from './movePoint.js'
+import { dronePlannedRouteConfig } from './dronePlannedRoute.js'
+
+export function movePointPlannedRouteConfig(baseUrl) {
+  const movePoint = movePointConfig(baseUrl)
+  const plannedRoute = dronePlannedRouteConfig()
+
+  /**
+   * 销毁无人机模型、实时轨迹，并清除对应规划航迹
+   */
+  const destroyDroneTrailAndPlannedRoute = (options) => {
+    const result = movePoint.destroyDroneTrail(options)
+    plannedRoute.clearDronePlannedRoute({
+      routeId: options?.pointId,
+      mapId: options?.mapId,
+    })
+    return result
+  }
+
+  return {
+    ...movePoint,
+    ...plannedRoute,
+    destroyDroneTrailAndPlannedRoute,
+  }
+}

package/package.json

@@ -1,101 +1,109 @@
-{
-  "name": "huweili-cesium",
-  "version": "1.0.13",
-  "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
-  "type": "module",
-  "main": "./index.js",
-  "module": "./index.js",
-  "exports": {
-    ".": "./index.js",
-    "./basis": "./basis.js",
-    "./basis.js": "./basis.js",
-    "./captureFenceScreenshot": "./captureFenceScreenshot.js",
-    "./captureFenceScreenshot.js": "./captureFenceScreenshot.js",
-    "./cardPool": "./cardPool.js",
-    "./cardPool.js": "./cardPool.js",
-    "./clickHandler": "./clickHandler.js",
-    "./clickHandler.js": "./clickHandler.js",
-    "./customToolbarButtons": "./customToolbarButtons.js",
-    "./customToolbarButtons.js": "./customToolbarButtons.js",
-    "./drawFence": "./drawFence.js",
-    "./drawFence.js": "./drawFence.js",
-    "./drawFenceNew": "./drawFenceNew.js",
-    "./drawFenceNew.js": "./drawFenceNew.js",
-    "./droneRipple": "./droneRipple.js",
-    "./droneRipple.js": "./droneRipple.js",
-    "./geometry": "./geometry.js",
-    "./geometry.js": "./geometry.js",
-    "./groundLink": "./groundLink.js",
-    "./groundLink.js": "./groundLink.js",
-    "./hemisphere": "./hemisphere.js",
-    "./hemisphere.js": "./hemisphere.js",
-    "./labelDiv": "./labelDiv.js",
-    "./labelDiv.js": "./labelDiv.js",
-    "./movePath": "./movePath.js",
-    "./movePath.js": "./movePath.js",
-    "./movePoint": "./movePoint.js",
-    "./movePoint.js": "./movePoint.js",
-    "./qrCodeGenerator": "./qrCodeGenerator.js",
-    "./qrCodeGenerator.js": "./qrCodeGenerator.js",
-    "./setPath": "./setPath.js",
-    "./setPath.js": "./setPath.js",
-    "./setPoint": "./setPoint.js",
-    "./setPoint.js": "./setPoint.js",
-    "./tileProviders": "./tileProviders.js",
-    "./tileProviders.js": "./tileProviders.js",
-    "./toolbar/basemapSwitcher": "./toolbar/basemapSwitcher.js",
-    "./toolbar/basemapSwitcher.js": "./toolbar/basemapSwitcher.js",
-    "./toolbar/compass": "./toolbar/compass.js",
-    "./toolbar/compass.js": "./toolbar/compass.js",
-    "./toolbar/fullscreenController": "./toolbar/fullscreenController.js",
-    "./toolbar/fullscreenController.js": "./toolbar/fullscreenController.js",
-    "./toolbar/zoomController": "./toolbar/zoomController.js",
-    "./toolbar/zoomController.js": "./toolbar/zoomController.js",
-    "./stores/mapStore": "./stores/mapStore.js",
-    "./stores/mapStore.js": "./stores/mapStore.js",
-    "./utils/eventBus": "./utils/eventBus.js",
-    "./utils/useEventBus": "./utils/useEventBus.js",
-    "./utils/getMapCenterPosition": "./utils/getMapCenterPosition.js",
-    "./utils/droneSelection": "./utils/droneSelection.js",
-    "./config": "./config/index.js",
-    "./config/index": "./config/index.js",
-    "./config/hooks": "./config/hooks.js",
-    "./api/gaode": "./api/gaode.js"
-  },
-  "files": [
-    "*.js",
-    "toolbar/**/*.js",
-    "stores/**/*.js",
-    "utils/**/*.js",
-    "config/**/*.js",
-    "api/**/*.js"
-  ],
-  "scripts": {
-    "sync": "node scripts/sync-from-source.mjs",
-    "prepublishOnly": "node scripts/verify-files.mjs"
-  },
-  "keywords": [
-    "cesium",
-    "map",
-    "drone",
-    "3d",
-    "gis"
-  ],
-  "author": "huweili <czxyhuweili@163.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": ""
-  },
-  "peerDependencies": {
-    "cesium": ">=1.100.0",
-    "mitt": "^3.0.0",
-    "pinia": "^2.0.0 || ^3.0.0",
-    "qrcode": "^1.5.0",
-    "vue": "^3.3.0"
-  },
-  "dependencies": {},
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "huweili-cesium",
+  "version": "1.0.15",
+  "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./basis": "./basis.js",
+    "./basis.js": "./basis.js",
+    "./captureFenceScreenshot": "./captureFenceScreenshot.js",
+    "./captureFenceScreenshot.js": "./captureFenceScreenshot.js",
+    "./cardPool": "./cardPool.js",
+    "./cardPool.js": "./cardPool.js",
+    "./clickHandler": "./clickHandler.js",
+    "./clickHandler.js": "./clickHandler.js",
+    "./customToolbarButtons": "./customToolbarButtons.js",
+    "./customToolbarButtons.js": "./customToolbarButtons.js",
+    "./drawFence": "./drawFence.js",
+    "./drawFence.js": "./drawFence.js",
+    "./drawFenceNew": "./drawFenceNew.js",
+    "./drawFenceNew.js": "./drawFenceNew.js",
+    "./dronePlannedRoute": "./dronePlannedRoute.js",
+    "./dronePlannedRoute.js": "./dronePlannedRoute.js",
+    "./droneRipple": "./droneRipple.js",
+    "./droneRipple.js": "./droneRipple.js",
+    "./geometry": "./geometry.js",
+    "./geometry.js": "./geometry.js",
+    "./groundLink": "./groundLink.js",
+    "./groundLink.js": "./groundLink.js",
+    "./hemisphere": "./hemisphere.js",
+    "./hemisphere.js": "./hemisphere.js",
+    "./labelDiv": "./labelDiv.js",
+    "./labelDiv.js": "./labelDiv.js",
+    "./movePath": "./movePath.js",
+    "./movePath.js": "./movePath.js",
+    "./movePoint": "./movePoint.js",
+    "./movePoint.js": "./movePoint.js",
+    "./movePointPlannedRoute": "./movePointPlannedRoute.js",
+    "./movePointPlannedRoute.js": "./movePointPlannedRoute.js",
+    "./qrCodeGenerator": "./qrCodeGenerator.js",
+    "./qrCodeGenerator.js": "./qrCodeGenerator.js",
+    "./setPath": "./setPath.js",
+    "./setPath.js": "./setPath.js",
+    "./setPoint": "./setPoint.js",
+    "./setPoint.js": "./setPoint.js",
+    "./tileProviders": "./tileProviders.js",
+    "./tileProviders.js": "./tileProviders.js",
+    "./toolbar/basemapSwitcher": "./toolbar/basemapSwitcher.js",
+    "./toolbar/basemapSwitcher.js": "./toolbar/basemapSwitcher.js",
+    "./toolbar/compass": "./toolbar/compass.js",
+    "./toolbar/compass.js": "./toolbar/compass.js",
+    "./toolbar/fullscreenController": "./toolbar/fullscreenController.js",
+    "./toolbar/fullscreenController.js": "./toolbar/fullscreenController.js",
+    "./toolbar/zoomController": "./toolbar/zoomController.js",
+    "./toolbar/zoomController.js": "./toolbar/zoomController.js",
+    "./stores/mapStore": "./stores/mapStore.js",
+    "./stores/mapStore.js": "./stores/mapStore.js",
+    "./utils/basemapSwitcher": "./utils/basemapSwitcher.js",
+    "./utils/basemapSwitcher.js": "./utils/basemapSwitcher.js",
+    "./utils/mapImagery": "./utils/mapImagery.js",
+    "./utils/mapImagery.js": "./utils/mapImagery.js",
+    "./utils/eventBus": "./utils/eventBus.js",
+    "./utils/useEventBus": "./utils/useEventBus.js",
+    "./utils/getMapCenterPosition": "./utils/getMapCenterPosition.js",
+    "./utils/droneSelection": "./utils/droneSelection.js",
+    "./config": "./config/index.js",
+    "./config/index": "./config/index.js",
+    "./config/hooks": "./config/hooks.js",
+    "./api/gaode": "./api/gaode.js"
+  },
+  "files": [
+    "*.js",
+    "toolbar/**/*.js",
+    "stores/**/*.js",
+    "utils/**/*.js",
+    "config/**/*.js",
+    "api/**/*.js"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-from-source.mjs",
+    "prepublishOnly": "node scripts/verify-files.mjs"
+  },
+  "keywords": [
+    "cesium",
+    "map",
+    "drone",
+    "3d",
+    "gis"
+  ],
+  "author": "huweili <czxyhuweili@163.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "peerDependencies": {
+    "cesium": ">=1.100.0",
+    "mitt": "^3.0.0",
+    "pinia": "^2.0.0 || ^3.0.0",
+    "qrcode": "^1.5.0",
+    "vue": "^3.3.0"
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=18"
+  }
+}

package/utils/basemapSwitcher.js

@@ -0,0 +1,252 @@
+/**
+ * 底图切换器（支持 coexistMap 离线/在线共存）
+ */
+import { applyImageryLayers } from './mapImagery.js'
+
+export const BasemapIds = window.MapConfig?.basemaps?.reduce((acc, item) => {
+  const key = item.id.toUpperCase().replace(/-/g, '_')
+  acc[key] = item.id
+  return acc
+}, {}) || {}
+
+export function createBasemapSwitcher() {
+  let currentBasemapId = null
+
+  const getBasemaps = () => window.MapConfig?.basemaps || []
+  const getBasemapById = (id) => getBasemaps().find((b) => b.id === id)
+
+  const loadBasemap = (viewer, basemapConfig) => {
+    if (!viewer || !basemapConfig) return
+    applyImageryLayers(viewer, window.MapConfig || {}, basemapConfig)
+    currentBasemapId = basemapConfig.id
+    window._currentBasemapId = basemapConfig.id
+  }
+
+  const switchById = (viewer, id) => {
+    const basemap = getBasemapById(id)
+    if (!basemap) {
+      console.error(`Basemap not found with id: ${id}`)
+      return
+    }
+    loadBasemap(viewer, basemap)
+  }
+
+  const toggleSatelliteBasemap = (viewer) => {
+    if (!viewer || !window.MapConfig) return
+
+    if (currentBasemapId === BasemapIds.AMAP_SATELLITE) {
+      const defaultBasemap = getBasemaps().find((b) => b.show)
+      if (defaultBasemap) {
+        loadBasemap(viewer, defaultBasemap)
+      }
+    } else {
+      switchById(viewer, BasemapIds.AMAP_SATELLITE)
+    }
+  }
+
+  const getCurrentBasemapId = () => currentBasemapId
+  const setCurrentBasemapId = (id) => {
+    currentBasemapId = id
+  }
+
+  const toggleBasemapPickerPanel = (viewer, triggerButton) => {
+    if (!viewer?.container) return
+
+    const PANEL_ID = 'cesium-basemap-picker-panel'
+    let panel = document.getElementById(PANEL_ID)
+
+    const syncPanelViewport = () => {
+      if (!panel || panel.style.display === 'none') return
+      const buttonRect = triggerButton?.getBoundingClientRect()
+      if (!buttonRect) return
+
+      const margin = 35
+      const panelRect = panel.getBoundingClientRect()
+      const toolbar = document.querySelector('.cesium-viewer-toolbar')
+      const toolbarRect = toolbar?.getBoundingClientRect()
+
+      let left = (toolbarRect?.left || 0) + (toolbarRect?.width || 0)
+      let top = buttonRect.bottom - panelRect.height
+
+      if (top < 0) top = margin
+      if (top + panelRect.height > window.innerHeight) {
+        top = window.innerHeight - panelRect.height - margin
+      }
+
+      panel.style.position = 'fixed'
+      panel.style.right = 'auto'
+      panel.style.bottom = 'auto'
+      panel.style.top = `${Math.round(top)}px`
+      panel.style.left = `${Math.round(left)}px`
+    }
+
+    const detachOutside = () => {
+      if (panel?._removeOutsideListener) {
+        panel._removeOutsideListener()
+        panel._removeOutsideListener = null
+      }
+      if (panel?._onReposition) {
+        window.removeEventListener('resize', panel._onReposition)
+        window.removeEventListener('scroll', panel._onReposition, true)
+        panel._onReposition = null
+      }
+    }
+
+    const hidePanel = () => {
+      detachOutside()
+      if (panel) panel.style.display = 'none'
+    }
+
+    const isPanelVisible = () => panel && panel.style.display !== 'none'
+
+    if (isPanelVisible()) {
+      hidePanel()
+      return
+    }
+
+    if (!panel) {
+      panel = document.createElement('div')
+      panel.id = PANEL_ID
+      panel.style.cssText = `
+        position: fixed;
+        z-index: 2147483647;
+        min-width: 280px;
+        max-width: 320px;
+        max-height: min(70vh, 500px);
+        overflow-y: auto;
+        overflow-x: hidden;
+        background: rgba(28, 32, 40, 0.94);
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        border-radius: 8px;
+        box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+        display: none;
+        flex-direction: column;
+        padding: 8px;
+        scrollbar-width: thin;
+        scrollbar-color: rgba(255, 255, 255, 0.2) transparent;
+      `
+      const list = document.createElement('div')
+      list.setAttribute('data-role', 'basemap-list')
+      list.style.cssText = 'display: grid; grid-template-columns: repeat(2, 1fr); gap: 8px;'
+      panel.appendChild(list)
+      document.body.appendChild(panel)
+
+      const style = document.createElement('style')
+      style.textContent = `
+        #${PANEL_ID}::-webkit-scrollbar { width: 6px; }
+        #${PANEL_ID}::-webkit-scrollbar-track { background: transparent; }
+        #${PANEL_ID}::-webkit-scrollbar-thumb { background: rgba(255, 255, 255, 0.2); border-radius: 3px; }
+        #${PANEL_ID}::-webkit-scrollbar-thumb:hover { background: rgba(255, 255, 255, 0.35); }
+      `
+      document.head.appendChild(style)
+    }
+
+    const listEl = panel.querySelector('[data-role="basemap-list"]')
+    listEl.innerHTML = ''
+
+    const currentId = getCurrentBasemapId()
+    getBasemaps().forEach((bm) => {
+      const row = document.createElement('button')
+      row.type = 'button'
+      const active = bm.id === currentId
+      row.style.cssText = `
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+        padding: 8px;
+        border: none;
+        background: ${active ? 'rgba(255, 255, 255, 0.1)' : 'transparent'};
+        cursor: pointer;
+        gap: 6px;
+        align-items: center;
+        justify-content: center;
+      `
+
+      const imgContainer = document.createElement('div')
+      imgContainer.style.cssText = `
+        width: 100%;
+        height: 60px;
+        border-radius: 4px;
+        overflow: hidden;
+        border: 2px solid ${active ? '#3B82F6' : 'transparent'};
+        position: relative;
+      `
+      if (bm.customMapColorStyle?.enabled) {
+        imgContainer.style.backgroundColor = bm.customMapColorStyle.MapBaseColor
+      }
+
+      const img = document.createElement('img')
+      img.src = import.meta.env.BASE_URL + bm.thumbnail || ''
+      img.style.cssText = `
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        opacity: ${bm.customMapColorStyle?.enabled ? 0.7 : 1};
+      `
+      img.onerror = function () {
+        this.style.display = 'none'
+      }
+      imgContainer.appendChild(img)
+
+      const nameSpan = document.createElement('span')
+      nameSpan.textContent = bm.name
+      nameSpan.style.cssText = `
+        font-size: 12px;
+        color: #e8eaed;
+        font-weight: ${active ? '600' : '400'};
+        text-align: center;
+      `
+
+      row.appendChild(imgContainer)
+      row.appendChild(nameSpan)
+      row.onmouseenter = () => {
+        row.style.background = 'rgba(255, 255, 255, 0.08)'
+      }
+      row.onmouseleave = () => {
+        row.style.background = active ? 'rgba(255, 255, 255, 0.1)' : 'transparent'
+      }
+      row.onclick = (e) => {
+        e.stopPropagation()
+        switchById(viewer, bm.id)
+        hidePanel()
+      }
+      listEl.appendChild(row)
+    })
+
+    panel.style.display = 'flex'
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => syncPanelViewport())
+    })
+
+    detachOutside()
+    const onReposition = () => syncPanelViewport()
+    panel._onReposition = onReposition
+    window.addEventListener('resize', onReposition)
+    window.addEventListener('scroll', onReposition, true)
+
+    const onOutsidePointer = (e) => {
+      if (!panel || panel.style.display === 'none') return
+      if (panel.contains(e.target)) return
+      if (triggerButton && triggerButton.contains(e.target)) return
+      hidePanel()
+    }
+
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        document.addEventListener('pointerdown', onOutsidePointer, true)
+      })
+    })
+    panel._removeOutsideListener = () =>
+      document.removeEventListener('pointerdown', onOutsidePointer, true)
+  }
+
+  return {
+    switchById,
+    toggleSatelliteBasemap,
+    getBasemaps,
+    getBasemapById,
+    getCurrentBasemapId,
+    setCurrentBasemapId,
+    toggleBasemapPickerPanel,
+  }
+}

package/utils/mapImagery.js

@@ -0,0 +1,135 @@
+/**
+ * 底图与离线共存图层加载
+ */
+import * as Cesium from 'cesium'
+import { customColorTileProvider, hexToRgb } from '../tileProviders.js'
+
+/**
+ * 解析 coexistMap 自定义配色（支持 hex 或已转换的 rgb）
+ * @param {Object} coexistMap
+ * @returns {Object | null}
+ */
+function resolveCoexistColorStyle(coexistMap) {
+  const style = coexistMap?.customMapColorStyle
+  if (!style?.enabled) return null
+
+  return {
+    enabled: true,
+    MapBaseColor:
+      typeof style.MapBaseColor === 'string'
+        ? hexToRgb(style.MapBaseColor)
+        : style.MapBaseColor,
+    RoadLightColor:
+      typeof style.RoadLightColor === 'string'
+        ? hexToRgb(style.RoadLightColor)
+        : style.RoadLightColor,
+  }
+}
+
+/**
+ * @param {Object} basemapConfig
+ * @returns {Cesium.ImageryProvider}
+ */
+export function createBasemapProvider(basemapConfig) {
+  const tileProviderOptions = {
+    url: basemapConfig.url,
+    subdomains: ['1', '2', '3', '4'],
+    maximumLevel: basemapConfig.maximumLevel ?? 18,
+    credit: basemapConfig.name,
+  }
+
+  if (basemapConfig.customMapColorStyle?.enabled) {
+    return new customColorTileProvider(tileProviderOptions, basemapConfig.customMapColorStyle)
+  }
+
+  return new Cesium.UrlTemplateImageryProvider(tileProviderOptions)
+}
+
+/**
+ * 离线瓦片（限定矩形范围，仅在该区域内请求瓦片）
+ * @param {Object} coexistMap mapConfig.coexistMap
+ * @returns {Cesium.ImageryProvider | null}
+ */
+export function createCoexistOfflineProvider(coexistMap) {
+  const offline = coexistMap?.map
+  if (!offline?.url) return null
+
+  const options = {
+    url: offline.url,
+    minimumLevel: offline.minimumLevel ?? 0,
+    maximumLevel: offline.maximumLevel ?? 18,
+    credit: offline.name || '离线地图',
+  }
+
+  const bounds = offline.bounds
+  if (bounds) {
+    options.rectangle = Cesium.Rectangle.fromDegrees(
+      bounds.west,
+      bounds.south,
+      bounds.east,
+      bounds.north,
+    )
+  }
+
+  const colorStyle = resolveCoexistColorStyle(coexistMap)
+  if (colorStyle) {
+    return new customColorTileProvider(options, colorStyle)
+  }
+
+  return new Cesium.UrlTemplateImageryProvider(options)
+}
+
+/**
+ * 解析在线底图：coexist 开启且配置了 mapId 时优先用该底图，否则用 show:true 的底图
+ * @param {Object} mapOptions
+ * @returns {Object | undefined}
+ */
+export function resolveOnlineBasemap(mapOptions) {
+  const basemaps = mapOptions?.basemaps || []
+  const coexist = mapOptions?.coexistMap
+
+  if (coexist?.enabled && coexist.mapId) {
+    const byId = basemaps.find((b) => b.id === coexist.mapId)
+    if (byId) return byId
+  }
+
+  return basemaps.find((b) => b.show === true)
+}
+
+/**
+ * 在线底图（底层，全球）+ 离线底图（顶层，仅 bounds 内加载）
+ * @param {import('cesium').Viewer} viewer
+ * @param {Object} mapOptions
+ * @param {Object} basemapConfig
+ * @returns {{ onlineLayer: Cesium.ImageryLayer, offlineLayer: Cesium.ImageryLayer | null }}
+ */
+export function applyImageryLayers(viewer, mapOptions, basemapConfig) {
+  viewer.imageryLayers.removeAll()
+
+  const onlineLayer = new Cesium.ImageryLayer(createBasemapProvider(basemapConfig))
+  viewer.imageryLayers.add(onlineLayer)
+
+  let offlineLayer = null
+  const coexist = mapOptions?.coexistMap
+  if (coexist?.enabled) {
+    const offlineProvider = createCoexistOfflineProvider(coexist)
+    if (offlineProvider) {
+      offlineLayer = new Cesium.ImageryLayer(offlineProvider)
+      viewer.imageryLayers.add(offlineLayer)
+      console.log(
+        `离线共存已启用：${coexist.map?.name}，范围外使用在线底图「${basemapConfig.name}」`,
+      )
+    }
+  }
+
+  return { onlineLayer, offlineLayer }
+}
+
+/**
+ * 底图切换后重新叠加离线层（仅替换在线层，保留离线层逻辑：先清再全量加载）
+ */
+export function switchBasemapWithCoexist(viewer, mapOptions, basemapConfig) {
+  const layers = applyImageryLayers(viewer, mapOptions, basemapConfig)
+  window._currentBasemapId = basemapConfig.id
+  return layers
+}