Viewer - SuperMap3D Documentation

new SuperMap3D.Viewer(container, options)

Viewer是用于构建应用程序的基础部件，它将所有标准的SuperMap3D部件组合成一个可重复使用的包。 viewer部件通常可以利用mixin来扩展，以此增加对各种应用程序有用的功能函数。

Name Type Description

container Element | String 指定容纳viewer部件的HTML元素的文档对象模型（DOM）或ID。

options

Object

optional 具有以下属性的对象:

Name	Type	Default	Description
`clock`	Clock	`new Clock()`	optional 用于控制当前时间的时钟。
`selectedImageryProviderViewModel`	ProviderViewModel		optional 当前基础图像图层的视图模型，如若未提供，则使用第一个可用基础图层。此值仅在 options.baseLayerPicker 设置为true时有效。
`imageryProviderViewModels`	Array.<ProviderViewModel>	`createDefaultImageryProviderViewModels()`	optional ProviderViewModels数组可从BaseLayerPicker中选择。此值仅在 options.baseLayerPicker 设置为true时有效。
`selectedTerrainProviderViewModel`	ProviderViewModel		optional 当前基础地形图层的视图模型，如若未提供，则使用第一个可用基础图层。此值仅在 options.baseLayerPicker 设置为true时有效。
`terrainProviderViewModels`	Array.<ProviderViewModel>	`createDefaultTerrainProviderViewModels()`	optional ProviderViewModels数组可从BaseLayerPicker中选择。此值仅在 options.baseLayerPicker 设置为true时有效。
`imageryProvider`	ImageryProvider	`new BingMapsImageryProvider()`	optional 使用的影像提供者。此值仅在 options.baseLayerPicker 设置为 false 时有效。
`terrainProvider`	TerrainProvider	`new EllipsoidTerrainProvider()`	optional 使用的地形提供者。
`skyBox`	SkyBox		optional 用于渲染星辰的天空盒，未定义时，使用默认星辰效果。
`skyAtmosphere`	SkyAtmosphere		optional 环绕地球边缘的蓝天和光晕效果，设置为false可将其关闭。
`useDefaultRenderLoop`	Boolean	`true`	optional 如果此部件能够控制渲染循环，设置为true，反之设置为false。
`targetFrameRate`	Number		optional 使用默认渲染循环时的目标帧速率。
`showRenderLoopErrors`	Boolean	`true`	optional 如果设置为true，发生渲染循环错误时，将自动给用户显示一个包含错误信息的HTML面板。
`automaticallyTrackDataSourceClocks`	Boolean	`true`	optional 如果设置为true，将自动跟踪新添加数据源的时钟设置，如果数据源的时钟变更，则更新。如需单独设置时钟，请将此项设置为false。
`contextOptions`	ContextType		optional Context and WebGL 创建属性与传递给`Scene`匹配的选项。增加硬件反走样功能，反走样系数msaalevel使用1到8的整数值，默认是1，值越大反走样效果越好（因为用到了WebGL2.0的特性，所以requestWebgl2参数设置为true。）
`mapProjection`	MapProjection	`new GeographicProjection()`	optional 在二维和Columbus视图模式下所使用的地图投影。
`globe`	Globe	`new Globe(mapProjection.ellipsoid)`	optional 场景中的地球，如果此项设置为false，将不添加球体对象。
`orderIndependentTranslucency`	Boolean	`true`	optional 如果此项设置为true，并且使用设备支持，将使用与顺序无关的半透明。
`creditContainer`	Element \| String		optional 指定包含`CreditDisplay`信息的DOM元素或ID。如若未指定，credit信息将添加到部件底部。
`dataSources`	DataSourceCollection	`new DataSourceCollection()`	optional 指定由viewer部件可视化的数据源集合。如果提供此参数，实例由调用者拥有，并且viewer被销毁时此实例不被销毁。
`terrainExaggeration`	Number	`1.0`	optional 用于夸大地形的标量。请注意，设置地形夸张不会修改其它任何数据。
`shadows`	Boolean	`false`	optional 确定阴影是否由太阳投射形成。
`terrainShadows`	ShadowMode	`ShadowMode.RECEIVE_ONLY`	optional 确定地形是否投射或接受来自太阳的阴影。
`mapMode2D`	MapMode2D	`MapMode2D.INFINITE_SCROLL`	optional 确定二维地图是可旋转的或是可以在在水平方向上无限滚动。
`navigation`	Boolean	`false`	optional 是否显示导航罗盘控件。如需显示，需在初始化viewer时此项设置为true。

Throws:

DeveloperError : 文档中不存在具有该标识的"container"元素。
DeveloperError : 在使用BaseLayerPicker部件时，options.imageryProvider不可用，请更改为指定options.selectedImageryProviderViewModel。
DeveloperError : 在使用BaseLayerPicker部件时，options.terrainProvider不可用，请更改为指定options.selectedTerrainProviderViewModel。
DeveloperError : 在使用BaseLayerPicker部件时，options.selectedImageryProviderViewModel不可用，请更改为指定options.imageryProvider。
DeveloperError : 在使用BaseLayerPicker部件时，options.selectedTerrainProviderViewModel不可用，请更改为指定options.terrainProvider 。

Example:

//初始化viewer部件
var viewer = new SuperMap3D.Viewer('Container', {
    //使用 STK World Terrain
    terrainProvider : new SuperMap3D.SuperMapTerrainProvider({
        url : 'https://assets.agi.com/stk-terrain/world'
    }),
    //使用OpenStreetMaps
    imageryProvider : SuperMap3D.createOpenStreetMapImageryProvider({
        url : 'https://a.tile.openstreetmap.org/'
    }),
});

//添加基础拖放功能
viewer.extend(SuperMap3D.viewerDragDropMixin);

//处理删除文件时遇到错误，显示弹出式警告。
viewer.dropError.addEventListener(function(dropHandler, name, error) {
    console.log(error);
    window.alert(error);
});

See:

Members

allowDataSourcesToSuspendAnimation : Boolean

获取或设置数据源是否可以暂时暂停动画，以避免向用户显示不完整的图片。例如，假如后台正在处理异步函数，在几何图形准备就绪前，时钟不会前进。

readonlyanimation : Animation

获取动画(Animation)部件。

readonlybaseLayerPicker : BaseLayerPicker

获取基础图层拾取器(BaseLayerPicker)对象。

readonlybottomContainer : Element

获取窗口底部包含CreditDisplay及其他潜在信息的DOM元素。

readonlycamera : Camera

获取相机(camera)对象。

readonlycanvas : Canvas

获取画布(canvas)对象。

readonlyclock : Clock

获取时钟(clock)对象。

readonlyclockViewModel : ClockViewModel

获取时钟视图模型。

readonlycontainer : Element

获取父容器。

readonlydataSourceDisplay : DataSourceDisplay

获取用于DataSource的显示。

readonlydataSources : DataSourceCollection

获取或设置将要被可视化的数据源DataSource实例集合。

readonlyentities : EntityCollection

获取与特定数据源无关的实体集合。这是访问dataSourceDisplay.defaultDataSource.entities的快捷方式。

readonlyfullscreenButton : FullscreenButton

获取全屏按钮(FullscreenButton)对象。

readonlygeocoder : Geocoder

获取地理编码器(Geocoder)对象。

readonlyhomeButton : HomeButton

获取主页按钮(HomeButton)对象。

readonlyimageryLayers : ImageryLayerCollection

获取将在地球上渲染的影像图层集合。

readonlyinfoBox : InfoBox

获取信息框(InfoBox)对象。

readonlynavigationHelpButton : NavigationHelpButton

获取导航帮助按钮(NavigationHelpButton)对象。

readonlyprojectionPicker : ProjectionPicker

获取投影拾取器。

resolutionScale : Number

获取或设置渲染分辨率的缩放因子。值小于1.0时能够在不太强大的设备上提高性能；相反，值大于1.0时将会以更高分辨率渲染，然后按比例缩小，以此提高视觉保真度。例如窗口部件以640x480的大小布设，将此属性设置为0.5，将导致场景以320x240分辨率渲染，场景按比例放大，而将其设置为2.0将导致场景以1280x960渲染，场景按比例缩小。

Default Value: 1.0

readonlyscene : Scene

获取场景(scene)对象。

readonlysceneModePicker : SceneModePicker

获取场景模式拾取器(SceneModePicker)对象。

readonlyscreenSpaceEventHandler : ScreenSpaceEventHandler

获取屏幕空间事件处理程序。

selectedEntity : Entity

获取或设置为其显示选择指示符的对象实例。

readonlyselectedEntityChanged : Event

获取选择实体对象变化时引发的事件。

readonlyselectionIndicator : SelectionIndicator

获取选择指示符(SelectionIndicator)对象。

readonlyshadowMap : ShadowMap

获取场景的阴影地图。

shadows : Boolean

确定阴影是否由太阳投射形成。

targetFrameRate : Number

当useDefaultRenderLoop设置为true时，获取或设置部件的目标帧速率。如果未定义此属性，由浏览器的requestAnimationFrame实现确定帧速率；如果已定义此属性，该值应大于0，并且大于底层requestAnimationFrame的值将不起作用。

terrainProvider : TerrainProvider

为地球提供表面几何图形的地形提供者(TerrainProvider)对象。

terrainShadows : ShadowMode

确定地形是否投射或接受来自太阳的阴影。

readonlytimeline : Timeline

获取时间轴(Timeline)部件。

trackedEntity : Entity

获取或设置当前由相机跟踪的实体实例。

readonlytrackedEntityChanged : Event

获取跟踪实体对象变化时引发的事件。

useDefaultRenderLoop : Boolean

获取或设置部件是否能够控制渲染循环。

设置为true时，部件将使用requestAnimationFrame来执行渲染和调整部件大小，以及驱动时钟模拟；设置为false时，则必须手动调用render、resize方法来作为自定义循环渲染的一部分。

如果渲染期间发生错误，将触发Scene的renderError事件，并且此属性将更改为false，错误发生后此属性必须改回true才能继续渲染。

readonlyvrButton : VRButton

获取VRButton对象。

readonlyWidget : Widget

获取Widget对象。

Methods

destroy()

释放对象占用的资源。

extend(mixin, options)

使用提供的mixin来扩展基础viewer功能。 mixin 可以向提供的viewer实例增加额外的属性、功能或者其他行为。

Name	Type	Description
`mixin`	Viewer~ViewerMixin	指定将要被添加到实例的Viewer mixin对象。
`options`	Object	optional 指定传递给mixin函数的options对象。

See:

viewerDragDropMixin

flyTo(target, options) → Promise.<Boolean>

相机飞向指定的实体、实体集或数据源。如果数据源仍在加载中，或者可视化仍在进行，此方法在执行飞行前需等待数据准备就绪。

offset变量由在局部“东-北-上”参考系（中心点为包围球中心）中的“方位角/俯仰角/范围”表示。方位角和俯仰角的角度在局部“东-北-上”参考系中定义。方位角heading是从y轴开始并朝向x轴增加的角度值。俯仰角pitch是从xy平面开始的旋转角度，俯仰角为正表示位于平面上方，为负表示位于平面下方。距离range表示距中心点的距离，如果range为0，则将计算一个范围使得整个包围球可见。

在二维中必须有自上而下的视图。相机位于俯视目标上方。range为在目标上方的高度；headingy由偏移量确定，若不能根据偏移量确定方位角，heading为北方向。

Name Type Description

options

Object

optional 对象具有以下属性:

Name	Type	Default	Description
`duration`	Number	`3.0`	optional 飞行持续时间（以秒为单位）。
`maximumHeight`	Number		optional 飞行中的最大高度。
`offset`	HeadingPitchRange		optional 在以目标为中心的局部“东-北-上”参考系中，距离目标的偏移量。

Returns:

飞行成功时，promise被解析为true；如果实体未在场景中可视化或飞行取消，promise被解析为false。

forceResize()

强制重调，使得部件重新考虑包括部件大小、credit放置等布局。

isDestroyed() → Boolean

返回是否释放对象占用的资源。

Returns:

true表示已释放占用资源，否则返回false。

render()

渲染场景。除非useDefaultRenderLoop设置为false，否则将自动调用此函数。

resize()

调整部件大小以匹配容器。此函数将根据需求自动调用，除非useDefaultRenderLoop 设置为false。

zoomTo(target, offset) → Promise.<Boolean>

异步设置相机，以查看指定的实体、实体集或数据源。如果数据源仍在加载中，或者可视化仍在进行，此方法在执行缩放前需等待数据准备就绪。

在二维中必须有自上而下的视图。相机位于俯视目标的上方。range 为在目标上方的高度；heading有偏移量确定，不然不能根据偏移量确定方位角，heading为北方向。

Name	Type	Description
`target`	Entity \| Array.<Entity> \| EntityCollection \| DataSource \| ImageryLayer \| Promise.<(Entity\|Array.<Entity>\|EntityCollection\|DataSource\|ImageryLayer)>	指定要查看的实体、实体集、数据源或影像图层。还可以指定一个promise来解析前述类型之一。
`offset`	HeadingPitchRange	optional 指定距局部“东-北-上”参考系中心的偏移量。

Returns:

缩放成功时，promise被解析为true；如果实体未在场景中可视化或缩放取消，promise被解析为false。

Type Definitions

ViewerMixin(viewer, options)

增加具有附加功能的Viewer实例的函数。

Name	Type	Description
`viewer`	Viewer	viewer实例对象。
`options`	Object	传递给mixin函数的options对象。

See:

Viewer#extend