MapView

• 概览
• 使用视图
• 程序化导航
• MapView 导航
• 使用 Gamepad 和 3DConnexion 设备进行 MapView 导航
• Handling 事件

概览

MapView 显示 Map 实例的 2D 视图。必须创建 MapView 的实例以在 2D 中渲染 Map (连同其业务图层和基础图层)。要以 3D 形式渲染地图及其图层，请参阅 SceneView 文档。有关视图的一般概述，请参阅 View。

为了使地图在 DOM 中对用户可见，必须创建一个 MapView 并至少引用两个对象：Map 实例和 DOM 元素。每个对象都分别在 map 和 container 属性中设置。

// Create a MapView instance (for 2D viewing)
const view = new MapView({
  map: myMap,  // References a Map instance
  container: "viewDiv"  // References the ID of a DOM element
});

使用视图

MapView 除了负责 Map 及其元素的渲染外，还处理用户与地图之间的交互。例如，传统的地图比例尺没有在 Map 上设置；而是在 MapView 上设置的。

view.scale = 24000; // Sets a 1:24,0000 scale on the view

MapView 在构建后可能不会立即准备好显示。例如，可能需要首先加载地图数据以确定视图的 spatialReference，或者 DOM 容器可能还没有非零大小。许多视图方法 (例如，hitTest 或 goTo) 需要准备好视图才能使用。

.when() 可以调用 MapView 实例上的 方法来执行只能在地图加载后运行的进程。

view.when(function() {
  // MapView is now ready for display and can be used. Here we will
  // use goTo to view a particular location at a given zoom level and center
  view.goTo({
    center: [-112, 38],
    zoom: 12
  });
})
.catch(function(err) {
  // A rejected view indicates a fatal error making it unable to display.
  // Use the errback function to handle when the view doesn't load properly
  console.error("MapView rejected:", err);
});

有关 view.when() 的实时示例，请参阅如何在 SceneView 中添加 2D 概视图示例。

程序化导航

您可通过使用 center 和 scale 或 zoom 的组合，或者通过在 MapView 的构造函数中设置 extent 或 viewpoint 属性来设置初始范围 (或地图的可见部分)。

由于某些视图属性相互覆盖，因此在视图构建期间应用这些属性会有一个优先级设置。初始化时，MapView 需要 center 和 scale，以及可选的 rotation。中心和比例派生自几个属性：center、zoom、scale、extent 或 viewpoint。center 和 scale 均可派生自 extent 和 viewpoint。如果在构造函数中设置了所有属性，它们将按定义的顺序进行应用。例如，比例是从范围派生的，因此在范围之后设置比例会覆盖派生值，而从范围中心派生的中心将保持不变。下表描述了在视图构建期间，哪些属性具有优先级 (被覆盖的属性在构建期间将不起作用)。

属性	覆盖
viewpoint	extent、center、scale、zoom
extent	center、scale、zoom

const view = new MapView({
  map: map,
  container: "viewDiv",
  zoom: 10,
  extent: initialExtent, // will override zoom
  // map will be centered at [0,0], but the scale from initialExtent will be used
  center: [0,0]
});

注：

• 如果在构造函数中设置的 center、extent 或 viewpoint.targetGeometry 的空间参考与视图的 spatialReference 不匹配，则投影引擎将被动态加载。
• 在运行时，将 center、extent 或 viewpoint 设置为与视图空间参考不匹配的空间参考时，必须加载投影引擎。您可以通过调用 projection.isLoaded() 在设置这些属性之前检查投影引擎是否已加载。如果尚未加载，可以调用 projection.load()。

// Create a map with Antarctic imagery basemap
const map = new Map({
  basemap: new Basemap({
    portalItem: {
      id: "6553466517dd4d5e8b0c518b8d6b64cb" // Antarctic Imagery
    }
  });
});

// Set the center and zoom level on the view.
// In this case, the view's spatial reference wkid is 3031
// center is lat/long. Projection engine will be loaded dynamically
// to project the center to match the spatial reference of the view
const view = new MapView({
  map: map,  // References a Map instance
  container: "viewDiv"  // References the ID of a DOM element
  center: [-100, 35], // Sets the center point of the view at a specified lon/lat
  zoom: 3 // MapView converts this to its corresponding scale which is 112823780.660964
});

// Sets the center point of the view at a specified lon/lat
view.center = [-112, 38];
view.zoom = 13;  // Sets the zoom LOD to 13

// new extent for the mapview where the spatialReference.wkid is 4326
const extent = new Extent({
  xmin: -9177882,
  ymin: 4246761,
  xmax: -9176720,
  ymax: 4247967,
  spatialReference: {
    wkid: 102100
  }
});

if (!projection.isLoaded()) {
  // load the projection engine if it is not loaded
  await projection.load();
}
view.extent = extent;

因为 View 可处理用户交互，因此在 MapView 上处理 click 等事件。动画也可使用 goTo() 方法，这允许您将 MapView 从一个范围更改或移动到另一个范围。

缩放和 LODs

为什么设置 MapView.zoom 不总是有效的，为什么它的值为 -1？该部分解释了 MapView 缩放和 LOD 的工作原理。地图的 basemap 定义了加载视图时 MapView 的 effectiveLODs。LOD 具有可用于导航地图的 scale 和相应的 zoom 值。如果 MapView 具有有效的 effectiveLODs，则可以在 MapView 上设置缩放值。在这种情况下，视图将其转换为相应的比例，或者如果缩放为小数，则对其进行插值。

如果以下语句为真，则 MapView 的 constraints.effectiveLODs 将为 null：

• 地图没有底图，或
• 底图没有 TileInfo，
• 且添加到地图的第一个图层没有 TileInfo。

如果 effectiveLODs 为 null，则无法在 MapView 上设置 zoom，因为无法进行转换。在这种情况下，缩放值将是 -1。设置比例将可用。为解决此问题，可在初始化时通过调用 TileInfo.create().lods 来定义 MapView 的 constraints.lods。

const layer = new FeatureLayer({
  url: " "
});

// initialize the map without basemap, just add the feature layer to the map
// feature layer does not have tileInfo to derive effectiveLODs from
const map = new Map({
  layers: [layer]
});

// Create a tileInfo instance using the default settings and pass its
// resulting LODs to a MapView's constraints.lods.
const view = new MapView({
  container: "viewDiv",
  map: map,
  zoom: 3, // this will work because we are creating LODs. Otherwise, it will not work
  constraints: {
    lods: TileInfo.create({
      // create the LODs to match the spatial reference of the view
      spatialReference: viewSpatialReference
    }).lods
  },
  spatialReference: viewSpatialReference
});

MapView 导航

MapView 导航默认启用，包括鼠标交互，如下表所述。

操作	MapView 行为
拖动	平移
双击	放大光标
Ctrl+双击	缩小光标
向前滚动	放大光标
向后滚动	缩小光标
右键单击+拖动	2D 旋转
Shift+左键单击+拖动	缩放到绘制图形的范围
方向键	向左、向右、向上或向下微移视图
N	调整视图指向北方
A	逆时针旋转视图
D	顺时针旋转视图
+	在地图中心逐渐放大
-	在地图中心逐渐缩小
用一根或多根手指拖动	平移
用一根手指双击缩放	在手指位置平移
两指捏入/捏出	缩小/放大
顺时针或逆时针方向移动两根手指	旋转

要禁用 MapView 导航，您必须对指针的事件对象或触发导航的手势事件调用 stopPropagation() 方法。

有关示例，请参阅禁用视图导航。

使用 Gamepad 和 3DConnexion 设备进行 MapView 导航

当 view.navigation.gamepad.enabled 设置为 true (默认) 时，Gamepad 和 3Dconnexion 设备 (如 SpaceMouse) 可用于导航。要在 MapView 中启用缩放，必须将 view.constraints.snapToZoom 设置为 false (默认为 true)。请参阅 GamepadInputDevice 了解支持的设备。

Gamepad 操作	MapView 行为
左触发器	放大
右触发器	缩小
左摇杆	平移视图
右摇杆	旋转视图

动作图像	SpaceMouse 操作	MapView 行为
	推 (左/右/前/后)	平移视图
	向上拉	缩小
	向下推	放大
	顺时针旋转	顺时针旋转视图
	逆时针旋转	逆时针旋转视图

要禁用 Gamepad 导航，您可以将 view.navigation.gamepad.enabled 设置为 false。

注意：

• 必须禁用缩放捕捉才能进行连续缩放。在 MapView 中，snapToZoom 默认为 true。
  • view.constraints.snapToZoom = false;
• 根据 W3C 工作草案 2020 年 10 月 29 日，如果 web 应用程序托管在不安全的环境 (例如 http 而非 https) 上，则 Gamepad 功能可能无法在部分或全部浏览器上使用。GeoScene Maps SDK for JavaScript 的未来版本可能会在不安全的上下文中显式禁用 Gamepad 功能。

Handling 事件

当用户与 MapView 交互时，他们的操作会触发您可以侦听和响应的事件。例如，您可以侦听用户何时将鼠标移动到地图上，并在鼠标位置处显示坐标。这称为 pointer-move 事件。有关所有事件的列表，请参阅 MapView 事件部分。

需要注意的是，一些事件相互依赖，用户交互的时间会影响触发事件的类型。例如，单击会触发一系列事件：当用户按下鼠标按钮时，会触发 pointer-down，当用户松开鼠标按钮时，会触发 pointer-up。在 pointer-up 事件之后，会立即触发 immediate-click 事件。immediate-click 应该用于无延迟地响应用户交互。只有在确保用户没有第二次点击 (在这种情况下，它会触发 double-click 事件) 后，才会触发 click 事件。

在双击的情况下，第一次单击后重复相同的事件链。但是，如果用户在接近的时间范围内再次点击，则不再触发 click 事件，而是再次触发 pointer-down、pointer-up 和 immediate-click 事件。在两个 immediate-click 事件之后，将触发一个 double-click 以及一个 immediate-double-click 事件。两者之间的区别在于，在 immediate-click 事件上使用 stopPropagation 无法阻止 immediate-double-click，因此可以独立于 immediate-click 事件对双击做出反应。

这些事件也用于内部导航、弹出窗口或不同的交互工具，如测量或草图。在某些用例中，添加额外的事件侦听器可能会干扰默认事件侦听器。例如，添加 immediate-click 事件来打开一个弹出窗口，会干扰同样打开一个弹出窗口的默认 click 事件。

请参阅事件资源管理器示例，以可视化与视图交互时触发的不同事件。

另请参阅

• MapView 简介

• 示例 - 视图内边距

• 示例 - 测地线的缓冲区 (2D & 3D)

• 示例 - 事件浏览/查看属性

• SceneView
• 地图
• ViewAnimation

构造函数

new MapView(properties)

参数

properties Object optional 有关可能传递给构造函数的所有属性的列表，请参见属性。

示例

// Typical usage
let view = new MapView({
  // ID of DOM element containing the view
  container: "viewDiv",
  // Map/WebMap object
  map: new Map()
});

属性概述

属性详细信息

allLayerViews Collection<LayerView> inherited

包含与此视图中的底图、业务图层和图层组相关的所有已创建 LayerViews 的平面列表的集合。

另请参阅

• LayerView

animation ViewAnimation

表示由 goTo() 初始化的正在进行的视图动画。您可以侦听此属性，以通知动画的状态。

另请参阅

• goTo()

示例

view.watch("animation", function(response){
  if(response && response.state === "running"){
    console.log("Animation in progress");
  }
  else{
   console.log("No animation");
  }
});

background ColorBackgroundautocast

起始版本：GeoScene Maps SDK for JavaScript 4.16

MapView 的背景色。如果视图的地图发生更改，则视图的 background 将重置为地图的背景，即使用户之前设置了它也是如此。

默认值：null

示例

let view = new MapView({
  container: "viewDiv",
  map: map,
  background: { // autocasts new ColorBackground()
    color: "magenta" // autocasts as new Color()
  }
});

basemapView BasemapView inherited

表示将单个底图添加到地图后的视图。

breakpoints Object

用于在视图的 height 和 width 上定义断点的便利属性。此处指定的大小可根据视图的大小确定 widthBreakpoint 和 heightBreakpoint 属性的值。

设置断点有助于响应式应用程序设计。它通过侦听宽度和高度断点来实现这一点。这很有帮助，因为它移除了对多个 @media calls 的需要。您可以为视图的 widthBreakpoint 或 heightBreakpoint 属性设置侦听处理器，而不是侦听视图的大小或调整大小属性。

请参阅样式指南以获取有关使用此功能的更多信息。

属性

xsmall Number optional 默认值：544 设置 widthBreakpoint 和 heightBreakpoint 所用的 xsmall 断点，以像素为单位。如果视图的 height 或 width 小于此值，则 widthBreakpoint 或 heightBreakpoint 的值将为 xsmall。

small Number optional 默认值：768 设置 widthBreakpoint 和 heightBreakpoint 所用的 small 断点，以像素为单位。如果视图的 height 或 width 介于此值和 xsmall 属性的值之间，则 widthBreakpoint 或 heightBreakpoint 的值将为 small。

medium Number optional 默认值：992 设置 widthBreakpoint 和 heightBreakpoint 所用的 medium 断点，以像素为单位。如果视图的 height 或 width 介于此值和 small 属性的值之间，则 widthBreakpoint 或 heightBreakpoint 的值将为 medium。

large Number optional 默认值：1200 设置 widthBreakpoint 和 heightBreakpoint 所用的 large 断点，以像素为单位。如果视图的 height 或 width 介于此值和 medium 属性的值之间，则 widthBreakpoint 或 heightBreakpoint 的值将为 large。

xlarge Number optional 设置 widthBreakpoint 和 heightBreakpoint 所用的 xlarge 断点，以像素为单位。如果视图的 height 或 width 大于 large 属性的值，则 widthBreakpoint 或 heightBreakpoint 的值将为 xlarge。

另请参阅

• 示例：使用 CSS 的响应应用程序

• MDN Web 文档：媒体查询

示例

// Instead of watching the size or resizing properties
view.watch(size)
view.watch(resizing)

// Set up a watch handle for breakpoint
view.watch("widthBreakpoint",function(breakpoint){
  switch (breakpoint) {
    case "xsmall":
    // do something
      break;
    case "small":
    case "medium":
    case "large":
    case "xlarge":
    // do something else
      break;
    default:
  }
});

center Pointautocast

自动转换自 Number[]|Object

表示视图的中心点；设置中心时，您可以传递一个 Point 实例或表示经度/纬度对的数字数组 ([-100.4593, 36.9014])。设置中心会立即更改当前视图。有关动画视图，请参阅 goTo()。

返回的 Point 对象始终位于视图的空间参考中，并且可以在内部进行修改。要持久化返回的对象，请使用 Point.clone() 创建一个克隆。

注

• 如果在构造函数中设置的 center 空间参考与视图的 spatialReference 不匹配，则投影引擎将被动态加载。
• 在运行时，将 center 设置为与视图空间参考不匹配的空间参考时，必须加载投影引擎。您可以通过调用 projection.isLoaded() 在设置中心之前检查投影引擎是否已加载。如果尚未加载，可以调用 projection.load()。

另请参阅

• goTo()

示例

// Sets the initial center point of the view to lon/lat coordinates
// lon/lat will be projected to match the spatial reference of the view
let view = new MapView({
  center: [-112, 38]
});

// Updates the view's center point to a pre-determined Point object
let pt = new Point({
  x: 12804.24,
  y: -1894032.09,
  spatialReference: {
    wkid: view.spatialReference  // wkid 2027
  }
});
view.center = pt;

const centerPoint = new Point({
  x: -8746995,
  y: 4352308,
  spatialReference: {
    wkid: 8857
  }
});
if (!projection.isLoaded()) {
  // load the projection engine if it is not loaded
  await projection.load();
}
view.center = centerPoint;

constraints Object

指定可应用于 MapView 的 scale、zoom 和 rotation 约束。如果地图不具有 basemap 或底图没有 tileInfo，则应在 MapView 构造函数中设置 constraints.lods。请参阅缩放和 LOD 部分，了解更多 MapView 的缩放和 LOD 的工作方式。请参阅以下对象规范。

属性

lods LOD[] optional LODs 数组。如果未指定，则从 Map 中读取此值。可以通过 TileInfo.create() 方法生成额外的 LOD。当提供的默认 LOD 数量不足时，这很有用。需要这样做的一个示例是在将视图比例设置为 1:1 时。此外，此属性可能是自动转换的。

geometry Geometry optional 允许用户横向导航的区域。仅支持 Extent 和 Polygon 几何类型。将忽略 Z 值。此属性由交互式 MapView 导航和 goTo() 实现。此属性可能是自动转换的。

minScale Number optional 允许用户在视图内缩放到的最小比例。

maxScale Number optional 允许用户在视图内缩放到的最大比例。将此值设置为 0 允许用户过度缩放图层切片。

minZoom Number optional 允许用户在视图内缩放到的最小缩放级别。

maxZoom Number optional 允许用户在视图内缩放到的最大缩放级别。将此值设置为 0 允许用户过度缩放图层切片。

snapToZoom Boolean optional 默认值：true 当为 true 时，视图在放大或缩小时会捕捉到下一个 LOD。当为 false 时，则进行连续缩放。这不适用于使用两根手指捏合/拉出进行放大/缩小。

rotationEnabled Boolean optional 默认值：true 指示用户是否可以旋转地图。

effectiveLODs LOD[] optional 只读属性，用于指定从 Map 中读取的细节级别 (LOD)。

effectiveMinZoom Number optional 只读属性，用于指定允许用户在视图内缩放到的最小缩放级别。

effectiveMaxZoom Number optional 只读属性，用于指定允许用户在视图内缩放到的最大缩放级别。

effectiveMinScale Number optional 只读属性，用于指定允许用户在视图内缩放到的最小比例。

effectiveMaxScale Number optional 只读属性，用于指定允许用户在视图内缩放到的最大比例。

另请参阅

• TileInfo.create()

• 缩放和 LODs

示例

view.constraints = {
  geometry: { // Constrain lateral movement to Lower Manhattan
    type: "extent",
    xmin: -74.020,
    ymin:  40.700,
    xmax: -73.971,
    ymax:  40.73
  },
  minScale: 500000, // User cannot zoom out beyond a scale of 1:500,000
  maxScale: 0, // User can overzoom tiles
  rotationEnabled: false // Disables map rotation
};

// This snippet shows how to set the MapView scale 1:1 while generating additional LODs for the MapView.constraints.
const spatialReference = new SpatialReference({
  wkid: 2154
});
const center = new Point({
  x: 0,
  y: 0,
  spatialReference
});

// Create LODs from level 0 to 31
const tileInfo = TileInfo.create({
  spatialReference,
  numLODs: 32
});
const lods = tileInfo.lods;

let view = new MapView({
  container: "viewDiv",
  map,
  scale: 1,
  center,
  spatialReference,
  constraints: {
    lods: lods,
    snapToZoom: false
  }
});

container HTMLDivElementautocast inherited

自动转换自 String

表示包含视图的 DOM 元素的 id 或节点。这通常在视图的构造函数中设置。

示例

// Sets container to the DOM id
let view = new MapView({
  container: "viewDiv"  // ID of the HTML element that holds the view
});

// Sets container to the node
let viewNode = document.getElementById("viewDiv");
let view = new SceneView({
  container: viewNode
});

declaredClass Stringreadonly inherited

起始版本：GeoScene Maps SDK for JavaScript 4.7

类的名称。声明的类名称格式化为 geoscene.folder.className。

extent Extentautocast

范围表示视图中地图的可见部分，作为 Extent 的实例。设置范围会立即更改没有动画的视图。要为视图设置动画，请参阅 goTo()。旋转视图时，范围不会更新以包括地图的新可见部分。

返回的 Extent 对象是一个内部引用，可以在内部进行修改。要持久化返回的对象，请使用 Extent.clone() 创建一个副本。

注

• 如果在构造函数中设置的 extent 空间参考与视图的 spatialReference 不匹配，则投影引擎将被动态加载。
• 在运行时，将 extent 设置为与视图空间参考不匹配的空间参考时，必须加载投影引擎。您可以通过调用 projection.isLoaded() 在设置范围之前检查投影引擎是否已加载。如果尚未加载，可以调用 projection.load()。

默认值：null

另请参阅

• goTo()

示例

// the projection engine must be loaded in the app if the spatial reference
// of the view does not match the spatial reference of the extent
const extent = new Extent({
  xmin: -13056650,
  ymin: 6077558,
  xmax: -13055709,
  ymax: 6077938,
  spatialReference: new SpatialReference({wkid:3857})
});
view.extent = extent;  // Updates the view without animation

fatalError Error inherited

起始版本：GeoScene Maps SDK for JavaScript 4.12

当视图丢失其 WebGL 上下文时，返回的致命错误。侦听此属性以正确处理错误并尝试恢复 WebGL 上下文。

另请参阅

• tryFatalErrorRecovery()

示例

view.watch("fatalError", function(error) {
  if(error) {
    console.error("Fatal Error! View has lost its WebGL context. Attempting to recover...");
    view.tryFatalErrorRecovery();
  }
});

floors Collection<string>

起始版本：GeoScene Maps SDK for JavaScript 4.19

在视图上针对一组特定楼层级别应用显示过滤器。它可以通过零个或多个级别 ID 过滤楼层感知型图层上的地图显示。

focused Booleanreadonly inherited

起始版本：GeoScene Maps SDK for JavaScript 4.7

指示浏览器焦点是否在视图上。

graphics Collection<Graphic> inherited

允许将图形直接添加到视图的默认图形中。

另请参阅

• Graphic
• GraphicsLayer

• 图形简介

示例

// Adds a graphic to the View
view.graphics.add(pointGraphic);

// Removes a graphic from the View
view.graphics.remove(pointGraphic);

height Numberreadonly inherited

从视图容器元素中读取的视图高度，以像素为单位。

视图容器的高度需要大于 0 才能显示。

默认值：0

heightBreakpoint String

一个方便的属性，用于指示视图高度的一般大小。此值是根据视图的高度在 breakpoints 属性中定义的范围内的位置确定的。有关可能值列表，请参见下表。使用 breakpoints 属性覆盖默认阈值。

请参阅样式指南以获取有关使用此功能的更多信息。

可能值	描述	默认阈值 (像素)
xsmall	视图的高度小于 xsmall breakpoint 中设置的值。	< 545
small	视图的高度介于 xsmall 和 small breakpoints 中设置的值之间。	545 - 768
medium	视图的高度介于 small 和 medium breakpoints 中设置的值之间。	769 - 992
large	视图的高度介于 medium 和 large breakpoints 中设置的值之间。	993 - 1200
xlarge	视图的高度大于 large breakpoint 中设置的值。	> 1200

可能值："xsmall"|"small"|"medium"|"large"|"xlarge"

示例

view.watch("heightBreakpoint", function(newVal){
  if (newVal === "xsmall"){
    // clear the view's default UI components if
    // app is used on a mobile device
    view.ui.components = [];
  }
});

highlightOptions Objectautocast

起始版本：GeoScene Maps SDK for JavaScript 4.5

用于配置突出显示的选项。在适当的 LayerView 上使用 highlight 方法来突出显示一个要素。

属性

color Color optional 默认值：#00ffff 自动转换自 Object|Number[]|String 高亮填充的颜色。

haloColor Color optional 默认值：null 自动转换自 Object|Number[]|String 高光周围的光晕颜色。如果未提供 haloColor，则晕圈将使用指定的 color 进行着色。

haloOpacity Number optional 默认值：1 高光晕圈的不透明度。这将与 color 中指定的任何不透明度相乘。

fillOpacity Number optional 默认值：0.25 填充的不透明度 (光晕内的区域)。这将与 color 中指定的不透明度相乘。

另请参阅

• FeatureLayerView.highlight()

示例

const view = new MapView({
  map: map,
  highlightOptions: {
    color: [255, 255, 0, 1],
    haloOpacity: 0.9,
    fillOpacity: 0.2
  }
});

input Inputreadonly inherited

起始版本：GeoScene Maps SDK for JavaScript 4.9

用于配置视图输入处理的选项。

示例

// Make gamepad events to emit independently of focus.
view.input.gamepad.enabledFocusMode = "none";

interacting Booleanreadonly inherited

指示是否正在与视图进行交互 (例如在平移或通过交互工具时)。

默认值：false

layerViews Collection<LayerView> inherited

一个集合，其中包含地图中所有已创建业务图层的 LayerViews 的层级结构列表。

另请参阅

• LayerView

magnifier Magnifierreadonly inherited

起始版本：GeoScene Maps SDK for JavaScript 4.19

放大镜允许将视图的一部分显示为视图顶部的放大镜图像。

map Mapautocast inherited

要在视图中显示的 Map 对象的实例。一个视图一次只能显示一张地图。另一方面，一个地图可以同时被多个 MapViews 或 SceneViews 查看。

该属性通常在 MapView 或 SceneView 的构造函数中进行设置。有关演示地图和视图之间关系的示例，请参阅类描述。

navigating Booleanreadonly inherited

指示是否正在导航视图 (例如在平移时)。

默认值：false

navigation Navigation inherited

起始版本：GeoScene Maps SDK for JavaScript 4.9

用于配置视图导航行为的选项。

示例

// Disable the gamepad usage, single touch panning, panning momentum and mouse wheel zooming.
const view = new MapView({
  container: "viewDiv",
  map: new Map({
    basemap: "satellite"
  }),
  center: [176.185, -37.643],
  zoom: 13,
  navigation: {
    gamepad: {
      enabled: false
    },
    browserTouchPanEnabled: false,
    momentumEnabled: false,
    mouseWheelZoomEnabled: false
  }
});

orientation Stringreadonly

指示视图方向的便利属性。有关可能值列表，请参见下表。

请参阅样式指南以获取有关使用此功能的更多信息。

可能值	描述
landscape	视图的宽度大于其高度。
portrait	视图的宽度等于或小于其高度。

可能值："landscape"|"portrait"

padding Object inherited

使用 padding 属性可使 center 和 extent 等在整个视图的一个子部分中起作用。这在将 UI 元素或半透明内容分层放置在视图部分的顶部时特别有用。有关其工作原理，请参阅查看 padding 示例。

属性

left Number optional 左侧内边距 (以像素为单位)。

top Number optional 顶部内边距 (以像素为单位)。

right Number optional 右侧内边距 (以像素为单位)。

bottom Number optional 底部内边距 (以像素为单位)。

默认值：{left: 0, top: 0, right: 0, bottom: 0}

popup Popupautocast inherited

Popup 对象，用于显示 map 中 layers 的一般内容或属性。

该视图具有一个带有预定义样式的默认 Popup 实例和一个用于定义内容的模板。此默认实例中的内容可以直接在弹出窗口的内容或图层的 PopupTemplate 中进行修改。

您可以创建一个新的 Popup 实例，并将其设置为该属性以自定义弹出窗口的样式、位置和内容，以支持在视图上使用默认的弹出窗口实例。

示例

// This syntax prevents any popups from opening and removes them from the application
view.popup = null;

// This syntax disables the click event on the view
view.popup.autoOpenEnabled = false;

ready Booleanreadonly inherited

当为 true 时，此属性指示视图是否成功满足所有依赖项，表示满足以下条件。

• 该视图具有一张地图。如果地图是 WebMap 或 WebScene，则必须加载地图或场景。
• 视图具有一个大于 0 的 container。
• 视图具有 spatialReference、center 和 scale。这些也可通过设置 extent 来推断。

当视图准备就绪时，它将自行解析并调用 when() 中定义的回调，其中代码可以在工作视图上执行。对视图准备情况的相继更改通常会通过查看 view.ready 并为 map 或 container 更改的情况提供逻辑来处理。

默认值：false

另请参阅

• when()

resizeAlign String

定义在调整浏览器窗口大小时保持静止的锚点。默认值 center 可确保视图的中心点在窗口大小发生变化时始终可见。其他选项允许视图的相应部分在窗口大小发生更改时保持可见。

可能值：:"center"|"left"|"right"|"top"|"bottom"|"top-left"|"top-right"|"bottom-left"|"bottom-right"

默认值：center

resizing Booleanreadonly inherited

指示视图是否正在调整大小。

默认值：false

resolution Numberreadonly

起始版本：GeoScene Maps SDK for JavaScript 4.9

以地图单位表示一个像素的大小。分辨率的值可以通过将范围宽度除以视图的宽度来得到。

rotation Number

正北方向相对于视图顶部的顺时针旋转 (以度为单位)。可以通过直接设置旋转或使用以下鼠标事件来旋转视图：Right-click + Drag。可以通过将约束中的 rotationEnabled 属性设置为 false 来禁用地图旋转。有关此示例，请参阅以下代码片段。

默认值：0

示例

// Due north is rotated 90 degrees, pointing to the right side of the view
view.rotation = 90;

// Due north is rotated 180 degrees, pointing to the bottom of the view
view.rotation = 180;

// Due north is rotated 270 degrees, pointing to the left side of the view
view.rotation = 270;

// Due north is rotated 0 degrees, pointing to the top of the view (the default)
view.rotation = 0; // 360 or multiple of 360 (e.g. 720) works here as well.

// Disables map rotation
view.constraints = {
  rotationEnabled: false
};

scale Number

表示位于视图中心的地图比例尺。设置比例会立即更改视图。有关动画视图，请参阅 goTo()。

另请参阅

• goTo()

• 缩放和 LODs

示例

view.scale = 24000;  // Sets the map scale in the view's center to 1:24,000

size Number[]readonly inherited

表示视图宽度和高度的数组，以像素为单位，例如 [width, height]。

spatialReference SpatialReferenceautocast

视图的空间参考。这表示用于在地图中定位地理要素的投影坐标系或地理坐标系。从版本 4.23 开始，您可以在初始化 MapView 后通过直接更改此属性或通过从 BasemapGallery 或 BasemapToggle 微件更改底图来更改 MapView 的 spatialReference。将 spatialReferenceLocked 属性设置为 true 以防止用户在运行时更改视图的空间参考。

在更改空间参考之前，可通过调用 projection.isLoaded() 检查投影引擎是否已加载。如果尚未加载，请调用 projection.load() 方法。如果未加载投影引擎，则视图中心在视图的新空间参考中将默认为 [0, 0]，并且将抛出控制台错误。

注

• 不显示与视图空间参考不相兼容的 LayerViews。在这种情况下，图层视图的 suspended 属性为 true，spatialReferenceSupported 属性为 false。

• 设置视图的空间参考时，center、extent 或 viewpoint.targetGeometry 属性将投影到新的空间参考。调整 scale 和 rotation 属性以使地图的内容在屏幕上保持相同的大小和方向。

• 为确保 TileLayers 和 VectorTileLayers 在 basemap 中正确显示，必须将 MapView 的 spatialReference 设置为与其 tileInfo 的空间参考相匹配。

• 不支持使用 imageCoordinateSystem 切换空间参考。

默认值：null

另请参阅

• spatialReferenceLocked

示例

// check if the projection engine is loaded
if (!projection.isLoaded()) {
  // load the projection engine if it is not loaded
  projection.load().then(() => {
   // change the spatial reference of the view to equal earth projection
    view.spatialReference = new SpatialReference({
      wkid: 54035 //equal earth projection
    });
  });
} else {
  // the projection engine is already loaded.
  // change the spatial reference of the view to equal earth projection
  view.spatialReference = new SpatialReference({
    wkid: 54035 //equal earth projection
  });
}

const basemap = await changeBasemap();
const spatialReference = await findSpatialReference(basemap);

// check if basemap has the same spatial reference as the view if they are not equal
// then check if the projection engine is loaded. load the projection engine if it is not loaded.
// If loaded, then simply change view.spatialReference to match the basemap spatialReference
if (spatialReference && !view.spatialReference.equals(spatialReference)) {
  if (!projection.isLoaded()) {
    // load the projection engine if it is not loaded
    await projection.load();
  }
  view.spatialReference = spatialReference;
}

// change the basemap
map.basemap = basemap;

async function changeBasemap() {
  let basemap;
  if (map.basemap.title === "OpenStreetMap Vector Basemap (Blueprint - WGS84)"){
    basemap = new Basemap({
      portalItem: { // Spilhaus - one ocean basemap
        id: " "
      }
    });
  } else {
    basemap = osm84;
  }
  return basemap;
}

async function findSpatialReference(basemap) {
  await basemap.load();

  if (basemap.spatialReference) {
    return basemap.spatialReference;
  }

  const layer = basemap.baseLayers.at(0);

  if (!layer) {
    return null;
  }

  await layer.load();

  return layer.spatialReference;
}

spatialReferenceLocked Boolean

起始版本：GeoScene Maps SDK for JavaScript 4.23

指示 MapView 的 spatialReference 在初始化后是否可以更改。默认值为 false，表示视图的 spatialReference 可以在运行时更改。当为 true 时，具有与 MapView 的空间参考不匹配的空间参考的 basemaps 将在 BasemapGallery 和 BasemapToggle 微件中被禁用，并且视图 spatialReference 不能在运行时更改。

默认值：false

另请参阅

• spatialReference

stationary Booleanreadonly inherited

指示视图是否处于动画化、导航或调整大小的状态。

suspended Booleanreadonly inherited

指示视图在页面上是否可见。当为 true 时，视图不可见并且停止渲染和更新数据。当满足以下条件之一时，设置为 true：

• 如果视图没有 container，
• 如果视图的 height 或 width 等于 0，
• 如果视图容器的 css 样式 display 设置为 none (display:none)。

当视图容器的 css 样式 visibility 设置为 hidden 时，该属性设置为 false，视图被隐藏但仍会渲染和更新数据。

默认值：true

timeExtent TimeExtentautocast inherited

起始版本：GeoScene Maps SDK for JavaScript 4.12

视图的时间范围。时间感知型图层显示其在视图时间范围内的时态数据。设置视图的时间范围与设置空间范围类似，因为一旦设置了时间范围，视图就会自动更新以适应变化。

默认值：null

示例

// Create a csv layer from an online spreadsheet.
let csvLayer = new CSVLayer({
  url: " ",
  timeInfo: {
    startField: "SaleDate" // The csv field contains date information.
  }
});

// Create a mapview showing sales for the last week of March 2019 only.
let view = new MapView({
  map: map,
  container: "viewDiv",
  timeExtent: {
    start: new Date("2019, 2, 24"),
    end:   new Date("2019, 2, 31")
  }
});

type Stringreadonly

视图的维度。

对于 MapView，类型总是 "2d"。

ui DefaultUIautocast inherited

公开视图中可用的默认微件，并允许您打开和关闭它们。有关更多详情，请参阅 DefaultUI。

示例

let toggle = new BasemapToggle({
  view: view,
  nextBasemap: "hybrid"
});
// Adds an instance of BasemapToggle widget to the
// top right of the view.
view.ui.add(toggle, "top-right");

// Moves the zoom and BasemapToggle widgets to the
// bottom left of the view.
view.ui.move([ "zoom", toggle ], "bottom-left");

// Removes all the widgets from the bottom left of the view
view.ui.empty("bottom-left");

// Removes the compass widget from the view
view.ui.remove("compass");

// Removes all default UI components, except Attribution.
// Passing an empty array will remove all components.
view.ui.components = [ "attribution" ];

updating Booleanreadonly inherited

指示是通过对网络发送附加数据请求，还是通过处理接收到的数据来更新视图。

默认值：false

viewpoint Viewpoint

将当前视图表示为视图上的 Viewpoint 或观察点。设置视点会立即更改当前视图。有关动画视图，请参阅 goTo()。

返回的 Viewpoint 对象是一个内部引用，可以在内部进行修改。要持久化返回的对象，请使用 Viewpoint.clone() 创建一个副本。

注

• 如果在构造函数中设置的 viewpoint 空间参考与视图的 spatialReference 不匹配，则投影引擎将被动态加载。
• 在运行时，将 viewpoint.targetGeometry 设置为与视图 spatialReference 不匹配的空间参考时，必须加载投影引擎。您可以通过调用 projection.isLoaded() 在设置 viewpoint.targetGeometry 之前检查投影引擎是否已加载。如果尚未加载，可以调用 projection.load()。

另请参阅

• goTo()

width Numberreadonly inherited

从视图容器元素中读取的视图宽度，以像素为单位。

视图容器的宽度需要大于 0 才能显示。

默认值：0

widthBreakpoint String

一个方便的属性，用于指示视图宽度的一般大小。此值是根据视图的宽度在 breakpoints 属性中定义的范围内的位置确定的。有关可能值列表，请参见下表。使用 breakpoints 属性覆盖默认阈值。

请参阅样式指南以获取有关使用此功能的更多信息。

可能值	描述	默认阈值 (像素)
xsmall	视图的宽度小于 xsmall breakpoint 中设置的值。	< 545
small	视图的宽度介于 xsmall 和 small breakpoints 中设置的值之间。	545 - 768
medium	视图的宽度介于 small 和 medium breakpoints 中设置的值之间。	769 - 992
large	视图的宽度介于 medium 和 large breakpoints 中设置的值之间。	993 - 1200
xlarge	视图的宽度大于 large breakpoint 中设置的值。	> 1200

可能值："xsmall"|"small"|"medium"|"large"|"xlarge"

示例

view.watch("widthBreakpoint", function(newVal){
  if (newVal === "xsmall"){
    // clear the view's default UI components if
    // app is used on a mobile device
    view.ui.components = [];
  }
});

zoom Number

表示视图中心的细节级别 (LOD)。缩放级别或比例是一个数字，用于定义地图内容在地图视图中显示的大小。缩放级别通常是介于 0 (全局视图) 和 23 (非常详细的视图) 之间的数字，用作预定比例值的简写。值 -1 表示视图没有 LOD。设置缩放值时，地图视图将其转换为相应的比例，或者如果缩放为小数，则对其进行插值。MapView 可以在全比例范围内显示具有不同投影的地图，因此使用比例而不是缩放级别。

设置缩放会立即更改当前视图。有关动画视图，请参阅 goTo()。将此属性与 center 一起设置是设置视图初始范围的便捷方法。

另请参阅

• goTo()

• 了解 MapView lods

示例

view.zoom = 3;  // Sets the LOD to 3 (small map scale)
view.zoom = 18; // Sets the LOD to 18 (large map scale)

// Set the zoom level and center in the constructor
let view = new MapView({
  zoom: 10,
  center: [-120, 34],
  map: map
});

方法概述

方法详细说明

addHandles(handleOrHandles, groupKey)inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

添加一个或多个与对象的生命周期相关联的句柄。当对象被销毁时，将移除句柄。

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);

参数

handleOrHandles WatchHandle|WatchHandle[] 对象销毁后，标记为要移除的句柄。

groupKey * optional 标识句柄应添加到的组的键。组中的所有句柄稍后都可使用 Accessor.removeHandles() 进行删除。如果未提供键，则句柄将被添加到默认组。

destroy()inherited

起始版本：GeoScene Maps SDK for JavaScript 4.17

销毁视图和任何相关资源，包括其 map、popup 和 UI 元素。一旦视图损坏，则无法再使用这些内容。为防止这些组件被销毁，请在调用 destroy() 之前将它们从视图中移除。

// remove popup and legend from the view so that they are not destroyed
const popup = view.popup;
view.popup = null;
view.ui.remove(legend);

// unset map from the view so that it is not destroyed
const map = view.map;
view.map = null;

// destroy the view and any remaining associated resources
view.destroy();

另请参阅

• Map.destroy()
• WebMap.destroy()
• WebScene.destroy()

emit(type, event){Boolean}inherited

起始版本：GeoScene Maps SDK for JavaScript 4.5

在实例上触发事件。仅当创建此类的子类时，才应使用此方法。

参数

type String 事件的名称。

event Object optional 事件有效负载。

返回

类型	描述
Boolean	如果监听器收到通知，则为true

focus()inherited

起始版本：GeoScene Maps SDK for JavaScript 4.5

将焦点设置在视图上。

goTo(target, options){Promise}

将视图设置为给定目标。目标参数可以是以下值之一：

• [longitude, latitude] 坐标对
• Geometry (Geometry[] 数组)
• Graphic (Graphic[] 数组)
• Viewpoint
• 具有 target、center、scale 和 rotation 属性组合的对象 (其中，target 是上面列出的任何类型)。提供 center 属性是动画化 MapView.center 的便捷方法，相当于使用中心点指定 target。

此函数返回一个 promise，一旦将新视图设置为目标，即会解析该 promise。如果过渡是动画的，则可以使用 MapView.animation 获得正在进行的动画。如果将视图设置为新目标失败，则 goTo() 方法返回的 promise 会拒绝并出现错误。使用 catch 语句来处理错误：

view.goTo({
  center: [-126, 49]
})
.catch(function(error) {
  if (error.name != "AbortError") {
     console.error(error);
  }
});

如果将切片地图服务用作底图，并且在约束中将 snapToZoom 属性设置为 true，则 goTo 方法将放大以适应定义的 target。如果 snapToZoom 属性设置为 false，则 goTo 方法将缩放到确切的 target。

参数

target GoToTarget2D 要设置动画的目标位置/视点。使用对象作为 target 时，请使用 GoToTarget2D 中的属性。

options GoToOptions2D optional 用于控制动画持续时间和缓动的动画选项。有关对象规范，请参阅 GoToOptions2D 中定义的属性。

返回

类型	描述
Promise	当视图的范围更新到 target 中定义的范围时解决的承诺。

示例

let pt = new Point({
  latitude: 49,
  longitude: -126
});

// go to the given point
view.goTo(pt);

let opts = {
  duration: 5000  // Duration of animation will be 5 seconds
};

// go to point at LOD 15 with custom duration
view.goTo({
  target: pt,
  zoom: 15
}, opts);

// go to same point using center and zoom
view.goTo({
  center: [-126, 49],
  zoom: 15
});

hasEventListener(type){Boolean}inherited

指示实例上是否存在与提供的事件名称相匹配的事件监听器。

参数

type String 事件的名称。

返回

类型	描述
Boolean	如果类支持输入事件，则返回 true。

hasHandles(groupKey){Boolean}inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

如果存在指定的句柄组，则返回 true。

参数

groupKey * optional 组键。

返回

类型	描述
Boolean	如果存在指定的句柄组，则返回 true。

示例

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

hitTest(screenPoint, options){Promise<HitTestResult>}

返回与指定屏幕坐标相交的每个图层的命中测试结果。结果被组织为包含不同结果类型的对象数组。

如果命中相交要素，则以下图层类型将返回所有要素：FeatureLayer、CSVLayer、GeoJSONLayer、GeoRSSLayer、GraphicsLayer、KMLLayer、MapNotesLayer、OGCFeatureLayer、StreamLayer 和 WFSLayer。

VectorTileLayer 命中测试结果包含一个图形，其属性指示与屏幕点相交的矢量切片样式中图层的 ID 和名称。不返回有关图层中表示的实际要素的详细属性和空间信息。

如果对相交元素进行命中，则 MediaLayer 命中测试结果将包含所有媒体元素。如果对相交元素进行命中，则 RouteLayer 命中测试结果将包含所有路径元素。

发布特定更改：

• 在 4.24 版本中，HitTestResult 返回一个包含 graphic、media element 和 route 的对象数组。
• 在 4.23 版本中，来自要素图层的所有命中测试要素都会在结果中返回。在以前版本中，仅返回最重要的要素。
• 在版本 4.6 中，添加了对 VectorTileLayer 的支持。

参数

规范

screenPoint ScreenPoint|MouseEvent 在视图上单击的屏幕坐标 (或本机鼠标事件)。

options Object optional 用于指定 hitTest 中包含或排除的内容的选项。自 4.16 起支持。 规范 include HitTestItem[]|Collection<HitTestItem>|Layer|Graphic optional 要包含在 hitTest 中的图层和图形列表。如果未指定 include，则将包括所有图层和图形。 exclude HitTestItem[]|Collection<HitTestItem>|Layer|Graphic optional 要从 hitTest 中排除的图层和图形列表。如果未指定 exclude，则不会排除任何图层或图形。

返回

类型	描述
Promise<HitTestResult>	解析后，返回包含不同结果类型的对象数组。

示例

// Get the screen point from the view's click event
view.on("click", function (event) {
  // Search for graphics at the clicked location. View events can be used
  // as screen locations as they expose an x,y coordinate that conforms
  // to the ScreenPoint definition.
  view.hitTest(event).then(function (response) {
    // only get the graphics returned from myLayer
    const graphicHits = response.results?.filter(
      (hitResult) => hitResult.type === "graphic" && hitResult.graphic.layer === myLayer
    );
    if (graphicHits?.length > 0) {
      // do something with the myLayer features returned from hittest
      graphicHits.forEach((graphicHit) => {
         console.log(graphicHit.graphic.attributes);
      });
    }
  });
});

// get screenpoint from view's pointer-move event
view.on("pointer-move", function(event){
  // Search for graphics on layers at the hovered location
  // exclude view.graphics from the hitTest
  view.hitTest(event, {exclude: view.graphics}).then(function(response){
    // if graphics are returned, do something with results
    const graphicHits = response.results?.filter(
      (hitResult) => hitResult.type === "graphic"
    );
    if (graphicHits?.length > 0) {
       // do something
    }
  });
});

// get screenpoint from view's click event
view.on("click", function(event){
  // Search for all features only on included layers at the clicked location
  view.hitTest(event, {include: featureLayer}).then(function(response){
    // if features are returned from the featureLayer, do something with results
    if (response.results.length){
       // do something
       console.log(response.results.length, "features returned");
    }
  })
});

// get screenpoint from view's click event
view.on("click", function(event){
  // Search for all media elements only on included mediaLayer at the clicked location
  view.hitTest(event, {include: mediaLayer}).then(function(response){
    // if media elements are returned from the mediaLayer, do something with results
    if (response.results.length){
       // do something
       console.log(response.results.length, "elements returned");
    }
  })
});

isFulfilled(){Boolean}inherited

isFulfilled() 可用于验证创建类的实例是否已完成 (已解决或已拒绝)。如果满足，则返回 true。

返回

类型	描述
Boolean	指示创建类的实例是否已完成 (已解决或已拒绝)。

isRejected(){Boolean}inherited

isRejected() 可用于验证创建类的实例是否被拒绝。如果被拒绝，则返回 true。

返回

类型	描述
Boolean	指示创建类的实例是否已被拒绝。

isResolved(){Boolean}inherited

isResolved() 可用于验证创建类的实例是否已解决。如果已解决，则返回 true。

返回

类型	描述
Boolean	指示创建类的实例是否已解决。

on(type, modifiersOrHandler, handler){Object}inherited

在实例上注册事件处理程序。调用此方法将事件与监听器挂钩。有关侦听的事件列表，请参阅事件汇总表。

参数

type String|String[] 事件的名称或要侦听的事件。

modifiersOrHandler String[]|Function 用于过滤事件的附加修饰符。有关可能值，请参阅键值。支持所有标准键值。或者，如果不需要修饰符，则该函数将在事件触发时调用。 以下事件不支持修饰符：blur, focus, layerview-create, layerview-destroy, resize.

handler Function optional 触发事件时要调用的函数 (如果指定了修饰符)。

返回

类型	描述
Object	返回具有 remove() 方法的事件处理程序，可调用该方法来停止监听事件。 属性 类型 描述 remove Function 调用时，从事件中移除侦听器。

示例

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

// Fires `pointer-move` event when user clicks on "Shift"
// key and moves the pointer on the view.
view.on('pointer-move', ["Shift"], function(event){
  let point = view2d.toMap({x: event.x, y: event.y});
  bufferPoint(point);
});

removeHandles(groupKey)inherited

起始版本：GeoScene Maps SDK for JavaScript 4.25

移除对象拥有的句柄组。

参数

groupKey * optional 要移除的组键或组键的数组或集合。

示例

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

takeScreenshot(options){Promise<Screenshot>}

起始版本：GeoScene Maps SDK for JavaScript 4.10

创建当前视图的屏幕截图。屏幕截图仅包括在画布上渲染的元素 (所有地理元素)，但不包括覆盖的 DOM 元素 (UI、弹出窗口、测量标注等)。默认情况下，会创建整个视图的屏幕截图。不同的选项允许创建不同类型的屏幕截图，包括以不同的纵横比、不同的分辨率进行屏幕截图和创建缩略图。

屏幕截图始终在视图的内边距区域内进行拍摄 (请参阅 padding)。

参数

规范

options Object optional 截图选项。 规范 format String optional 默认值： png 生成的编码数据 url 的格式。 可能值："jpg"|"png" layers Layer[] optional 使用时，仅此列表中的可见图层将包含在输出中。 quality Number optional 默认值：98 编码为 jpg 时编码图像的质量（0 到 100）。 width Number optional 屏幕截图的宽度 (默认为区域宽度)。如果未指定，高度将根据屏幕截图区域的纵横比自动得出。 height Number optional 屏幕截图的高度 (默认为区域高度)。如果未指定，宽度将根据屏幕截图区域的纵横比自动得出。 area Object optional 指定是否截取视图特定区域的屏幕截图。区域坐标相对于内边距视图的原点 (请参阅 padding)，并将裁剪为视图大小。默认为整个视图 (不包括内边距)。 规范 x Number optional 区域的 x 坐标。 y Number optional 区域的 y 坐标。 width Number optional 区域的宽度。 height Number optional 区域的高度。 ignoreBackground Boolean optional 默认值： false 指示是否忽略在 web 地图的初始视图属性中设置的背景颜色。 ignorePadding Boolean optional 默认值： false 指示是否应忽略视图内边距。将此属性设置为 true 以允许在屏幕截图中包含内边距区域。

返回

类型	描述
Promise<Screenshot>	解析后，返回一个包含编码 dataUrl 和原始图像数据的对象。

示例

// Take a screenshot once view is ready (and data is displaying)
 reactiveUtils.whenOnce(() => !view.updating).then(() => {
   // Take a screenshot at the same resolution of the current view
   view.takeScreenshot().then(function(screenshot) {
     let imageElement = document.getElementById("screenshotImage");
     imageElement.src = screenshot.dataUrl;
   });
});

// Create a square thumbnail from the current view
let options = {
  width: 200,
  height: 200
};

view.takeScreenshot(options).then(function(screenshot) {
  let imageElement = document.getElementById("screenshotImage");
  imageElement.src = screenshot.dataUrl;
});

// Take a high resolution, square screenshot
let options = {
  width: 2048,
  height: 2048
};

view.takeScreenshot(options).then(function(screenshot) {
  let imageElement = document.getElementById("screenshotImage");
  imageElement.src = screenshot.dataUrl;
});

// Takes a high-resolution screenshot for display on a HiDPI screen
// The pixelRatio indicates the display has 2x the pixel density of typical screens
let pixelRatio = 2;
view.takeScreenshot({ width: view.width * pixelRatio, height: view.height * pixelRatio });

// Takes a high-resolution screenshot for display on a HiDPI screen
// The pixelRatio is the resolution of the display capturing the image
let pixelRatio = window.devicePixelRatio;
view.takeScreenshot({ width: view.width * pixelRatio, height: view.height * pixelRatio });

toMap(screenPoint){Point}

将给定的屏幕点转换为地图点。屏幕点表示相对于视图左上角的像素点。

参数

screenPoint ScreenPoint|MouseEvent 要转换的屏幕上的位置 (或本机鼠标事件)。

返回

类型	描述
Point	与给定屏幕点相对应的地图点。

toScreen(point){ScreenPoint}

将给定的地图点转换为屏幕点。屏幕点表示相对于视图左上角的像素点。

参数

point Point 点几何。

返回

类型	描述
ScreenPoint	与给定地图点相对应的屏幕点。

示例

// get the screen point for the specified map point.
const mapPoint = {
  x: -49.97,
  y: 41.73,
  spatialReference:{
     wkid: 4326
  }
};
const screenPoint = mapView.toScreen(mapPoint);

tryFatalErrorRecovery()inherited

起始版本：GeoScene Maps SDK for JavaScript 4.12

调用此方法可清除因丢失 WebGL 上下文而导致的任何致命错误。

另请参阅

• fatalError

示例

view.watch("fatalError", function(error) {
  if(error) {
    view.tryFatalErrorRecovery();
  }
});

when(callback, errback){Promise}inherited

起始版本：GeoScene Maps SDK for JavaScript 4.6

一旦创建了类的实例，就可以使用when() 。此方法接受两个输入参数：callback 函数和 errback 函数。callback 在类的实例加载时执行。errback 在类的实例无法加载时执行。

参数

callback Function optional 当 promise 解决时调用的函数。

errback Function optional 当 promise 失败时执行的函数。

返回

类型	描述
Promise	返回 callback 结果的新承诺，可用于链接其他函数。

示例

// Although this example uses MapView, any class instance that is a promise may use when() in the same way
let view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

whenLayerView(layer){Promise<LayerView>}inherited

获取在给定图层的视图上创建的 LayerView。在给定图层的图层视图已创建时，解析返回的 promise， 或者拒绝返回的 promise 并显示错误 (例如，如果图层不是视图的一部分，或者此视图不支持图层类型)。

参数

layer Layer 要获取其 LayerView 的图层。

返回

类型	描述
Promise<LayerView>	解析为指定图层的 LayerView 实例。

示例

// Create a feature layer from a url pointing to a Feature Service
let layer = new FeatureLayer(url);

map.add(layer);

view.whenLayerView(layer)
    .then(function(layerView) {
      // The layerview for the layer
    })
    .catch(function(error) {
      // An error occurred during the layerview creation
    });

类型定义

GoToOptions2D Object

goTo() 方法的动画选项。有关对象规范，请参阅以下属性。

属性

animate Boolean optional 默认值：true 指示是否应为新视图的过渡设置动画。如果设置为 false，则忽略 duration 和 easing 属性。

duration Number optional 默认值：200 动画的持续时间，以毫秒为单位。

easing String|Function optional 默认值：ease 用于动画的 easing 函数。有关这些函数的图形表示，请参阅 easing 函数。 可能值："linear"|"ease"|"ease-in"|"ease-out"|"ease-in-out"

signal AbortSignal optional 中止动画的 AbortSignal。如果取消，则承诺将被拒绝，并返回一个名为 AbortError 的错误。另请参见 AbortController。

GoToTarget2D Number[]|Geometry|Geometry[]|Collection<Geometry>|Graphic|Graphic[]|Collection<Graphic>|Viewpoint|Object

goTo() 方法中要设置动画的目标位置/视点。由数字组成的二元素数组，表示使视图居中的 [x,y] 坐标。使用对象作为 target 时，请使用下表中的属性。

属性

target Number[]|Geometry|Geometry[]|Collection<Geometry>|Graphic|Graphic[]|Collection<Graphic>|Viewpoint optional 动画的目标。

center Number[] optional 转至到的 MapView.center。

scale Number optional 转至到的 MapView.scale。

zoom Number optional 转至到的 MapView.zoom。

GraphicHit Object

起始版本：GeoScene Maps SDK for JavaScript 4.24

hitTest() 方法的 HitTestResult 中返回的图形命中结果的对象规范。有关此对象中每个属性的规范，请参阅下表。

属性

type String 值通常是 "graphic"。

graphic Graphic 表示视图中与输入屏幕坐标相交的要素的图形。如果图形来自应用了 Renderer 的图层，则 symbol 属性将为空。根据获取图形的上下文，其他属性可能为空。 如果结果来自 VectorTileLayer，则返回带有两个 attributes 的静态图形：layerId 和 layerName。这些对应于矢量切片样式中样式图层的名称和 ID。

layer Layer 包含要素/图形的图层。

mapPoint Point 与输入屏幕坐标相对应的视图的空间参考中的点几何。

HitTestItem Layer|Graphic|Collection<Layer>|Collection<Graphic>|Layer[]|Graphic[]

要在 hitTest() 过滤器选项中使用的图层、图形或图层或图形集合。

另请参阅

• hitTest()

HitTestResult Object

起始版本：GeoScene Maps SDK for JavaScript 4.24

hitTest() 方法结果的对象规范。

属性

results ViewHit[] 从 hitTest() 返回的结果对象数组。当输入屏幕坐标的位置与视图中的图形或媒体元素相交时，将返回结果。

screenPoint ScreenPoint 在视图上单击的屏幕坐标 (或本机鼠标事件)。

MediaHit Object

起始版本：GeoScene Maps SDK for JavaScript 4.24

在 hitTest() 方法的 HitTestResult 中，从 MediaLayer 中返回的媒体命中结果的对象规范。有关此对象中每个属性的规范，请参阅下表。

属性

type String 值通常是 "media"。

element ImageElement|VideoElement 表示 MediaLayer.source 中与输入屏幕坐标相交的媒体元素的元素。

layer MediaLayer 包含元素的媒体图层。

mapPoint Point 与输入屏幕坐标相对应的视图的空间参考中的点几何。

RouteHit Object

起始版本：GeoScene Maps SDK for JavaScript 4.24

在 hitTest() 方法的 HitTestResult 中，从 RouteLayer 中返回的路径命中结果的对象规范。有关此对象中每个属性的规范，请参阅下表。

属性

type String 值通常是 "route"。

layer RouteLayer 包含元素的路径图层。

mapPoint Point 与输入屏幕坐标相对应的视图的空间参考中的点几何。

networkFeature DirectionLine|DirectionPoint|PointBarrier|PolygonBarrier|RouteInfo|Stop 路径命中测试将包含所有相交网络元素，其中包括以下元素之一：DirectionLine、DirectionPoint、PointBarrier、PolylineBarrier、PolygonBarrier、Stop 或 RouteInfo。

ScreenPoint

起始版本：GeoScene Maps SDK for JavaScript 4.11

表示屏幕上一个点的对象。

属性

x Number x 坐标。

y Number y 坐标。

Screenshot

起始版本：GeoScene Maps SDK for JavaScript 4.10

当 takeScreenshot() 承诺解决时返回的对象：

属性

dataUrl String 代表屏幕截图的数据 url。

data ImageData 原始 RGBA 图像数据。

ViewHit GraphicHit|MediaHit|RouteHit

起始版本：GeoScene Maps SDK for JavaScript 4.24

hitTest() 方法的 HitTestResult 中返回的结果的对象规范。

事件概述

事件详细说明

blurinherited

起始版本：GeoScene Maps SDK for JavaScript 4.7

当浏览器焦点从视图移开时触发。

属性

target View 浏览器焦点被移离的视图。

native Object 标准的 DOM KeyboardEvent。

clickinherited

在用户点击视图后触发。此事件发出的速度比 immediate-click 事件稍慢，以确保不会触发 double-click 事件。Immediate-click 事件可用于无延迟地响应点击事件。

属性

mapPoint Point 在地图的空间参考中，单击视图上的点位置。

x Number 单击视图的水平屏幕坐标。

y Number 单击视图的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 表示当前鼠标按键状态。 值 描述 0 左键单击 (或触摸) 1 中键单击 2 右键单击 可能值：0|1|2

type String 事件类型。 值通常是 "click"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

示例

// Set up a click event handler and retrieve the screen point
view.on("click", function(event) {
 // the hitTest() checks to see if any graphics in the view
 // intersect the given screen x, y coordinates
 view.hitTest(event)
  .then(getGraphics);
});

view.on("click", function(event) {
 // you must overwrite default click-for-popup
 // behavior to display your own popup
 view.popup.autoOpenEnabled = false;

 // Get the coordinates of the click on the view
 let lat = Math.round(event.mapPoint.latitude * 1000) / 1000;
 let lon = Math.round(event.mapPoint.longitude * 1000) / 1000;

 view.popup.open({
   // Set the popup's title to the coordinates of the location
   title: "Reverse geocode: [" + lon + ", " + lat + "]",
   location: event.mapPoint // Set the location of the popup to the clicked location
   content: "This is a point of interest"  // content displayed in the popup
 });
});

double-clickinherited

双击视图后触发。

属性

mapPoint Point 在地图的空间参考中，单击视图上的点位置。

x Number 单击视图的水平屏幕坐标。

y Number 单击视图的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 表示当前鼠标按键状态。 值 描述 0 左键单击 (或触摸) 1 中键单击 2 右键单击 可能值：0|1|2

type String 事件类型。 值通常是 "double-click"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

示例

view.on("double-click", function(event) {
  // The event object contains the mapPoint and the screen coordinates of the location
  // that was clicked.
  console.log("screen point", event.x, event.y);
  console.log("map point", event.mapPoint);
});

draginherited

在视图上拖动指针时触发。

属性

action String 指示拖动的状态。added 和 removed 的两个值表示所涉及的指针数量的变化。 可能值："start"|"added"|"update"|"removed"|"end"

x Number 视图上指针的水平屏幕坐标。

y Number 视图上指针的垂直屏幕坐标。

origin Object 拖动开始的屏幕坐标。 规范 x Number 视图上指针的水平屏幕坐标。 y Number 视图上指针的垂直屏幕坐标。

button Number 指示在拖动开始时单击了哪个鼠标按钮。参阅 MouseEvent.button。 值 描述 0 鼠标左键 (或触摸) 1 鼠标中键 2 鼠标右键 可能值：0|1|2

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "drag"。

radius Number 围绕此拖动所涉及的多个指针的球体半径。为 0 时，只使用一个指针。

angle Number 自上次 start 类型事件以来的旋转量 (以度为单位)。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM MouseEvent。

示例

view.on("drag", function(event){
 // Print out the current state of the
 // drag event.
 console.log("drag state", event.action);
});

focusinherited

起始版本：GeoScene Maps SDK for JavaScript 4.7

当浏览器焦点在视图上时触发。

属性

target View 浏览器当前焦点所在的视图。

native Object 标准的 DOM KeyboardEvent。

holdinherited

在视图上按住鼠标按钮或单指停留一小段时间后触发。

属性

mapPoint Point 在地图的空间参考中，单击视图上的点位置。

x Number 视图上保持的水平屏幕坐标。

y Number 视图上保持的垂直屏幕坐标。

button Number 指示按下了哪个鼠标按钮。参阅 MouseEvent.button。 值 描述 0 鼠标左键 (或触摸) 1 鼠标中键 2 鼠标右键 可能值：0|1|2

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "hold"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

示例

view.on("hold", function(event) {
  // The event object contains the mapPoint and the screen coordinates of the location
  // that was clicked.
  console.log("hold at screen point", event.x, event.y);
  console.log("hold at map point", event.mapPoint);
});

immediate-clickinherited

起始版本：GeoScene Maps SDK for JavaScript 4.7

在用户点击视图后立即触发。与 click 事件相反，immediate-click 事件在用户单击视图时立即发出，并且不受 double-click 的抑制。此事件对于需要及时反馈的交互式体验很有用。

属性

mapPoint Point 在地图的空间参考中，单击视图上的点位置。

x Number 单击视图的水平屏幕坐标。

y Number 单击视图的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。参阅 MouseEvent.button。 值 描述 0 左键单击 (或触摸) 1 中键单击 2 右键单击 可能值：0|1|2

buttons Number 指示触发事件时按下了哪些按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "immediate-click"。

stopPropagation Function 防止事件在事件链中冒泡。禁止关联的 click 和 double-click 事件。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

示例

// Set up an immediate-click event handler and retrieve the screen point
view.on("immediate-click", function(event) {
 // the hitTest() checks to see if any graphics in the view
 // intersect the given screen x, y coordinates
 view.hitTest(event)
  .then(getGraphics);
});

immediate-double-clickinherited

起始版本：GeoScene Maps SDK for JavaScript 4.15

在两个连续的 immediate-click 事件之后发出。与 double-click 相比，无法通过在 immediate-click 事件上使用 stopPropagation 来阻止 immediate-double-click，因此可以独立于 immediate-click 事件对双击做出反应。

属性

mapPoint Point 在地图的空间参考中，单击视图上的点位置。

x Number 单击视图的水平屏幕坐标。

y Number 单击视图的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。参阅 MouseEvent.button。 值 描述 0 左键单击 (或触摸) 1 中键单击 2 右键单击 可能值：0|1|2

buttons Number 指示触发事件时按下了哪些按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "immediate-double-click"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

key-downinherited

按下键盘键后触发。

属性

repeat Boolean 指示这是由于按键而触发的第一个事件，还是重复事件。

key String 按下的键值，根据 MDN 完整键值列表。

type String 事件类型。 值通常是 "key-down"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM KeyboardEvent。

示例

// Zoom in when user clicks on "a" button
// Zoom out when user clicks on "s" button
view.on("key-down", function(event){
 console.log("key-down", event);

 if (event.key === "a"){
   let zm = view.zoom + 1;

   view.goTo({
     target: view.center,
     zoom: zm
   });
 }
 else if(event.key == "s"){
   let zm = view.zoom - 1;

   view.goTo({
     target: view.center,
     zoom: zm
   });
 }
});

key-upinherited

释放键盘按键后触发。

属性

type String 事件类型。 值通常是 "key-up"。

key String 释放的键值，根据 MDN 完整键值列表。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM KeyboardEvent。

layerview-createinherited

地图中的每个图层均具有在视图中创建并渲染的相应 LayerView 后触发。

属性

layer Layer 地图中为其创建 layerView 的图层。

layerView LayerView 在表示 layer 中图层的视图中进行渲染的 LayerView。

另请参阅

• View.whenLayerView()

示例

// This function fires each time a layer view is created for a layer in
// the map of the view.
view.on("layerview-create", function(event) {
  // The event contains the layer and its layer view that has just been
  // created. Here we check for the creation of a layer view for a layer with
  // a specific id, and log the layer view
  if (event.layer.id === "satellite") {
    // The LayerView for the desired layer
    console.log(event.layerView);
  }
});

layerview-create-errorinherited

将图层添加到地图后，在创建 LayerView 期间出现错误时触发。

属性

layer Layer 地图中的图层，触发此事件的视图无法为其创建图层视图。

error Error 描述图层视图创建失败原因的错误对象。

另请参阅

• View.whenLayerView()

示例

// This function fires each time an error occurs during the creation of a layerview
view.on("layerview-create-error", function(event) {
  console.error("LayerView failed to create for layer with the id: ", event.layer.id);
});

layerview-destroyinherited

销毁 LayerView 并不再在视图中呈现后触发。例如，当从视图的地图中移除图层时，就会发生这种情况。

属性

layer Layer 地图中为其销毁 layerView 的图层。

layerView LayerView 视图中被销毁的 LayerView。

mouse-wheelinherited

当指针设备（通常是鼠标）的滚轮按钮在视图上滚动时触发。

属性

x Number 单击视图的水平屏幕坐标。

y Number 单击视图的垂直屏幕坐标。

deltaY Number 代表垂直滚动量的数字。

type String 事件类型。 值通常是 "mouse-wheel"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM WheelEvent。

示例

view.on("mouse-wheel", function(event){
 // deltaY value is positive when wheel is scrolled up
 // and it is negative when wheel is scrolled down.
 console.log(event.deltaY);
});

pointer-downinherited

在按下鼠标按钮或手指触摸显示屏后触发。

属性

pointerId Number 在多个向下、移动和向上事件之间唯一标识的指针。在 pointer-up 事件之后，可能会重用 Id。

pointerType String 指示点类型。 可能值："mouse"|"touch"

x Number 视图上指针的水平屏幕坐标。

y Number 视图上指针的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "pointer-down"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 发出事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

pointer-enterinherited

在鼠标光标进入视图或显示触摸开始后触发。

属性

pointerId Number 在多个事件之间唯一标识的指针。在 pointer-up 事件之后，可能会重用 Id。

pointerType String 指示点类型。 可能值："mouse"|"touch"

x Number 视图上指针的水平屏幕坐标。

y Number 视图上指针的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "pointer-enter"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 创建事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

pointer-leaveinherited

在鼠标光标离开视图或显示触摸结束后触发。

属性

pointerId Number 在多个事件之间唯一标识的指针。在 pointer-up 事件之后，可能会重用 Id。

pointerType String 指示点类型。 可能值："mouse"|"touch"

x Number 视图上指针的水平屏幕坐标。

y Number 视图上指针的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "pointer-leave"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 创建事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

pointer-moveinherited

鼠标或手指在显示屏上移动后触发。

属性

pointerId Number 在多个向下、移动和向上事件之间唯一标识的指针。在 pointer-up 事件之后，可能会重用 Id。

pointerType String 指示点类型。 可能值："mouse"|"touch"

x Number 视图上指针的水平屏幕坐标。

y Number 视图上指针的垂直屏幕坐标。

button Number 指示单击了哪个鼠标按钮。

buttons Number 指示触发事件时按下了哪些鼠标按钮。参阅 MouseEvent.buttons。

type String 事件类型。 值通常是 "pointer-move"。

stopPropagation Function 防止事件在事件链中冒泡。

timestamp Number 创建事件的时间戳 (以毫秒为单位)。

native Object 标准的 DOM PointerEvent。

示例

// Fires `pointer-move` event when user clicks on "Shift"
// key and moves the pointer on the view.
view.on('pointer-move', ["Shift"], function(event){
  let point = view.toMap({x: event.x, y: event.y});
  bufferPoint(point);
});