用于构建应用程序的基础控件。它将所有标准 Cesium 控件组合成一个可重用的包。
该控件始终可以通过使用 mixin 进行扩展，mixin 为各种应用程序添加有用的功能。
| Name | Type | Description |
|---|---|---|
container |
Element | string | 包含此控件的 DOM 元素或 id。 |
options |
Viewer.ConstructorOptions | optional 描述初始化选项的对象 |
Throws:
-
DeveloperError : 文档中不存在 id 为 "container" 的元素。
-
DeveloperError : 不使用 BaseLayerPicker 控件时，options.selectedImageryProviderViewModel 不可用，请改为指定 options.baseLayer。
-
DeveloperError : 不使用 BaseLayerPicker 控件时，options.selectedTerrainProviderViewModel 不可用，请改为指定 options.terrainProvider。
Example:
// 使用多个自定义选项和 mixin 初始化 viewer 控件。
try {
const viewer = new Cesium.Viewer("cesiumContainer", {
// 在哥伦布视图中启动
sceneMode: Cesium.SceneMode.COLUMBUS_VIEW,
// 使用 Cesium World Terrain
terrain: Cesium.Terrain.fromWorldTerrain(),
// 隐藏基础图层选择器
baseLayerPicker: false,
// 使用 OpenStreetMaps
baseLayer: new Cesium.ImageryLayer(new Cesium.OpenStreetMapImageryProvider({
url: "https://tile.openstreetmap.org/"
})),
skyBox: new Cesium.SkyBox({
sources: {
positiveX: "stars/TychoSkymapII.t3_08192x04096_80_px.jpg",
negativeX: "stars/TychoSkymapII.t3_08192x04096_80_mx.jpg",
positiveY: "stars/TychoSkymapII.t3_08192x04096_80_py.jpg",
negativeY: "stars/TychoSkymapII.t3_08192x04096_80_my.jpg",
positiveZ: "stars/TychoSkymapII.t3_08192x04096_80_pz.jpg",
negativeZ: "stars/TychoSkymapII.t3_08192x04096_80_mz.jpg"
}
}),
// 使用 Web Mercator 投影显示哥伦布视图地图
mapProjection: new Cesium.WebMercatorProjection()
});
} catch (error) {
console.log(error);
}
// 添加基本的拖放功能
viewer.extend(Cesium.viewerDragDropMixin);
// 处理拖放文件时如果遇到错误显示弹出警告
viewer.dropError.addEventListener(function(dropHandler, name, error) {
console.log(error);
window.alert(error);
});Demo:
See:
Members
获取或设置数据源是否可以暂时暂停动画以避免向用户显示不完整的画面。
例如，如果异步图元正在后台处理，时钟在几何体准备好之前不会推进。
readonly animation : Animation
获取 Animation 控件。
readonly baseLayerPicker : BaseLayerPicker
获取 BaseLayerPicker。
获取窗口底部区域的 DOM 元素，包含
CreditDisplay 和可能的其他内容。
readonly camera : Camera
获取相机。
获取画布。
readonly cesiumWidget : CesiumWidget
获取 CesiumWidget。
readonly clock : Clock
获取时钟。
clockTrackedDataSource : DataSource
获取或设置与 viewer 时钟跟踪的数据源。
readonly clockViewModel : ClockViewModel
获取时钟视图模型。
获取父容器。
creditDisplay : CreditDisplay
管理要在屏幕和灯箱中显示的信用列表。
readonly dataSourceDisplay : DataSourceDisplay
获取用于可视化
DataSource 的显示。
readonly dataSources : DataSourceCollection
获取要可视化的
DataSource 实例集合。
readonly ellipsoid : Ellipsoid
获取场景的默认椭球体。
-
Default Value:
Ellipsoid.default
readonly entities : EntityCollection
获取不绑定到特定数据源的实体集合。
这是
dataSourceDisplay.defaultDataSource.entities 的快捷方式。
readonly fullscreenButton : FullscreenButton
获取 FullscreenButton。
readonly geocoder : Geocoder
获取 Geocoder。
readonly homeButton : HomeButton
获取 HomeButton。
readonly imageryLayers : ImageryLayerCollection
获取将在 globe 上渲染的影像图层集合。
readonly infoBox : InfoBox
获取信息框。
readonly navigationHelpButton : NavigationHelpButton
获取 NavigationHelpButton。
readonly postProcessStages : PostProcessStageCollection
获取后处理阶段。
readonly projectionPicker : ProjectionPicker
获取 ProjectionPicker。
获取或设置渲染分辨率的缩放因子。小于 1.0 的值可以提高性能较弱设备的性能，
而大于 1.0 的值将以更高分辨率渲染然后缩小，从而改善视觉效果。
例如，如果控件布局大小为 640x480，将此值设置为 0.5 将导致场景以 320x240 渲染然后放大，
而设置为 2.0 将导致场景以 1280x960 渲染然后缩小。
-
Default Value:
1.0
readonly scene : Scene
获取场景。
readonly sceneModePicker : SceneModePicker
获取 SceneModePicker。
readonly screenSpaceEventHandler : ScreenSpaceEventHandler
获取屏幕空间事件处理器。
selectedEntity : Entity|undefined
获取或设置要显示选择指示的对象实例。
如果用户交互地选择了 Cesium3DTilesFeature 实例，则此属性将包含一个瞬态 Entity 实例，
该实例具有名为 "feature" 的属性，即被选择的实例。
readonly selectedEntityChanged : Event
获取所选实体更改时触发的事件。
readonly selectionIndicator : SelectionIndicator
获取选择指示器。
readonly shadowMap : ShadowMap
获取场景的阴影映射。
确定光源是否投射阴影。
获取或设置当
useDefaultRenderLoop 为 true 时控件的目标帧率。
如果未定义，由浏览器的 requestAnimationFrame 实现确定帧率。如果已定义，此值必须大于 0。
高于底层 requestAnimationFrame 实现的值将无效。
terrainProvider : TerrainProvider
为 globe 提供表面地形的地形提供器。
terrainShadows : ShadowMode
确定地形是否投射或接收来自光源的阴影。
readonly timeline : Timeline
获取 Timeline 控件。
trackedEntity : Entity|undefined
获取或设置相机当前跟踪的 Entity 实例。
readonly trackedEntityChanged : Event
获取跟踪实体更改时触发的事件。
布尔标志，指示是否使用浏览器的推荐分辨率。
如果为 true，则忽略浏览器的设备像素比并使用 1.0，有效地基于 CSS 像素而不是设备像素进行渲染。
这可以在高像素密度的性能较弱设备上改善性能。当为 false 时，将以设备像素渲染。
无论此标志是 true 还是 false，
Viewer#resolutionScale 都将生效。
-
Default Value:
true
获取或设置此控件是否应该控制渲染循环。
如果为 true，控件将使用 requestAnimationFrame 执行渲染和控件大小调整，以及驱动模拟时钟。
如果设置为 false，必须在自定义渲染循环中手动调用
resize、render 方法。
如果渲染时发生错误，将触发 Scene 的 renderError 事件，且此属性将设置为 false。
必须在错误后重新设置为 true 才能继续渲染。
readonly vrButton : VRButton
获取 VRButton。
Methods
销毁控件。如果从布局中永久移除控件，应调用此方法。
使用提供的 mixin 扩展基础 viewer 功能。
mixin 可以为 viewer 实例添加额外的属性、函数或其他功能。
| Name | Type | Description |
|---|---|---|
mixin |
Viewer.ViewerMixin | 要添加到此实例的 Viewer mixin。 |
options |
object | optional 要传递给 mixin 函数的选项对象。 |
See:
飞行相机到提供的实体、实体数组或数据源。
如果数据源仍在加载过程中或可视化仍在加载，此方法将等待数据准备好后再执行飞行。
偏移量是局部东北天参考帧中的航向/俯仰/范围，以边界球体的中心为中心。 航向和俯仰角在局部东北天参考帧中定义。 航向是从 y 轴开始并向 x 轴增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面上方。 负俯仰角在平面下方。范围是到中心的距离。如果范围为零，将计算一个范围以使整个边界球体可见。
在 2D 中，必须是自上而下的视图。相机将放置在目标上方俯视。 目标上方的高度为范围。航向将由偏移量确定。如果无法从偏移量确定航向，则航向为北。
| Name | Type | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
target |
Entity | Array.<Entity> | EntityCollection | DataSource | ImageryLayer | Cesium3DTileset | TimeDynamicPointCloud | Promise.<(Entity|Array.<Entity>|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|VoxelPrimitive|BufferPrimitiveCollection.<BufferPrimitive>)> | 要查看的实体、实体数组、实体集合、数据源、Cesium3DTileset、点云或影像图层。也可以传递解析为上述类型之一的 promise。 | ||||||||||||||||
options |
object |
optional
具有以下属性的对象：
|
Returns:
解析为 true 表示飞行成功，或 false 表示目标当前未在场景中可视化或飞行被取消的 Promise。
强制控件重新考虑其布局，包括控件大小和信用显示位置。
Returns:
如果对象已被销毁则返回 true，否则返回 false。
渲染场景。除非
useDefaultRenderLoop 设置为 false，否则会自动调用此函数。
调整控件大小以匹配容器大小。
除非
useDefaultRenderLoop 设置为 false，否则此函数会自动调用。
异步设置相机以查看提供的实体、实体数组或数据源。
如果数据源仍在加载过程中或可视化仍在加载，此方法将等待数据准备好后再执行缩放。
偏移量是局部东北天参考帧中的航向/俯仰/范围，以边界球体的中心为中心。 航向和俯仰角在局部东北天参考帧中定义。 航向是从 y 轴开始并向 x 轴增加的角度。俯仰是从 xy 平面的旋转。正俯仰角在平面上方。 负俯仰角在平面下方。范围是到中心的距离。如果范围为零，将计算一个范围以使整个边界球体可见。
在 2D 中，必须是自上而下的视图。相机将放置在目标上方俯视。 目标上方的高度为范围。航向将由偏移量确定。如果无法从偏移量确定航向，则航向为北。
| Name | Type | Description |
|---|---|---|
target |
Entity | Array.<Entity> | EntityCollection | DataSource | ImageryLayer | Cesium3DTileset | TimeDynamicPointCloud | Promise.<(Entity|Array.<Entity>|EntityCollection|DataSource|ImageryLayer|Cesium3DTileset|TimeDynamicPointCloud|VoxelPrimitive|BufferPrimitiveCollection.<BufferPrimitive>)> | 要查看的实体、实体数组、实体集合、数据源、Cesium3DTileset、点云或影像图层。也可以传递解析为上述类型之一的 promise。 |
offset |
HeadingPitchRange | optional 局部东北天参考帧中相对于实体中心的偏移。 |
Returns:
解析为 true 表示缩放成功，或 false 表示目标当前未在场景中可视化或缩放被取消的 Promise。
Type Definitions
Viewer 构造函数的初始化选项
Properties:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
animation |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 Animation 控件。 |
baseLayerPicker |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 BaseLayerPicker 控件。 |
fullscreenButton |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 FullscreenButton 控件。 |
vrButton |
boolean |
<optional> |
false | 如果设置为 true，将创建 VRButton 控件。 |
geocoder |
boolean | IonGeocodeProviderType | Array.<GeocoderService> |
<optional> |
IonGeocodeProviderType.DEFAULT | 搜索 Geocoder 控件时使用的地理编码服务。如果设置为 false，将不会创建 Geocoder 控件。 |
homeButton |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 HomeButton 控件。 |
infoBox |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 InfoBox 控件。 |
sceneModePicker |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 SceneModePicker 控件。 |
selectionIndicator |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 SelectionIndicator 控件。 |
timeline |
boolean |
<optional> |
true | 如果设置为 false，将不会创建 Timeline 控件。 |
navigationHelpButton |
boolean |
<optional> |
true | 如果设置为 false，将不会创建导航帮助按钮。 |
navigationInstructionsInitiallyVisible |
boolean |
<optional> |
true | 如果为 true，导航说明初始可见；如果为 false，则在用户显式单击按钮之前不会显示。 |
scene3DOnly |
boolean |
<optional> |
false | 当为 true 时，每个几何实例将仅在 3D 中渲染以节省 GPU 内存。 |
shouldAnimate |
boolean |
<optional> |
false | 如果为 true，时钟默认会尝试推进模拟时间，否则为 false。此选项优先于设置 Viewer#clockViewModel。 |
clockViewModel |
ClockViewModel |
<optional> |
new ClockViewModel(clock) | 用于控制当前时间的时钟视图模型。 |
selectedImageryProviderViewModel |
ProviderViewModel |
<optional> |
当前基础影像图层的视图模型，如果未提供则使用第一个可用的基础图层。此值仅在 `baseLayerPicker` 设置为 true 时有效。 | |
imageryProviderViewModels |
Array.<ProviderViewModel> |
<optional> |
createDefaultImageryProviderViewModels() | 可在 BaseLayerPicker 中选择的 ProviderViewModel 数组。此值仅在 `baseLayerPicker` 设置为 true 时有效。 |
selectedTerrainProviderViewModel |
ProviderViewModel |
<optional> |
当前基础地形图层的视图模型，如果未提供则使用第一个可用的基础图层。此值仅在 `baseLayerPicker` 设置为 true 时有效。 | |
terrainProviderViewModels |
Array.<ProviderViewModel> |
<optional> |
createDefaultTerrainProviderViewModels() | 可在 BaseLayerPicker 中选择的 ProviderViewModel 数组。此值仅在 `baseLayerPicker` 设置为 true 时有效。 |
baseLayer |
ImageryLayer | false |
<optional> |
ImageryLayer.fromWorldImagery() | 应用于 globe 的最底层影像图层。如果设置为 false，则不会添加影像提供器。此值仅在 `baseLayerPicker` 设置为 false 时有效。当 `globe` 设置为 false 时不能使用。 |
ellipsoid |
Ellipsoid |
<optional> |
Ellipsoid.default | 默认椭球体。 |
terrainProvider |
TerrainProvider |
<optional> |
new EllipsoidTerrainProvider() | 要使用的地形提供器。 |
terrain |
Terrain |
<optional> |
处理异步地形提供器的地形对象。仅在 options.terrainProvider 未定义时可以指定。 | |
skyBox |
SkyBox | false |
<optional> |
用于渲染星空的天穹。当 undefined 且使用 WGS84 椭球体时，使用默认星空。如果设置为 false，则不会添加天穹、太阳或月亮。 |
|
skyAtmosphere |
SkyAtmosphere | false |
<optional> |
蓝天和地球边缘的光晕。使用 WGS84 椭球体时启用。设置为 false 可关闭。 |
|
fullscreenElement |
Element | string |
<optional> |
document.body | 按下全屏按钮时进入全屏模式的元素或 id。 |
useDefaultRenderLoop |
boolean |
<optional> |
true | 如果为 true，此控件将控制渲染循环，否则为 false。 |
targetFrameRate |
number |
<optional> |
使用默认渲染循环时的目标帧率。 | |
showRenderLoopErrors |
boolean |
<optional> |
true | 如果为 true，此控件将在发生渲染循环错误时自动向用户显示包含错误的 HTML 面板。 |
useBrowserRecommendedResolution |
boolean |
<optional> |
true | 如果为 true，使用浏览器推荐的分辨率并忽略 window.devicePixelRatio。 |
automaticallyTrackDataSourceClocks |
boolean |
<optional> |
true | 如果为 true，此控件将自动跟踪新添加的 DataSources 的时钟设置，在 DataSource 的时钟更改时更新。如果要独立配置时钟，请将其设置为 false。 |
contextOptions |
ContextOptions |
<optional> |
传递给 Scene 的上下文和 WebGL 创建属性。 |
|
sceneMode |
SceneMode |
<optional> |
SceneMode.SCENE3D | 初始场景模式。 |
mapProjection |
MapProjection |
<optional> |
new GeographicProjection(options.ellipsoid) | 在 2D 和哥伦布视图模式下使用的地图投影。 |
globe |
Globe | false |
<optional> |
new Globe(options.ellipsoid) | 场景中使用的 globe。如果设置为 false，则不会添加 globe，且默认隐藏大气层。 |
orderIndependentTranslucency |
boolean |
<optional> |
true | 如果为 true 且配置支持，使用顺序无关的半透明。 |
creditContainer |
Element | string |
<optional> |
包含 CreditDisplay 的 DOM 元素或 id。如果未指定，则添加到控件本身的底部。 |
|
creditViewport |
Element | string |
<optional> |
包含 CreditDisplay 创建的信用弹出窗口的 DOM 元素或 id。如果未指定，它将出现在控件本身上方。 |
|
dataSources |
DataSourceCollection |
<optional> |
new DataSourceCollection() | 控件可视化的数据源集合。如果提供了此参数，则假定该实例由调用者拥有，且在销毁 viewer 时不会被销毁。 |
shadows |
boolean |
<optional> |
false | 确定光源是否投射阴影。 |
terrainShadows |
ShadowMode |
<optional> |
ShadowMode.RECEIVE_ONLY | 确定地形是否从光源投射或接收阴影。 |
mapMode2D |
MapMode2D |
<optional> |
MapMode2D.INFINITE_SCROLL | 确定 2D 地图是否可旋转或是否可在水平方向无限滚动。 |
projectionPicker |
boolean |
<optional> |
false | 如果设置为 true，将创建 ProjectionPicker 控件。 |
blurActiveElementOnCanvasFocus |
boolean |
<optional> |
true | 如果为 true，单击 viewer 画布时活动元素将失焦。将此设置为 false 适用于单击画布仅用于获取位置或实体数据而不意味着将画布设置为活动元素的情况。 |
requestRenderMode |
boolean |
<optional> |
false | 如果为 true，仅在场景变化需要时渲染帧。启用可减少应用程序的 CPU/GPU 使用率并节省移动设备电量，但在此模式下需要使用 Scene#requestRender 显式渲染新帧。这在 API 其他部分修改场景后通常是必要的。参见 Improving Performance with Explicit Rendering。 |
maximumRenderTimeChange |
number |
<optional> |
0.0 | 如果 requestRenderMode 为 true，此值定义触发渲染请求的最大模拟时间变化。参见 Improving Performance with Explicit Rendering。 |
depthPlaneEllipsoidOffset |
number |
<optional> |
0.0 | 调整 DepthPlane 以解决椭球零高程以下的渲染问题。 |
msaaSamples |
number |
<optional> |
4 | 如果提供，此值控制多采样抗锯齿的速率。典型的多采样率为每像素 2、4，有时为 8 个样本。较高的 MSAA 采样率可能影响性能以换取改进的视觉质量。此值仅适用于支持多采样渲染目标的 WebGL2 上下文。设置为 1 禁用 MSAA。 |
为 Viewer 实例添加额外功能的函数。
| Name | Type | Description |
|---|---|---|
Viewer |
Viewer | 实例。 |
options |
object | 要传递给 mixin 函数的选项对象。 |