useScreenSpaceEventHandler

以响应式方式使用 Cesium 的 ScreenSpaceEventHandler 处理鼠标/触摸屏幕事件：canvas 变化时自动重建处理器，事件类型或修饰键变化时自动重新注册监听，组件卸载时自动销毁。适合监听点击、移动、滚轮、双指手势等事件，事件类型可动态变化。

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useScreenSpaceEventHandler } from 'vesium';
import { ref } from 'vue';

const coord = ref<Record<any, any>>({});

Object.values(Cesium.ScreenSpaceEventType).forEach((type: any) => {
  useScreenSpaceEventHandler(type, (ctx: any) => coord.value[type] = JSON.stringify(ctx));
});
</script>

<template>
  <div class="p-10px bg-[var(--vp-c-bg)] flex flex-col gap-5px w-200px">
    <span v-for="(value, key) in Cesium.ScreenSpaceEventType" :key="key">
      {{ key }} : {{ coord[value] || '--' }}
    </span>
  </div>
</template>

import * as Cesium from 'cesium';
import { useScreenSpaceEventHandler } from 'vesium';

const stop = useScreenSpaceEventHandler(
  Cesium.ScreenSpaceEventType.LEFT_CLICK,
  (event) => {
    console.log(event.position); // 定位事件的回调含屏幕坐标 position
  },
  { modifier: Cesium.KeyboardEventModifier.SHIFT }, // 按住 Shift 才触发
);

stop(); // 组件卸载时自动清理，也可手动停止

配置项

• type - 事件类型（Cesium.ScreenSpaceEventType），支持 ref/getter 动态变化；回调参数类型随 type 推导（点击等定位事件为 PositionedEvent、MOUSE_MOVE 为 MotionEvent、WHEEL 为 number、双指手势为 TwoPointEvent / TwoPointMotionEvent）。不传则不注册监听。
• inputAction - 监听回调函数；不传则不注册监听。
• modifier - 键盘修饰键（Cesium.KeyboardEventModifier），透传给 Cesium。
• isActive - 是否激活监听，默认 true；只暂停/恢复监听注册，不会重建整个 composable。

返回值

• 返回停止函数（WatchStopHandle）：调用即停止当前监听并销毁处理器；组件卸载时自动调用。

注意事项

• 处理器基于 canvas 创建：canvas 变化（如 viewer 重建）时旧实例自动销毁并创建新实例，无需手动处理。

Type Definitions

import type { KeyboardEventModifier, ScreenSpaceEventType } from 'cesium';
import type { MaybeRefOrGetter, WatchStopHandle } from 'vue';
import { ScreenSpaceEventHandler } from 'cesium';
export type ScreenSpaceEvent<T extends ScreenSpaceEventType> = {
    [ScreenSpaceEventType.LEFT_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_DOUBLE_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MOUSE_MOVE]: ScreenSpaceEventHandler.MotionEvent;
    [ScreenSpaceEventType.WHEEL]: number;
    [ScreenSpaceEventType.PINCH_START]: ScreenSpaceEventHandler.TwoPointEvent;
    [ScreenSpaceEventType.PINCH_END]: ScreenSpaceEventHandler.TwoPointEvent;
    [ScreenSpaceEventType.PINCH_MOVE]: ScreenSpaceEventHandler.TwoPointMotionEvent;
}[T];
export interface UseScreenSpaceEventHandlerOptions {
    /**
     * Modifier key forwarded to Cesium.
     */
    modifier?: MaybeRefOrGetter<KeyboardEventModifier | undefined>;
    /**
     * Whether to activate the event listener without tearing down the composable.
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
}
/**
 * Easily use the `ScreenSpaceEventHandler`,
 * when the dependent data changes or the component is unmounted,
 * the listener function will automatically reload or destroy.
 *
 * @param type Types of mouse event
 * @param inputAction Callback function for listening
 */
export declare function useScreenSpaceEventHandler<T extends ScreenSpaceEventType>(type?: MaybeRefOrGetter<T | undefined>, inputAction?: (event: ScreenSpaceEvent<T>) => any, options?: UseScreenSpaceEventHandlerOptions): WatchStopHandle;