首页 / Cesium / API 文档

Scene

先看结论

整个三维场景的根对象：持有 canvas 与 WebGL 上下文，管理相机、地球、图元集合和后处理链。 Viewer 和 CesiumWidget 内部都各建了一个 Scene。

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

new Cesium.Scene({ canvas, contextOptions, creditContainer, mapProjection, orderIndependentTranslucency, scene3DOnly, shadows })

常规项目不直接构造 Scene，用 viewer.scene 即可。只有自己组织渲染循环、或要把 Cesium 嵌进已有 WebGL 管线时，才需要手工创建。

构造参数

参数	类型	默认	说明
`canvas`	HTMLCanvasElement	必填	WebGL 的绘制目标，尺寸由外部 CSS 决定
`contextOptions`	object	—	透传给 WebGL 上下文，常用 `alpha`、`antialias`、`webgl2`
`creditContainer`	Element \| string	—	版权信息显示在哪个 DOM 里
`mapProjection`	MapProjection	GeographicProjection	二维与哥伦布视图使用的投影
`orderIndependentTranslucency`	boolean	true	与顺序无关的半透明渲染，半透明物体互不遮挡
`scene3DOnly`	boolean	false	只保留三维模式，省掉二维相关的资源
`shadows`	boolean	false	是否开启阴影贴图

常用成员

成员	类型	说明
`canvas`	HTMLCanvasElement	画布，事件绑定和尺寸计算都基于它
`camera`	Camera	观察者，`flyTo`、`setView` 的入口
`globe`	Globe	地球本体，可置为 `false` 得到纯空间场景
`primitives`	PrimitiveCollection	图元集合，追求性能时用它代替 Entity
`groundPrimitives`	PrimitiveCollection	贴地图元，自动跟随地形起伏
`imageryLayers`	ImageryLayerCollection	影像图层栈，`addImageryProvider` 在这里
`postProcessStages`	PostProcessStageCollection	后处理链，`bloom`、`fxaa` 与自定义 stage
`screenSpaceCameraController`	ScreenSpaceCameraController	鼠标与触摸对相机的操作规则
`backgroundColor`	Color	没有地球和天空盒时的底色，默认黑色
`skyBox` / `skyAtmosphere`	SkyBox / SkyAtmosphere	星空盒与大气层，都是对象，用 `.show` 控制显示
`mode`	SceneMode	当前模式，只读，切换走 `morphTo2D` 等方法
`requestRenderMode`	boolean	按需渲染，静止时不再重绘
`debugShowFramesPerSecond`	boolean	左上角显示帧率

常用方法

方法	返回	说明
`pick(windowPosition, width, height)`	object \| undefined	拾取最上层可拾取对象，命中 Entity 时返回带 `id` 的包装对象
`drillPick(windowPosition, limit, width, height)`	Array	拾取该像素下的所有对象，按从前到后排序
`sampleHeight(position)`	number	取当前已加载地形的高度，未加载区域按椭球面算
`clampToHeight(object, position, objectsToExclude, width)`	Cartesian3	把点贴到地形或模型表面
`morphTo2D(duration)` / `morphTo3D(duration)`	—	二三维切换，`duration` 单位秒
`morphToColumbusView(duration)`	—	切换哥伦布视图（平面地图 + 立体要素）
`destroy()`	—	释放 WebGL 资源，切换页面时必须调用

示例

var scene = viewer.scene;

// 关掉天空与大气，做一个深色背景的数据场景
scene.skyBox.show = false;
scene.skyAtmosphere.show = false;
scene.sun.show = false;
scene.backgroundColor = Cesium.Color.fromCssColorString('#0b1220');

// 点击拾取
var handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
handler.setInputAction(function (movement) {
  var picked = scene.pick(movement.position);
  if (Cesium.defined(picked) && Cesium.defined(picked.id)) {
    console.log('命中实体', picked.id.id);
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

// 读取某点地形高度，返回 undefined 表示该级别还没加载
var height = scene.sampleHeight(
  Cesium.Cartesian3.fromDegrees(116.391263, 39.907359)
);
console.log(height);

注意事项

直接 new Cesium.Scene 不会自动挂载时钟、数据源和控件，这些属于 Viewer；自己建 Scene 时要自己维护渲染循环与 resize。
scene.globe 可以设为 false，此时 sampleHeight 和贴地相关方法不可用。
拾取地形表面要用 scene.globe.pick(ray, scene)，scene.pick 只能命中图元与 Entity。
开启 requestRenderMode 后，修改材质、移动实体都需要触发一次重绘，否则画面不更新。

引用本文

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