useEntity

Reactively adds Cesium Entity instances (points, labels, models, etc.) to an EntityCollection (defaults to viewer.entities). When the data changes or the component unmounts, the previous batch is removed automatically and the new data added — no manual tracking; values, getters, refs, async getters and arrays are all supported. Removal only calls collection.remove(entity) and never destroys the instance: Entity is a descriptive object that does not hold GPU resources directly, so it stays reusable and re-addable (unlike usePrimitive, which destroys by default).

Usage

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

// use entity instance
const entity1 = useEntity(new Cesium.Entity({
  position: Cesium.Cartesian3.fromDegrees(150, 10),
  label: {
    font: '14px Arial',
    text: 'entity instance',
  },
}));

// use getter
const entity2 = useEntity(() => {
  return new Cesium.Entity({
    position: Cesium.Cartesian3.fromDegrees(150, 9),
    label: {
      font: '14px Arial',
      text: 'use getter',
    },
  });
});

const entityRef = shallowRef(new Cesium.Entity({
  position: Cesium.Cartesian3.fromDegrees(150, 8),
  label: {
    font: '14px Arial',
    text: 'use ref',
  },
}));

// use ref
const entity3 = useEntity(entityRef);

// use array
const entities = useEntity([
  new Cesium.Entity({
    position: Cesium.Cartesian3.fromDegrees(149, 7),
    label: {
      font: '14px Arial',
      text: 'array item 1',
    },
  }),
  new Cesium.Entity({
    position: Cesium.Cartesian3.fromDegrees(151, 7),
    label: {
      font: '14px Arial',
      text: 'array item 2',
    },
  }),
]);

const viewer = useViewer();
watchPostEffect(() => {
  if (entity1.value && entity2.value && entity3.value && entities.value) {
    viewer.value?.flyTo([
      entity1.value,
      entity2.value,
      entity3.value,
      ...entities.value!,
    ], {
      duration: 1,
    });
  }
});
</script>

<template>
</template>

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

// Single value: you create and own the instance; the hook only adds/removes it
const entity = useEntity(new Cesium.Entity({
  position: Cesium.Cartesian3.fromDegrees(150, 10),
  label: { text: 'entity instance' },
}));

// Getter rebuilds on every evaluation; refs, async getters and arrays also work
const dynamic = useEntity(() => new Cesium.Entity({ /* ... */ }));

Options

• collection - The target EntityCollection; defaults to useViewer().value.entities.
• isActive - Whether active, defaults to true; toggling adds/removes automatically.
• evaluating - A ref receiving the async evaluation state; true while evaluating.

Return Value

• A single value (or getter/ref/async getter) returns ComputedRef<T | undefined>.
• An array returns ComputedRef<T[] | undefined>.

Notes

• The returned ref is driven by computedAsync with an initial value of [] — an empty array is truthy, so don't rely on truthiness to check existence.
• An array input is replaced as a whole: on change, the old batch is fully removed and the new one fully added.

Type Definitions

import type { Entity, EntityCollection } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
import type { MaybeRefOrAsyncGetter } from '../toPromiseValue';
export interface UseEntityOptions {
    /**
     * The collection of Entity to be added
     * @default useViewer().value.entities
     */
    collection?: EntityCollection;
    /**
     * default value of `isActive`
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
    /**
     * Ref passed to receive the updated of async evaluation
     */
    evaluating?: Ref<boolean>;
}
/**
 * Add `Entity` to the `EntityCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `Entity`.
 *
 * Overload 1: Parameter supports passing in a single value.
 */
export declare function useEntity<T extends Entity = Entity>(entity?: MaybeRefOrAsyncGetter<T | undefined>, options?: UseEntityOptions): ComputedRef<T | undefined>;
/**
 * Add `Entity` to the `EntityCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `Entity`.
 *
 * Overload 2: Parameter supports passing in an array.
 */
export declare function useEntity<T extends Entity = Entity>(entities?: MaybeRefOrAsyncGetter<Array<T | undefined> | undefined>, options?: UseEntityOptions): ComputedRef<T[] | undefined>;