createViewer

Initializes a Viewer instance, or reuses an existing instance passed in, and exposes it through dependency injection to the current component and its descendants. It encapsulates the boilerplate of calling destroy() manually and drilling props: an instance created from an element is destroyed automatically when the component scope ends.

Usage

<script setup lang="ts">
import { createViewer } from 'vesium';
import { shallowRef } from 'vue';
import 'cesium/Build/Cesium/Widgets/widgets.css';

const elRef = shallowRef<HTMLElement>();

createViewer(elRef, {
// ... options
});
</script>

<template>
  <div ref="elRef" class="inset-0 absolute" />
</template>

Note

If createViewer and useViewer are used in the same component, useViewer should be called after createViewer and will prioritize the instance created by the current component.

import { createViewer, useViewer } from 'vesium';
import { shallowRef } from 'vue';

const elRef = shallowRef<HTMLElement>();

// Pass in a DOM element (or ref) to create a new instance, destroyed on unmount
const viewer = createViewer(elRef, { /* ...options */ });

// Pass in an existing instance to reuse it without taking over its lifecycle
const sharedViewer = createViewer(window.viewer);
const injectedViewer = useViewer();

Return Value

• Readonly<ShallowRef<Viewer | undefined>> - a readonly reference to the Viewer; it becomes undefined once the instance is destroyed. It points to the same Viewer instance as useViewer(). (Note: the two are different ref objects; createViewer filters out destroyed instances.)

Notes

• A MutationObserver watches body: when the canvas is removed from the DOM (e.g. by v-if), the reference is cleared so consumers do not keep using a stale instance.
• If the element ref is not yet bound, no instance is created; it is created automatically once the element appears.

Type Definitions

import type { MaybeComputedElementRef } from '@vueuse/core';
import type { MaybeRef, ShallowRef } from 'vue';
import { Viewer } from 'cesium';
/**
 * Pass in an existing Viewer instance,
 * which can be accessed by the current component and its descendant components using {@link useViewer}
 *
 * When the Viewer instance referenced by this overloaded function becomes invalid, it will not trigger destruction.
 * @param viewer - Existing viewer instance
 * @returns The Viewer instance
 */
export declare function createViewer(viewer: MaybeRef<Viewer | undefined>): Readonly<ShallowRef<Viewer | undefined>>;
/**
 * Initialize a Viewer instance, which can be accessed by the
 * current component and its descendant components using {@link useViewer}.
 *
 * The Viewer instance created by this overloaded function will automatically be destroyed when it becomes invalid.
 *
 * @param element - The DOM element or ID that will contain the widget
 * @param options - see `Viewer.ConstructorOptions`
 * @returns The Viewer instance
 */
export declare function createViewer(element: MaybeComputedElementRef, options?: Viewer.ConstructorOptions): Readonly<ShallowRef<Viewer | undefined>>;