useCameraState

响应式获取 Camera 的状态（位置、方向、heading/pitch/roll、层级等）。相机由 Cesium 内部渲染循环驱动，直接读 viewer.camera.position 不会触发 Vue 更新；本 hook 监听相机事件（默认 changed）、节流（默认 8ms）同步为响应式数据并随动画更新，适合绑定到 UI（如坐标面板）或据此驱动其他逻辑。

Usage

<script setup lang="ts">
import { useCameraState } from 'vesium';

const {
  position,
  direction,
  up,
  right,
  positionCartographic,
  positionWC,
  directionWC,
  upWC,
  rightWC,
  viewRectangle,
  heading,
  pitch,
  roll,
  level,
} = useCameraState();
</script>

<template>
  <div class="p-10px flex flex-col gap-y-10px h-250px overflow-scroll">
    <pre> {{ { position, direction, up, right, positionCartographic, positionWC, directionWC, upWC, rightWC, viewRectangle, heading, pitch, roll, level } }}</pre>
  </div>
</template>

import { useCameraState } from 'vesium';

const { position, heading, pitch, roll, level } = useCameraState();

配置项

• camera - 要监听的相机，默认 useViewer().value.scene.camera。
• event - 监听的事件：changed | moveStart | moveEnd，默认 changed。
• delay - 节流延迟（毫秒），默认 8。

返回值

• position - 相机位置（世界坐标，克隆值）。
• heading / pitch / roll - 相机航向角 / 俯仰角 / 翻滚角（弧度）。
• level - 相机中心层级（由高度估算）。
• 其余字段（direction、positionCartographic、viewRectangle 等）见下方类型定义。

注意事项

• 默认相机来自 useViewer()，使用前需先调用 createViewer。
• 状态按节流同步（默认 8ms），不保证逐帧精确；返回的向量/坐标是克隆值，修改不影响相机内部状态。
• positionCartographic 经纬度为弧度（2D / 哥伦布视图下可能超出合法范围）；level 由经验公式估算，非 Cesium 官方 API。

Type Definitions

import type { Camera, Cartesian3, Cartographic, Rectangle } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter } from 'vue';
export interface UseCameraStateOptions {
    /**
     * The camera to use
     * @default useViewer().value.scene.camera
     */
    camera?: MaybeRefOrGetter<Camera | undefined>;
    /**
     * Camera event type to watch
     * @default `changed`
     */
    event?: MaybeRefOrGetter<'changed' | 'moveStart' | 'moveEnd'>;
    /**
     * Throttled delay duration (ms)
     * @default 8
     */
    delay?: number;
}
export interface UseCameraStateReturn {
    /**
     * The camera
     */
    camera: ComputedRef<Camera | undefined>;
    /**
     * The position of the camera
     */
    position: ComputedRef<Cartesian3 | undefined>;
    /**
     * The view direction of the camera
     */
    direction: ComputedRef<Cartesian3 | undefined>;
    /**
     * The up direction of the camera
     */
    up: ComputedRef<Cartesian3 | undefined>;
    /**
     * The right direction of the camera
     */
    right: ComputedRef<Cartesian3 | undefined>;
    /**
     * Gets the {@link Cartographic} position of the camera, with longitude and latitude
     * expressed in radians and height in meters.  In 2D and Columbus View, it is possible
     * for the returned longitude and latitude to be outside the range of valid longitudes
     * and latitudes when the camera is outside the map.
     */
    positionCartographic: ComputedRef<Cartographic | undefined>;
    /**
     * Gets the position of the camera in world coordinates
     */
    positionWC: ComputedRef<Cartesian3 | undefined>;
    /**
     * Gets the view direction of the camera in world coordinates
     */
    directionWC: ComputedRef<Cartesian3 | undefined>;
    /**
     * Gets the up direction of the camera in world coordinates
     */
    upWC: ComputedRef<Cartesian3 | undefined>;
    /**
     * Gets the right direction of the camera in world coordinates
     */
    rightWC: ComputedRef<Cartesian3 | undefined>;
    /**
     * Computes the approximate visible rectangle on the ellipsoid
     */
    viewRectangle: ComputedRef<Rectangle | undefined>;
    /**
     * Gets the camera heading in radians
     */
    heading: ComputedRef<number | undefined>;
    /**
     * Gets the camera pitch in radians
     */
    pitch: ComputedRef<number | undefined>;
    /**
     * Gets the camera roll in radians
     */
    roll: ComputedRef<number | undefined>;
    /**
     * Gets the camera center hierarchy level
     */
    level: ComputedRef<number | undefined>;
}
/**
 *  Reactive Cesium Camera state
 * @param options options
 * @returns Reactive camera states
 */
export declare function useCameraState(options?: UseCameraStateOptions): UseCameraStateReturn;