huweili-cesium 1.1.21 → 1.2.1

package/README.md

@@ -172,10 +172,10 @@ npm run sync
 | `public/config/constants.js` | `window.MapInstanceIds` 定义多地图 ID（如 `HOME: 'home-main-map'`） | `:map-id` 须与之一致，工具栏回调里的 `mapId` 也要传同一个值 |
 | `public/config/mapConfig.js` | `window.MapConfig`（中心点、2D/3D、底图列表、是否显示 Cesium 自带控件等） | 控制地图初始化；`control.homeButton: false` 时由自定义工具栏替代 |
 
-在页面中引用常量（推荐）：
+在页面中引用常量（从 `runtimeConfig` 导入）：
 
 ```js
-import { MapInstanceIds } from '@/main'
+import { MapInstanceIds } from '@/config/runtimeConfig'
 
 const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
 ```
@@ -195,7 +195,7 @@ const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'
 
 <script setup>
 import CesiumMap from 'huweili-cesium'
-import { MapInstanceIds } from '@/main'
+import { MapInstanceIds } from '@/config/runtimeConfig'
 import { getHomeToolbarButtons } from '@/utils/homeToolbarButtons'
 
 const HOME_MAP_ID = MapInstanceIds?.HOME || 'home-main-map'

package/index.vue

@@ -18,59 +18,7 @@ import { applyImageryLayers, resolveOnlineBasemap } from './js/utils/mapImagery'
 import { createCustomToolbarButtons } from './js/customToolbarButtons'
 
 const { merge } = objectUtils()
-const { mouseController } = basicConfig()
-
-/**
- * 设置 Cesium 地图的初始相机视角
- * 
- * 功能说明：
- * - 根据传入的中心点坐标（经纬度）和视角参数（高度、航向、俯仰、翻滚）
- * - 将相机移动到指定位置并设置朝向
- * - 用于地图初始化时设置默认视角位置
- * 
- * @param {Cesium.Viewer} viewer - Cesium 地图实例
- * @param {Object} center - 中心点配置对象
- * @param {number} center.lng - 中心点经度（度），默认 0
- * @param {number} center.lat - 中心点纬度（度），默认 0
- * @param {number} center.alt - 相机高度（米），默认 10000
- * @param {number} center.heading - 航向角（度），0=正北，90=正东，默认 0
- * @param {number} center.pitch - 俯仰角（度），-90=正下方，0=水平，默认 -90
- * @param {number} center.roll - 翻滚角（度），默认 0
- * 
- * 使用示例：
- * setInitialCameraView(viewer, {
- *   lng: 116.4074,   // 北京经度
- *   lat: 39.9042,    // 北京纬度
- *   alt: 10000,       // 高度 10km
- *   heading: 0,       // 朝向正北
- *   pitch: -35,      // 俯视 35 度
- *   roll: 0          // 不翻滚
- * })
- */
-function setInitialCameraView(viewer, center = {}) {
-  // 安全检查：确保 viewer 和 camera 对象存在
-  if (!viewer?.camera) return
-
-  // 从 center 对象中提取参数，使用默认值确保容错性
-  const lng = Number(center.lng) || 0        // 经度，默认 0°
-  const lat = Number(center.lat) || 0        // 纬度，默认 0°
-  const alt = Number(center.alt) || 10000     // 高度，默认 10000 米
-  const heading = Cesium.Math.toRadians(Number(center.heading) || 0)  // 航向角 → 弧度
-  const pitch = Cesium.Math.toRadians(-90)    // 俯仰角，固定 -90°（垂直俯视）
-  const roll = Cesium.Math.toRadians(Number(center.roll) || 0)        // 翻滚角 → 弧度
-
-  // 设置相机视角
-  viewer.camera.setView({
-    // 相机目标位置：使用经纬度坐标和高度创建 Cartesian3 坐标
-    destination: Cesium.Cartesian3.fromDegrees(lng, lat, alt),
-    // 相机朝向：通过 heading、pitch、roll 三个角度定义
-    orientation: {
-      heading,  // 航向角：绕垂直轴旋转（0=北，90=东，180=南，270=西）
-      pitch,    // 俯仰角：绕水平轴旋转（-90=正下方，0=水平，90=正上方）
-      roll,     // 翻滚角：绕相机朝向轴旋转
-    },
-  })
-}
+const { mouseController, setInitialCameraView } = basicConfig()
 
 const {
   addToolbarButton,
@@ -367,6 +315,19 @@ function startContinuousRendering(viewer) {
   animate()
 }
 
+/**
+ * 停止持续渲染循环
+ * 
+ * 功能说明：
+ * - 取消 requestAnimationFrame 创建的动画帧请求
+ * - 清空 animationId，防止重复取消
+ * - 用于页面失活、组件卸载或需要暂停渲染时释放资源
+ * 
+ * 使用场景：
+ * - 页面被 keep-alive 缓存时（onDeactivated）
+ * - 组件卸载时（onUnmounted）
+ * - 手动暂停地图渲染以节省性能时
+ */
 function stopRenderLoop() {
   if (animationId) {
     cancelAnimationFrame(animationId)
@@ -384,6 +345,18 @@ function setupActivityListeners() {
   })
 }
 
+/**
+ * 从缓存中恢复地图渲染（用于 keep-alive 场景）
+ * 
+ * 功能说明：
+ * - 当页面被 keep-alive 缓存后再次激活时，恢复 Cesium 地图的渲染状态
+ * - 重新设置当前地图 ID、激活状态和最后活跃时间
+ * - 在下一个 tick 中调整地图大小、触发渲染并重启持续渲染循环
+ * 
+ * 使用场景：
+ * - Vue 路由中使用 keep-alive 缓存包含地图的组件，切换回该页面时调用
+ * - 在 onActivated 生命周期钩子中触发
+ */
 function resumeMapAfterCache() {
   if (!map || map.isDestroyed?.()) return
   mapStore.setCurrentMapId(props.mapId)
@@ -397,12 +370,36 @@ function resumeMapAfterCache() {
   })
 }
 
+/**
+ * 组件挂载钩子（首次加载时触发）
+ * 
+ * 触发时机：
+ * - 组件首次挂载到 DOM 时
+ * - 无论是否使用 keep-alive，首次加载都会触发
+ * 
+ * 功能说明：
+ * - 设置当前地图 ID
+ * - 监听用户活动事件
+ * - 初始化 Cesium 地图
+ */
 onMounted(() => {
   mapStore.setCurrentMapId(props.mapId)
   setupActivityListeners()
   initCesium()
 })
 
+/**
+ * keep-alive 组件激活钩子（从缓存中恢复时触发）
+ * 
+ * 触发时机：
+ * - 当前组件被 keep-alive 包裹，用户导航回到该页面时
+ * - 组件从缓存状态恢复到活动状态
+ * 
+ * 功能说明：
+ * - 重新设置当前地图 ID
+ * - 如果地图已销毁，重新初始化地图
+ * - 如果地图还在缓存中，恢复地图渲染
+ */
 onActivated(() => {
   mapStore.setCurrentMapId(props.mapId)
   if (!map || map.isDestroyed?.()) {
@@ -413,11 +410,39 @@ onActivated(() => {
   resumeMapAfterCache()
 })
 
+/**
+ * keep-alive 组件失活钩子（页面被缓存时触发）
+ * 
+ * 触发时机：
+ * - 当前组件被 keep-alive 包裹，用户导航离开该页面时
+ * - 组件进入缓存状态，但不会被销毁
+ * 
+ * 功能说明：
+ * - 标记地图为非活跃状态
+ * - 停止持续渲染循环，节省 CPU 资源
+ * 
+ * 与 onUnmounted 的区别：
+ * - onDeactivated：组件被缓存，可通过 onActivated 恢复
+ * - onUnmounted：组件被销毁，需要完全清理资源
+ */
 onDeactivated(() => {
   isMapActive = false
   stopRenderLoop()
 })
 
+/**
+ * 组件卸载钩子（完全销毁时触发）
+ * 
+ * 触发时机：
+ * - 组件被完全移除时
+ * - 路由切换且未使用 keep-alive 缓存时
+ * 
+ * 功能说明：
+ * - 停止渲染循环
+ * - 移除自定义工具栏按钮
+ * - 销毁 Cesium Viewer 实例释放内存
+ * - 从 store 中移除地图实例
+ */
 onUnmounted(() => {
   isMapActive = false
   stopRenderLoop()

package/js/basis.js

@@ -44,6 +44,58 @@ export function basicConfig() {
     map.clock.shouldAnimate = true
   }
 
+  /**
+   * 设置 Cesium 地图的初始相机视角
+   * 
+   * 功能说明：
+   * - 根据传入的中心点坐标（经纬度）和视角参数（高度、航向、俯仰、翻滚）
+   * - 将相机移动到指定位置并设置朝向
+   * - 用于地图初始化时设置默认视角位置
+   * 
+   * @param {Cesium.Viewer} viewer - Cesium 地图实例
+   * @param {Object} center - 中心点配置对象
+   * @param {number} center.lng - 中心点经度（度），默认 0
+   * @param {number} center.lat - 中心点纬度（度），默认 0
+   * @param {number} center.alt - 相机高度（米），默认 10000
+   * @param {number} center.heading - 航向角（度），0=正北，90=正东，默认 0
+   * @param {number} center.pitch - 俯仰角（度），-90=正下方，0=水平，默认 -90
+   * @param {number} center.roll - 翻滚角（度），默认 0
+   * 
+   * 使用示例：
+   * setInitialCameraView(viewer, {
+   *   lng: 116.4074,   // 北京经度
+   *   lat: 39.9042,    // 北京纬度
+   *   alt: 10000,       // 高度 10km
+   *   heading: 0,       // 朝向正北
+   *   pitch: -35,      // 俯视 35 度
+   *   roll: 0          // 不翻滚
+   * })
+   */
+  const setInitialCameraView = (viewer, center = {}) => {
+    // 安全检查：确保 viewer 和 camera 对象存在
+    if (!viewer?.camera) return
+
+    // 从 center 对象中提取参数，使用默认值确保容错性
+    const lng = Number(center.lng) || 0        // 经度，默认 0°
+    const lat = Number(center.lat) || 0        // 纬度，默认 0°
+    const alt = Number(center.alt) || 10000     // 高度，默认 10000 米
+    const heading = Cesium.Math.toRadians(Number(center.heading) || 0)  // 航向角 → 弧度
+    const pitch = Cesium.Math.toRadians(-90)    // 俯仰角，固定 -90°（垂直俯视）
+    const roll = Cesium.Math.toRadians(Number(center.roll) || 0)        // 翻滚角 → 弧度
+
+    // 设置相机视角
+    viewer.camera.setView({
+      // 相机目标位置：使用经纬度坐标和高度创建 Cartesian3 坐标
+      destination: Cesium.Cartesian3.fromDegrees(lng, lat, alt),
+      // 相机朝向：通过 heading、pitch、roll 三个角度定义
+      orientation: {
+        heading,  // 航向角：绕垂直轴旋转（0=北，90=东，180=南，270=西）
+        pitch,    // 俯仰角：绕水平轴旋转（-90=正下方，0=水平，90=正上方）
+        roll,     // 翻滚角：绕相机朝向轴旋转
+      },
+    })
+  }
+
   /**
    * 鼠标事件控制器
    * 
@@ -617,6 +669,7 @@ export function basicConfig() {
     set2DView,
     set3DView,
     applyOrthographicFrustum,
-    restorePerspectiveFrustum
+    restorePerspectiveFrustum,
+    setInitialCameraView
   }
 }

package/package.json

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