huweili-cesium 1.2.87 → 1.2.88

package/index.vue

@@ -16,6 +16,14 @@ 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 {
+  ensureTerrainConfig,
+  resolveTerrainConfig,
+  createTerrainProvider,
+  applyTerrain,
+  isTerrainEnabled,
+  syncTerrainConfig,
+} from './js/utils/terrainProvider.js'
 import { createCustomToolbarButtons } from './js/customToolbarButtons.js'
 const { merge } = objectUtils()
 const { mouseController, setInitialCameraView, syncCameraInteractionMode } = basicConfig()
@@ -89,6 +97,24 @@ const handleSceneModeChange = ({ mapId, sceneMode }) => {
   syncCameraInteractionMode(map, mapId, sceneMode)
 }
 
+/**
+ * 处理地形开关变化（地图外 UI 通过事件总线触发）
+ *
+ * 用法示例（宿主页面）：
+ * emit('map-terrain-changed', { mapId: 'home-main-map', show: true })
+ * emit('map-terrain-changed', { mapId: 'home-main-map', url: '/terrain' })
+ *
+ * @param {Object} param
+ * @param {string} param.mapId - 地图实例 ID
+ * @param {boolean} [param.show] - 是否启用地形
+ * @param {string} [param.url] - 地形服务地址（离线数据替换此 url 即可）
+ */
+const handleTerrainChange = async ({ mapId, show, url }) => {
+  if (mapId !== props.mapId || !map || map.isDestroyed?.()) return
+  await syncTerrainConfig(map, MapConfig, { show, url })
+  map.render()
+}
+
 const cesiumContainer = ref(null)
 let map = null
 let customButtons = []
@@ -151,6 +177,7 @@ const initCesium = async () => {
 
   if (mapOptions) {
     mapOptions = processMapConfigColors(mapOptions)
+    ensureTerrainConfig(mapOptions)
   }
 
   try {
@@ -169,12 +196,16 @@ const initCesium = async () => {
       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,
+      terrainProvider: await (async () => {
+        const terrainConfig = resolveTerrainConfig(mapOptions)
+        if (!terrainConfig.show) return undefined
+        try {
+          return await createTerrainProvider(terrainConfig)
+        } catch (error) {
+          console.error('初始地形加载失败，将使用默认椭球地形:', error)
+          return undefined
+        }
+      })(),
       terrainShadows: Cesium.ShadowMode.RECEIVE_ONLY, // 地形只接收阴影，不投射，节省性能
       creditContainer: document.createElement('div'), // 用空容器替换默认版权水印区域
     }
@@ -228,6 +259,15 @@ const initCesium = async () => {
       console.warn('未找到可用底图，Cesium 将使用默认底图或空底图显示')
     }
 
+    const terrainConfig = resolveTerrainConfig(mapOptions)
+    if (terrainConfig.show) {
+      if (isTerrainEnabled(map)) {
+        console.log(`地形已启用，URL：${terrainConfig.url}`)
+      } else {
+        console.warn(`地形开关已开启但未加载成功，请检查 mapConfig.terrain.url：${terrainConfig.url}`)
+      }
+    }
+
     if (map.screenSpaceEventHandler && mapOptions.control.disableDoubleClick) {
       // 移除双击左键事件，防止地图缩放
       map.screenSpaceEventHandler.removeInputAction(Cesium.ScreenSpaceEventType.LEFT_DOUBLE_CLICK)
@@ -277,6 +317,25 @@ const initCesium = async () => {
         removeToolbarButtons, // 移除工具栏按钮
       },
       syncCameraInteractionMode: (mode) => syncCameraInteractionMode(map, props.mapId, mode), // 同步相机交互模式
+      terrain: {
+        getEnabled: () => isTerrainEnabled(map),
+        getConfig: () => resolveTerrainConfig(mapOptions),
+        setEnabled: async (show) => {
+          await syncTerrainConfig(map, MapConfig, { show })
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+        setUrl: async (url) => {
+          await syncTerrainConfig(map, MapConfig, { url, show: true })
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+        apply: async (config = {}) => {
+          await syncTerrainConfig(map, MapConfig, config)
+          map?.render()
+          return isTerrainEnabled(map)
+        },
+      },
     })
 
     map.resize() // 调整地图尺寸
@@ -414,6 +473,7 @@ onMounted(() => {
   mapStore.setCurrentMapId(props.mapId) // 初始化当前地图ID
   setupActivityListeners() // 初始化用户活动监听器，用于判断是否需要继续渲染地图，避免空闲超时导致的渲染暂停
   onEvent('map-scene-mode-changed', handleSceneModeChange) // 监听场景模式变化事件，用于同步相机交互模式
+  onEvent('map-terrain-changed', handleTerrainChange) // 监听地形开关变化（地图外 UI 控制）
   initCesium() // 初始化 Cesium 地图实例
 })
 
@@ -439,6 +499,7 @@ onUnmounted(() => {
   isMapActive = false
   stopRenderLoop() // 停止持续渲染循环，释放资源
   offEvent('map-scene-mode-changed', handleSceneModeChange) // 移除场景模式变化事件监听器
+  offEvent('map-terrain-changed', handleTerrainChange) // 移除地形开关变化事件监听器
   if (map) {
     teardownOrthographicWheelZoom(map) // 移除正交投影滚轮缩放事件监听器
   }

package/js/index.js

@@ -58,3 +58,13 @@ export {
 export { getAddressByLocation, setGeocodeProvider } from './api/gaode.js'
 
 export { objectUtils } from './utils/cesium/object.js'
+
+export {
+  DEFAULT_TERRAIN_CONFIG,
+  resolveTerrainConfig,
+  ensureTerrainConfig,
+  createTerrainProvider,
+  applyTerrain,
+  isTerrainEnabled,
+  syncTerrainConfig,
+} from './utils/terrainProvider.js'

package/js/utils/terrainProvider.js

@@ -0,0 +1,125 @@
+/**
+ * 地形服务加载与切换（支持 mapConfig.terrain 配置及地图外开关）
+ */
+import * as Cesium from 'cesium'
+
+/** mapConfig.terrain 缺省时的默认值（show 仅在为 undefined 时生效） */
+export const DEFAULT_TERRAIN_CONFIG = {
+  show: true,
+  url: 'https://data.mars3d.cn/terrain',
+  coastlineData: false,
+  lightingData: false,
+}
+
+/**
+ * 解析地形配置（合并 mapConfig.terrain 与默认值）
+ * @param {Object} mapOptions
+ * @returns {{ show: boolean, url: string, coastlineData: boolean, lightingData: boolean }}
+ */
+export function resolveTerrainConfig(mapOptions) {
+  const terrain = mapOptions?.terrain || {}
+  return {
+    show: terrain.show ?? DEFAULT_TERRAIN_CONFIG.show,
+    url: terrain.url ?? DEFAULT_TERRAIN_CONFIG.url,
+    coastlineData: terrain.coastlineData ?? DEFAULT_TERRAIN_CONFIG.coastlineData,
+    lightingData: terrain.lightingData ?? DEFAULT_TERRAIN_CONFIG.lightingData,
+  }
+}
+
+/**
+ * 补全 mapOptions.terrain，避免宿主未配置时无法加载
+ * @param {Object} mapOptions
+ */
+export function ensureTerrainConfig(mapOptions) {
+  if (!mapOptions) return mapOptions
+  if (!mapOptions.terrain) {
+    mapOptions.terrain = { ...DEFAULT_TERRAIN_CONFIG }
+    return mapOptions
+  }
+  const resolved = resolveTerrainConfig(mapOptions)
+  mapOptions.terrain = { ...mapOptions.terrain, ...resolved }
+  return mapOptions
+}
+
+/**
+ * 创建 Cesium 地形 Provider
+ * @param {Object} terrainConfig
+ * @returns {Promise<Cesium.CesiumTerrainProvider|undefined>}
+ */
+export async function createTerrainProvider(terrainConfig) {
+  const config = resolveTerrainConfig({ terrain: terrainConfig })
+  if (!config.show || !config.url) return undefined
+
+  return Cesium.CesiumTerrainProvider.fromUrl(config.url, {
+    requestWaterMask: !!config.coastlineData,
+    requestVertexNormals: !!config.lightingData,
+  })
+}
+
+/**
+ * 将地形应用到 Viewer（关闭时使用椭球地形）
+ * @param {Cesium.Viewer} viewer
+ * @param {Object} terrainConfig
+ * @returns {Promise<boolean>} 是否成功加载真实地形
+ */
+export async function applyTerrain(viewer, terrainConfig) {
+  if (!viewer || viewer.isDestroyed?.()) return false
+
+  const config = resolveTerrainConfig({ terrain: terrainConfig })
+
+  if (!config.show) {
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+
+  if (!config.url) {
+    console.warn('地形已开启但未配置 url，请在 mapConfig.js 的 terrain.url 中设置地形服务地址')
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+
+  try {
+    const provider = await createTerrainProvider(config)
+    viewer.terrainProvider = provider
+    viewer.scene?.requestRender?.()
+    console.log(`地形已加载：${config.url}`)
+    return true
+  } catch (error) {
+    console.error('地形加载失败，将使用默认椭球地形:', error)
+    viewer.terrainProvider = new Cesium.EllipsoidTerrainProvider()
+    viewer.scene?.requestRender?.()
+    return false
+  }
+}
+
+/**
+ * 当前 Viewer 是否在使用真实地形（非椭球）
+ * @param {Cesium.Viewer} viewer
+ */
+export function isTerrainEnabled(viewer) {
+  if (!viewer?.terrainProvider) return false
+  return !(viewer.terrainProvider instanceof Cesium.EllipsoidTerrainProvider)
+}
+
+/**
+ * 同步 mapConfig.terrain 并应用到 Viewer
+ * @param {Cesium.Viewer} viewer
+ * @param {Object} mapConfig - 通常为 window.MapConfig / MapConfig
+ * @param {{ show?: boolean, url?: string }} patch
+ */
+export async function syncTerrainConfig(viewer, mapConfig, patch = {}) {
+  if (!mapConfig) {
+    return applyTerrain(viewer, patch)
+  }
+
+  if (!mapConfig.terrain) {
+    mapConfig.terrain = { ...DEFAULT_TERRAIN_CONFIG }
+  }
+
+  if (patch.show !== undefined) mapConfig.terrain.show = patch.show
+  if (patch.url !== undefined) mapConfig.terrain.url = patch.url
+
+  return applyTerrain(viewer, mapConfig.terrain)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huweili-cesium",
-  "version": "1.2.87",
+  "version": "1.2.88",
   "description": "基于 Cesium 的地图工具库（无人机态势、轨迹、围栏、工具栏等）",
   "type": "module",
   "main": "./index.js",
@@ -81,6 +81,8 @@
     "./utils/basemapSwitcher.js": "./js/utils/basemapSwitcher.js",
     "./utils/mapImagery": "./js/utils/mapImagery.js",
     "./utils/mapImagery.js": "./js/utils/mapImagery.js",
+    "./utils/terrainProvider": "./js/utils/terrainProvider.js",
+    "./utils/terrainProvider.js": "./js/utils/terrainProvider.js",
     "./utils/eventBus": "./js/utils/eventBus.js",
     "./utils/eventBus.js": "./js/utils/eventBus.js",
     "./utils/useEventBus": "./js/utils/useEventBus.js",