NEXA - 文档

Appearance

位置信息状态栏 ​

在 Viewer 容器底部挂载一条半透明状态栏，实时显示鼠标经纬高（经度 / 纬度 / 高度） 与相机姿态（方向 / 俯仰角 / 视高），适合大屏 / 监控台与 GIS 工具箱的坐标拾取辅助。

能力定位 ​

PositionInfoStatusBar 适合：

  • 大屏 / 监控台：实时展示当前指针坐标与相机姿态，无需手动查询；
  • 坐标拾取辅助：移动鼠标即可读取地表经纬高，与 MouseEvents 回调互补（本控件自带 UI）；
  • 调试辅助：拖动相机时实时看到方向 / 俯仰角 / 视高变化。

与 MouseEvents（纯事件回调）不同：PositionInfoStatusBar 是自带 DOM 状态栏的控件， on(viewer) 后即挂载并自动更新，hide/show 可临时显隐，off/destroy 完整清理。

构造函数 ​

ts
constructor(options?: PositionInfoStatusBarOptions)
ts
interface PositionInfoStatusBarOptions {
  showCameraInfo?: boolean // 是否显示相机信息（方向 / 俯仰角 / 视高），默认 true
}
参数类型默认值描述
showCameraInfobooleantruefalse 时只显示鼠标经纬高 3 个字段，不挂相机字段

生命周期 ​

实现 Lifecycle<Viewer> 契约，on/off/destroy 均幂等：

ts
on(viewer: Viewer): void      // 挂载状态栏 DOM + 订阅鼠标移动与相机 moveEnd
off(viewer: Viewer): void     // 移除监听 + 销毁事件处理器 + 移除 DOM（幂等，可再次 on）
destroy(viewer: Viewer): void // 等价于 off（幂等）

清理完整性：本类只拥有自身创建的 DOM 状态栏、ScreenSpaceEventHandler 与 camera.moveEnd 监听器，off/destroy 一并移除，不触碰调用方其他资源。

基础示例 ​

ts
import { PositionInfoStatusBar } from '@nexa/gis-cesium'

const statusBar = new PositionInfoStatusBar({ showCameraInfo: true })
statusBar.on(viewer) // 挂载状态栏并开始实时更新

statusBar.hide() // 临时隐藏
statusBar.show() // 重新显示

// 页面或场景退出时统一清理（幂等）
statusBar.destroy(viewer)

进阶示例 ​

只显示鼠标经纬高（不显示相机信息）：

ts
const statusBar = new PositionInfoStatusBar({ showCameraInfo: false })
statusBar.on(viewer)

实现说明 ​

  • 经纬高更新：鼠标移动时通过 scene.pickPosition（环境不支持深度回读或未命中时回退 camera.pickEllipsoid）拾取地面位置，转 Cartographic 后显示经度 / 纬度 / 高度。
  • 相机姿态更新：监听 camera.moveEnd，读取 heading / pitch 与视点高度显示方向 / 俯仰角 / 视高。
  • 源案例缺陷修复：源实现（Scene/PositionInfoStatusBar）缺少销毁逻辑（事件处理器与 DOM 均不清理）；本实现以 Lifecycle 幂等 on/off/destroy 补齐清理。
  • 公共 API：仅使用 Cesium 公共 ScreenSpaceEventHandler、scene.pickPosition、 scene.pickPositionSupported、camera.pickEllipsoid、camera.moveEnd 与 Cartographic， 不触碰私有字段。
  • 无外部依赖：源案例的 3dtiles 加载 / 外网底图 / OL 地图联动等 demo 编排迁移时剥离， 使用 SDK 默认底图与示例区域视角。

清理责任 ​

ts
statusBar.destroy(viewer) // 或 statusBar.off(viewer)，等价且幂等

重复调用 destroy/off 安全（未 on 时为空操作）。销毁后重新 on 可再次挂载。

Cesium 版本限制 ​

  • 依赖 Cesium 公共 ScreenSpaceEventHandler / Scene.pickPosition / pickPositionSupported / Camera.pickEllipsoid / Camera.moveEnd / Cartographic；
  • 已验证目标版本：Cesium 1.133.1。