首页 / Cesium / API 文档

Viewer

先看结论

把场景、相机、控件和默认数据源打包在一起的入口对象。绝大多数 Cesium 项目都从它开始。

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

new Cesium.Viewer(container, options)

container 可以是 DOM 元素，也可以是元素 id。 options 全部可省略，但省略后默认会尝试连接 Cesium ion。

常用参数

参数	类型	默认	说明
`baseLayer`	ImageryLayer \| false	ion 影像	设为 `false` 完全不加载影像，也不再请求 ion
`terrain`	Terrain	椭球体	地形服务；与 `terrainProvider` 二选一
`terrainProvider`	TerrainProvider	EllipsoidTerrainProvider	旧式写法，仍然可用
`baseLayerPicker`	boolean	true	右上角图层选择器
`geocoder`	boolean	true	地名搜索框
`homeButton`	boolean	true	回到初始视角按钮
`sceneModePicker`	boolean	true	二三维切换
`navigationHelpButton`	boolean	true	操作提示
`animation`	boolean	true	左下角时钟动画控件
`timeline`	boolean	true	底部时间轴
`fullscreenButton`	boolean	true	全屏按钮
`infoBox`	boolean	true	点击要素后弹出的信息框
`selectionIndicator`	boolean	true	选中要素时的绿色选择框
`shouldAnimate`	boolean	false	时钟是否自动前进
`requestRenderMode`	boolean	false	开启后按需渲染，静态场景可显著省电

常用成员

成员	说明
`viewer.scene`	场景对象，控制地球、光照、天空盒、后处理
`viewer.camera`	相机，`flyTo` / `setView` / `lookAt` 都在这里
`viewer.entities`	实体集合，点、线、面、模型、标签的统一入口
`viewer.dataSources`	数据源集合，CZML、GeoJSON、KML 加进来后在这里
`viewer.clock`	时钟，控制 CZML 动画的时间
`viewer.scene.globe`	地球本体，`baseColor`、`enableLighting` 等

纯展示场景的写法

做数据看板或大屏时，通常把这些全关掉，只留一个干净的三维地球：

var viewer = new Cesium.Viewer('map', {
  baseLayer: false,
  baseLayerPicker: false,
  geocoder: false,
  homeButton: false,
  sceneModePicker: false,
  navigationHelpButton: false,
  animation: false,
  timeline: false,
  fullscreenButton: false,
  infoBox: false,
  selectionIndicator: false,
  requestRenderMode: true,
  maximumRenderTimeChange: Infinity
});

var s = viewer.scene;
s.globe.baseColor = Cesium.Color.fromCssColorString('#1c2733');
s.skyBox.show = false;
s.sun.show = false;
s.moon.show = false;
s.skyAtmosphere.show = false;

requestRenderMode 开启后，Cesium 只在场景变化时重绘，静止状态下几乎不占 GPU。只要页面里有动画（CZML、时间轴、闪烁的点），就要把它关掉，否则画面会卡住不动。

需要销毁

viewer.destroy() 会释放 WebGL 资源。单页应用里切换路由时如果不调用，反复进出几次就会出现上下文数量超限、页面变黑的报错。

引用本文

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