useCesiumEventListener

Reactively subscribe to events on Cesium.Event instances: the listener is re-registered automatically when the dependencies change (e.g. the viewer is recreated) and destroyed on component unmount. Use it for any Cesium.Event such as camera.moveStart or scene.postRender, or to subscribe to several events at once.

Usage

<script setup lang="ts">
import { useCesiumEventListener, useViewer } from 'vesium';
import { ref } from 'vue';

const viewer = useViewer();

const changedSymbol = ref('no change');

useCesiumEventListener(() => viewer.value?.camera.moveStart, () => {
  changedSymbol.value = 'moveStart';
});

useCesiumEventListener(() => viewer.value?.camera.moveEnd, () => {
  changedSymbol.value = 'moveEnd';
});
</script>

<template>
  <div class="p-10px flex flex-col gap-y-10px">
    Camera Changed : {{ changedSymbol }}
  </div>
</template>

import { useCesiumEventListener, useViewer } from 'vesium';

const viewer = useViewer();

// Pass a getter when the event instance may not be ready or may change
useCesiumEventListener(() => viewer.value?.camera.moveEnd, () => {
  console.log('Camera move end');
});

// Arrays are supported: subscribe to multiple events at once
useCesiumEventListener(() => [viewer.value?.scene.preRender, viewer.value?.scene.postRender], () => {});

Suggestion

Events are often triggered by real-time frame rendering, which may cause invalid refreshing of Vue's reactivity, so throttling the listeners is recommended. Use the throttle function from @vesium/shared or refThrottled from VueUse.

Options

• isActive - Whether the listener is active, defaults to true; when false nothing is registered and the subscription resumes automatically once it becomes true. Supports a ref or getter for dynamic control.

Return Value

• Returns a stop function (WatchStopHandle): calling it removes all currently registered listeners immediately; it is also called automatically on component unmount, so no manual cleanup is needed.

Notes

• event accepts a single Cesium.Event or an array of them; each entry may be undefined, a ref, or a getter, and the listener is re-registered automatically when the dependencies change.

Type Definitions

import type { Arrayable, FunctionArgs } from '@vueuse/core';
import type { Event } from 'cesium';
import type { MaybeRefOrGetter, WatchStopHandle } from 'vue';
export interface UseCesiumEventListenerOptions {
    /**
     * Whether to active the event listener.
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
}
/**
 * Easily use the `addEventListener` in `Cesium.Event` instances,
 * when the dependent data changes or the component is unmounted,
 * the listener function will automatically reload or destroy.
 *
 * @param event The Cesium.Event instance
 * @param listener The listener function
 * @param options additional options
 * @returns  A function that can be called to remove the event listener
 */
export declare function useCesiumEventListener<FN extends FunctionArgs<any[]>>(event: Arrayable<Event<FN> | undefined> | Arrayable<MaybeRefOrGetter<Event<FN> | undefined>> | MaybeRefOrGetter<Arrayable<Event<FN> | undefined>>, listener: FN, options?: UseCesiumEventListenerOptions): WatchStopHandle;