useDataSource

Reactively adds Cesium DataSource instances (GeoJsonDataSource, KmlDataSource, CzmlDataSource, etc.) to a DataSourceCollection (defaults to viewer.dataSources). Data sources are typically the entry point for asynchronously loading external geographic data: pass an async getter directly — the data source is added once loaded, removed when the data changes or the component unmounts, and the loading state is exposed via evaluating. Removal keeps the instance by default — when destroyOnRemove is unspecified it passes undefined through and Cesium's remove treats it as false; pass true explicitly to destroy and release resources.

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useDataSource, useViewer } from 'vesium';
import { watchPostEffect } from 'vue';
import geojson from '../../.vitepress/static/geojson.json?url';

const dataSource = useDataSource(() => Cesium.GeoJsonDataSource.load(geojson));

const viewer = useViewer();
watchPostEffect(() => {
  if (dataSource.value) {
    viewer.value?.flyTo(
      dataSource.value,
      {
        duration: 1,
      },
    );
  }
});
</script>

<template>
</template>

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

// Async getter: added once loaded
const dataSource = useDataSource(() => Cesium.GeoJsonDataSource.load('/data/city.geojson'));

// Sync instance: pass it directly
const custom = useDataSource(new Cesium.CustomDataSource('my-data'));

// Options: isActive controls activation, destroyOnRemove controls destruction on removal
const controlled = useDataSource(new Cesium.CustomDataSource('controlled'), {
  isActive: true, // When false, the data source is not added
  destroyOnRemove: true, // Not destroyed by default; pass true to release resources
});

Options

• collection - The target DataSourceCollection; defaults to useViewer().value.dataSources.
• isActive - Whether active, defaults to true.
• evaluating - A ref receiving the async evaluation state; true while loading.
• destroyOnRemove - Second argument of dataSources.remove; no default set (undefined passed through), Cesium treats it as false (kept by default); pass true to destroy.

Return Value

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

Notes

• Cleanup first checks !collection.isDestroyed() and skips removal when the collection is destroyed.
• Use it inside the component tree provided by createViewer: the data source is not added while the viewer is unavailable.

Type Definitions

import type { CesiumDataSource } from '@vesium/shared';
import type { DataSourceCollection } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
import type { MaybeRefOrAsyncGetter } from '../toPromiseValue';
export interface UseDataSourceOptions {
    /**
     * The collection of DataSource to be added
     * @default useViewer().value.dataSources
     */
    collection?: DataSourceCollection;
    /**
     * default value of `isActive`
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
    /**
     * Ref passed to receive the updated of async evaluation
     */
    evaluating?: Ref<boolean>;
    /**
     * The second parameter passed to the `remove` function
     *
     * `dataSources.remove(dataSource,destroyOnRemove)`
     */
    destroyOnRemove?: MaybeRefOrGetter<boolean>;
}
/**
 * Add `DataSource` to the `DataSourceCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `DataSource`.
 *
 * Overload 1: Parameter supports passing in a single value.
 *
 * @param dataSource The `DataSource` to added
 * @param options additional options
 *
 * @returns  computedRef of the `DataSource`
 *
 * @overload
 */
export declare function useDataSource<T extends CesiumDataSource = CesiumDataSource>(dataSource?: MaybeRefOrAsyncGetter<T | undefined>, options?: UseDataSourceOptions): ComputedRef<T | undefined>;
/**
 * Add `DataSource` to the `DataSourceCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `DataSource`.
 *
 * Overload 2: Parameter supports passing in an array.
 *
 * @param dataSources The list of `DataSource` to added
 * @param options additional options
 *
 * @returns  computedRef of the `DataSource`
 *
 * @overload
 */
export declare function useDataSource<T extends CesiumDataSource = CesiumDataSource>(dataSources?: MaybeRefOrAsyncGetter<T[] | undefined>, options?: UseDataSourceOptions): ComputedRef<T[] | undefined>;