useSceneDrillPick

响应式封装 Cesium.Scene.drillPick：拾取同一屏幕坐标下的全部对象，返回结果数组的计算属性。场景中存在重叠图形、需要"点选后从列表选择目标"时使用；与 useScenePick 不同，这里没有结果缓存。

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useEntity, useSceneDrillPick, useScreenSpaceEventHandler } from 'vesium';
import { computed, shallowRef } from 'vue';

const cursorPosition = shallowRef<Cesium.Cartesian2>();

// track mouse move
useScreenSpaceEventHandler(Cesium.ScreenSpaceEventType.MOUSE_MOVE, (movement: { endPosition: Cesium.Cartesian2 }) => {
  cursorPosition.value = movement.endPosition.clone();
});

// use scene drill pick to pick multiple objects at cursor
const drillPick = useSceneDrillPick(cursorPosition, {
  width: 5,
  height: 5,
  limit: 10,
});

// show all picked objects
const pickInfo = computed(() => {
  if (!drillPick.value || drillPick.value.length === 0) {
    return 'No object picked';
  }
  const names = drillPick.value.map((item: any, index: number) => {
    if (item.id instanceof Cesium.Entity) {
      return `${index + 1}. Entity: ${item.id.name || 'unnamed'}`;
    }
    if (item.primitive) {
      return `${index + 1}. Primitive: ${item.primitive.id?.name || 'unnamed'}`;
    }
    return `${index + 1}. Unknown`;
  });
  return names.join('\n');
});

// add overlapping entities for drill pick demo
const _entity1 = useEntity(new Cesium.Entity({
  name: 'Layer 1 - Red',
  position: Cesium.Cartesian3.fromDegrees(120, 30, 100),
  box: {
    dimensions: new Cesium.Cartesian3(3000, 3000, 1000),
    material: new Cesium.ColorMaterialProperty(Cesium.Color.RED.withAlpha(0.6)),
  },
}));

const _entity2 = useEntity(new Cesium.Entity({
  name: 'Layer 2 - Green',
  position: Cesium.Cartesian3.fromDegrees(120, 30, 200),
  box: {
    dimensions: new Cesium.Cartesian3(2000, 2000, 1000),
    material: new Cesium.ColorMaterialProperty(Cesium.Color.GREEN.withAlpha(0.6)),
  },
}));

const _entity3 = useEntity(new Cesium.Entity({
  name: 'Layer 3 - Blue',
  position: Cesium.Cartesian3.fromDegrees(120, 30, 300),
  box: {
    dimensions: new Cesium.Cartesian3(1000, 1000, 1000),
    material: new Cesium.ColorMaterialProperty(Cesium.Color.BLUE.withAlpha(0.6)),
  },
}));
</script>

<template>
  <div style="position: fixed; top: 10px; left: 10px; padding: 8px; font-size: 12px; color: white; white-space: pre-wrap; background: rgb(0 0 0 / 70%); border-radius: 4px;">
    {{ pickInfo }}
  </div>
</template>

import * as Cesium from 'cesium';
import { useSceneDrillPick, useScreenSpaceEventHandler } from 'vesium';
import { shallowRef } from 'vue';

const cursorPosition = shallowRef<Cesium.Cartesian2>();
useScreenSpaceEventHandler(Cesium.ScreenSpaceEventType.MOUSE_MOVE, (m) => {
  cursorPosition.value = m.endPosition.clone();
});
const picks = useSceneDrillPick(cursorPosition, { limit: 10 }); // 最多 10 个，可降低开销
picks.value?.forEach((item, index) => {
  console.log(`${index + 1}.`, item.id.name);
});

配置项

• isActive - 是否激活拾取，默认 true；为 false 时结果重置为 undefined，支持 ref/getter。
• throttled - 坐标变化的节流采样间隔（毫秒），默认 8。
• limit - 最多收集的结果数量，透传给 scene.drillPick；不传返回全部命中对象，传较小值可降低开销。
• width / height - 拾取矩形宽高，默认 3。

返回值

• 返回 ComputedRef<any[] | undefined>：拾取结果数组，元素含 id、primitive 等字段（对应 scene.drillPick 返回项）；无命中或条件不满足时为 undefined。

注意事项

• drillPick 开销大于 pick 且无结果缓存，请配合 throttled 节流与 limit 限制使用。
• viewer 不存在、位置为空或 isActive 为 false 时，结果重置为 undefined。

Type Definitions

import type { Cartesian2 } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter } from 'vue';
export interface UseSceneDrillPickOptions {
    /**
     * Whether to activate the pick function.
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean | undefined>;
    /**
     * Throttled sampling (ms)
     * @default 8
     */
    throttled?: number;
    /**
     * If supplied, stop drilling after collecting this many picks.
     */
    limit?: MaybeRefOrGetter<number | undefined>;
    /**
     * The width of the pick rectangle.
     * @default 3
     */
    width?: MaybeRefOrGetter<number | undefined>;
    /**
     * The height of the pick rectangle.
     * @default 3
     */
    height?: MaybeRefOrGetter<number | undefined>;
}
/**
 * Uses the `scene.drillPick` function to perform screen point picking,
 * return a computed property containing the pick result, or undefined if no object is picked.
 *
 * @param windowPosition The screen coordinates of the pick point.
 */
export declare function useSceneDrillPick(windowPosition: MaybeRefOrGetter<Cartesian2 | undefined>, options?: UseSceneDrillPickOptions): ComputedRef<any[] | undefined>;