首页 / Cesium / API 文档

CesiumWidget

先看结论

最小可用的三维地球：一个场景加一条渲染循环，没有工具按钮、没有时间轴、也没有 Entity 与数据源封装。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-28 · 引用本文

new Cesium.CesiumWidget(container, options)

构造参数

参数	类型	默认	说明
`container`	Element \| string	必填	DOM 元素或其 id，画布会铺满
`options.baseLayer`	ImageryLayer \| false	ion 影像	底层影像，false 表示不加载也不请求 ion
`options.terrain`	Terrain	椭球体	地形服务，新版写法
`options.terrainProvider`	TerrainProvider	EllipsoidTerrainProvider	地形，旧式写法，仍可用
`options.sceneMode`	SceneMode	SCENE3D	初始模式，可设为 SCENE2D 或 COLUMBUS_VIEW
`options.skyBox`	SkyBox	ion 星空	星空盒；网络受限时设为 false 更稳妥
`options.skyAtmosphere`	SkyAtmosphere	默认大气	大气层对象
`options.globe`	Globe \| false	默认 Globe	false 表示不要地球，只画图元
`options.useDefaultRenderLoop`	boolean	true	自动 requestAnimationFrame 循环
`options.targetFrameRate`	number	—	限制帧率上限
`options.requestRenderMode`	boolean	false	按需渲染
`options.shadows`	boolean	false	是否开启阴影

常用成员与方法

成员	类型 / 返回	说明
`scene`	Scene	场景对象，所有渲染相关操作从这里进
`canvas`	HTMLCanvasElement	画布，事件绑定的目标
`container`	Element	外层容器
`useDefaultRenderLoop`	boolean	改为 false 后需自己调用 `render()`
`targetFrameRate`	number	帧率上限
`resize()`	—	容器尺寸变化后手动重算画布
`render()`	—	手动渲染一帧
`destroy()` / `isDestroyed()`	— / boolean	销毁并释放 WebGL 资源

示例

// 一个没有工具按钮、没有 ion 依赖的干净地球
var widget = new Cesium.CesiumWidget('map', {
  baseLayer: false,
  skyBox: false,
  sceneMode: Cesium.SceneMode.SCENE3D,
  useDefaultRenderLoop: true
});

var scene = widget.scene;
scene.globe.baseColor = Cesium.Color.fromCssColorString('#1b2735');
scene.skyAtmosphere.show = false;
scene.sun.show = false;

// 自己加图元：CesiumWidget 没有 entities，要用 primitives
scene.primitives.add(new Cesium.PointPrimitiveCollection()).add({
  position: Cesium.Cartesian3.fromDegrees(116.391, 39.907, 0),
  pixelSize: 10,
  color: Cesium.Color.CYAN
});

// 容器尺寸变化后必须手动通知
window.addEventListener('resize', function () {
  widget.resize();
});

注意事项

没有 entities、dataSources、clock 封装，业务对象要自己用 primitives 或另建 EntityCollection。
没有内置的 resize 监听，容器尺寸变化后画面会被拉伸，需自行调用 widget.resize()。
没有版权容器与错误面板，ion 资源加载失败时不会在界面上提示，需要自己处理 baseLayer: false。
销毁时不会连带销毁你加入 scene 的图元，切换页面要按加入顺序清理。

引用本文

经纬志（2026）。《CesiumWidget》。https://www.jingweizhi.com/cesium/api/cesium-widget.html（访问日期 2026-11-03）。