useScaleBar

响应式生成 Cesium 比例尺数据：单像素距离、比例尺宽度、格式化的距离文本。手动画比例尺需自行计算像素距离并在相机移动、画布变化时重算；本 hook 通过拾取画布底边中心相邻像素的地面点计算像素距离，从固定档位表选出刻度，相机移动或画布缩放时自动（节流）重算，适合叠加在画布角落的常规比例尺 UI。

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useScaleBar, useViewer } from 'vesium';
import { watchEffect } from 'vue';

const viewer = useViewer();
watchEffect(() => {
  viewer.value?.camera.flyTo({
    destination: Cesium.Cartesian3.fromDegrees(100, 0, 10000),
    duration: 3,

  });
});
const { pixelDistance, width, distance, distanceText } = useScaleBar();
</script>

<template>
  <div class="p-10px flex flex-col w-200px">
    <div>pixelDistance: {{ pixelDistance?.toFixed(2) }}m</div>
    <div>distance: {{ distance }}m</div>
    <div class="border-b-2px border-b-#666" :style="{ width: `${width}px` }">
      {{ distanceText }}
    </div>
  </div>
</template>

import { useScaleBar } from 'vesium';

// maxPixel 控制比例尺最大像素宽度（默认 80px）
const { pixelDistance, width, distance, distanceText } = useScaleBar({ maxPixel: 80 });

配置项

• maxPixel - 比例尺的最大像素宽度（px），默认 80。
• delay - 相机事件触发重算的节流延迟（毫秒），默认 8。

返回值

• pixelDistance - 当前画布中单个像素对应的实际距离（米）。
• width - 比例尺宽度（像素）。
• distance - 比例尺宽度对应的实际距离（米）。
• distanceText - 距离的格式化文本，如 100m、100km。

注意事项

• 依赖 useViewer()，使用前需先调用 createViewer。
• 距离经 globe.pick 拾取地面计算：相机朝向无地面交点（如朝向天空）时保留上一次计算的值；从未成功拾取过时才为 undefined。
• distanceText 超过 1000m 时以 km 显示。

Type Definitions

import type { MaybeRefOrGetter, Ref } from 'vue';
export interface UseScaleBarOptions {
    /**
     * The maximum width of the scale (px)
     * @default 80
     */
    maxPixel?: MaybeRefOrGetter<number>;
    /**
     * Throttled delay duration (ms)
     * @default 8
     */
    delay?: number;
}
export interface UseScaleBarReturn {
    /**
     * The actual distance of a single pixel in the current canvas
     */
    pixelDistance: Readonly<Ref<number | undefined>>;
    /**
     * The width of the scale.(px)
     */
    width: Readonly<Ref<number>>;
    /**
     * The actual distance corresponding to the width of the scale (m)
     */
    distance: Readonly<Ref<number | undefined>>;
    /**
     * Formatted content of distance.
     * eg. 100m,100km
     */
    distanceText: Readonly<Ref<string | undefined>>;
}
/**
 * Reactive generation of scale bars
 */
export declare function useScaleBar(options?: UseScaleBarOptions): UseScaleBarReturn;