CesiumWidget

CesiumWidget 是一个基于 WebGL 技术的虚拟地球客户端开发框架 CesiumJS 的核心类。它封装了底层的 WebGL 渲染和事件驱动机制，并提供了构建三维场景的基本工具。

类定义

class CesiumWidget {
  constructor(container: HTMLElement | string, options?: CesiumWidgetOptions)
  camera: Camera;
  canvas: HTMLCanvasElement;
  scene: Scene;
  clock: Clock;
  imageryLayers: ImageryLayerCollection;
  terrainProvider: TerrainProvider | undefined;
  entities: EntityCollection;
  dataSourceDisplay: DataSourceDisplay;
  selectionIndicator: SelectionIndicator | undefined;
  infoBox: InfoBox | undefined;
  navigationHelpButton: NavigationHelpButton | undefined;
  homeButton: HomeButton | undefined;
  animation: Animation | undefined;
  baseLayerPicker: BaseLayerPicker | undefined;
  fullscreenButton: FullscreenButton | undefined;
  vrButton: VRButton | undefined;
  geocoder: Geocoder | undefined;
  timeline: Timeline | undefined;
  sceneModePicker: SceneModePicker | undefined;
  projectionPicker: ProjectionPicker | undefined;
  creditContainer: HTMLElement | undefined;
  targetFrameRate: number | undefined;
  useDefaultRenderLoop: boolean;
  requestRenderMode: boolean;
  maximumRenderTimeChange: number;
  showRenderLoopErrors: boolean;
  allowDataSourcesToSuspendAnimation: boolean;
  readonly cameraControlsUnderground: boolean;
  forceResize: boolean;
  readonly hasError: boolean;
  readonly renderError: Event;
  readonly targetFrameRateChanged: Event;
  readonly preRender: Event;
  readonly postRender: Event;
  readonly cameraMoveStart: Event;
  readonly cameraMoveEnd: Event;
  readonly cameraChanged: Event;
  readonly resize: Event;
  readonly viewerPoseChanged: Event;
  static offscreenViewportChanged: Event;
  static useDefaultRenderLoopChanged: Event;
  static requestRenderModeChanged: Event;
  static maximumRenderTimeChangeChanged: Event;
  static showRenderLoopErrorsChanged: Event;
  destroy(): void;
}

构造函数

constructor(container: HTMLElement | string, options?: CesiumWidgetOptions)

创建 CesiumWidget 实例。

Parameters

• container: HTMLElement | string - 可以容纳 CesiumCanvas 的 HTML 元素或 ID。
• options: CesiumWidgetOptions - 可选参数，如视野范围、渲染模式等设置属性。默认为 {}。

属性

camera

camera: Camera;

获取或设置 CesiumWidget 的相机对象。相机包含视角角度、位置、朝向等视角属性，用于设置场景图的显示状态。

canvas

canvas: HTMLCanvasElement;

获取 CesiumWidget 的渲染画布。

scene

scene: Scene;

获取 CesiumWidget 的场景对象。

clock

clock: Clock;

获取 CesiumWidget 的时间轴对象。

imageryLayers

imageryLayers: ImageryLayerCollection;

获取 CesiumWidget 的图层集合对象。

terrainProvider

terrainProvider: TerrainProvider | undefined;

获取或设置 CesiumWidget 的地形提供者。

entities

entities: EntityCollection;

获取 CesiumWidget 的实体集合对象。

dataSourceDisplay

dataSourceDisplay: DataSourceDisplay;

获取 CesiumWidget 的数据源显示对象。

selectionIndicator

selectionIndicator: SelectionIndicator | undefined;

获取或设置 CesiumWidget 的框选标识器。

infoBox

infoBox: InfoBox | undefined;

获取或设置 CesiumWidget 的信息窗口。

navigationHelpButton

navigationHelpButton: NavigationHelpButton | undefined;

获取或设置 CesiumWidget 的导航帮助按钮对象。

homeButton

homeButton: HomeButton | undefined;

获取或设置 CesiumWidget 的回到初始视角按钮。

animation

animation: Animation | undefined;

获取或设置 CesiumWidget 的动画对象。

baseLayerPicker

baseLayerPicker: BaseLayerPicker | undefined;

获取或设置 CesiumWidget 的底图选择器对象。

fullscreenButton

fullscreenButton: FullscreenButton | undefined;

获取或设置 CesiumWidget 的全屏显示按钮。

vrButton

vrButton: VRButton | undefined;

获取或设置 CesiumWidget 的 VR 模式切换按钮。

geocoder

geocoder: Geocoder | undefined;

获取或设置 CesiumWidget 的地理编码对象。

timeline

timeline: Timeline | undefined;

获取或设置 CesiumWidget 的时间轴对象。

sceneModePicker

sceneModePicker: SceneModePicker | undefined;

获取或设置 CesiumWidget 的场景模式选择器对象。

projectionPicker

projectionPicker: ProjectionPicker | undefined;

获取或设置 CesiumWidget 的投影选择器对象。

creditContainer

creditContainer: HTMLElement | undefined;

获取或设置 CesiumWidget 的版权信息容器。

targetFrameRate

targetFrameRate: number | undefined;

获取或设置 CesiumWidget 的目标帧率。

useDefaultRenderLoop

useDefaultRenderLoop: boolean;

获取或设置 CesiumWidget 是否使用默认渲染循环。

requestRenderMode

requestRenderMode: boolean;

获取或设置 CesiumWidget 是否请求渲染模式。

maximumRenderTimeChange

maximumRenderTimeChange: number;

获取或设置 CesiumWidget 的最大渲染时间变化值。

showRenderLoopErrors

showRenderLoopErrors: boolean;

获取或设置 CesiumWidget 是否显示渲染循环错误。

allowDataSourcesToSuspendAnimation

allowDataSourcesToSuspendAnimation: boolean;

获取或设置 CesiumWidget 是否允许数据源暂停动画。

cameraControlsUnderground

readonly cameraControlsUnderground: boolean;

获取 CesiumWidget 相机是否在地下。

forceResize

forceResize: boolean;

获取或设置 CesiumWidget 是否强制 resize。

hasError

readonly hasError: boolean;

获取 CesiumWidget 是否存在错误。

renderError

readonly renderError: Event;

当渲染时出现错误时触发的事件。

targetFrameRateChanged

readonly targetFrameRateChanged: Event;

当目标帧率发生变化时触发的事件。

preRender

readonly preRender: Event;

场景渲染之前触发的事件。

postRender

readonly postRender: Event;

场景渲染之后触发的事件。

cameraMoveStart

readonly cameraMoveStart: Event;

相机移动开始时触发的事件。

cameraMoveEnd

readonly cameraMoveEnd: Event;

相机移动结束时触发的事件。

cameraChanged

readonly cameraChanged: Event;

相机属性改变时触发的事件。

resize

readonly resize: Event;

CesiumWidget 容器尺寸改变时触发的事件。

viewerPoseChanged

readonly viewerPoseChanged: Event;

观察者位置或朝向改变时触发的事件。

offscreenViewportChanged

static offscreenViewportChanged: Event;

当 offscreen 模式的视口变化时触发的事件。

useDefaultRenderLoopChanged

static useDefaultRenderLoopChanged: Event;

当 useDefaultRenderLoop 属性变化时触发的事件。

requestRenderModeChanged

static requestRenderModeChanged: Event;

当 requestRenderMode 属性变化时触发的事件。

maximumRenderTimeChangeChanged

static maximumRenderTimeChangeChanged: Event;

当 maximumRenderTimeChange 属性变化时触发的事件。

showRenderLoopErrorsChanged

static showRenderLoopErrorsChanged: Event;

当 showRenderLoopErrors 属性变化时触发的事件。

方法

destroy()

destroy(): void;

销毁 CesiumWidget 实例及其所有相关资源，释放内存。

例子

创建一个 CesiumWidget 实例，并将其添加到 id 为 "cesiumContainer" 的 div 中。

<div id="cesiumContainer"></div>

import Cesium from "cesium";

const viewer = new Cesium.CesiumWidget("cesiumContainer");

设置 CesiumWidget 实例的相机和视野范围。

const camera = viewer.camera;
// 设置相机高度
camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(
    117.16,
    31.83,
    11000000
  ),
});
// 初始位置和方向
camera.lookAt(
  new Cesium.Cartesian3.fromDegrees(117.16, 31.83, 4000000),
  new Cesium.Cartesian3.fromDegrees(117.16, 31.83, 0)
);

在 CesiumWidget 实例中添加 Tileset 对象。

const scene = viewer.scene;
const tileset = scene.primitives.add(new Cesium.Cesium3DTileset({
  url: "https://assets.cesium.com/4696",
}));

CesiumWidget 实例中添加 Entity 和 Label 对象。

const entities = viewer.entities;
const logo = entities.add({
  position: Cesium.Cartesian3.fromDegrees(117.16, 31.83),
  billboard: {
    image: "logo.png",
    scale: 0.5,
  },
});
entities.add({
  position: Cesium.Cartesian3.fromDegrees(117.16, 31.83, 100000),
  label: {
    text: "CesiumJS",
    font: "20px sans-serif",
    horizontalOrigin: Cesium.HorizontalOrigin.CENTER,
    verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
  },
});