Class: Map

ol/Map~Map 


import Map from 'ol/Map.js';

地图是 OpenLayers 的核心组件。要渲染地图，需要视图、一个或多个图层，以及一个目标容器：

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import OSM from 'ol/source/OSM.js';

const map = new Map({
  view: new View({
    center: [0, 0],
    zoom: 1,
  }),
  layers: [
    new TileLayer({
      source: new OSM(),
    }),
  ],
  target: 'map',
});

上面的代码片段使用 TileLayer 创建了一个地图，用于 显示 OSM OSM 数据，并将其渲染到 id 为 map 的 DOM 元素中。

构造函数在目标元素中放置一个视口容器（CSS 类名为 ol-viewport，参见 getViewport()），然后在视口中再放置两个 元素：一个 CSS 类名为 ol-overlaycontainer-stopevent 的元素用于控件和某些覆盖物，另一个 CSS 类名为 ol-overlaycontainer 的元素用于其他覆盖物（参见 Overlay 的 stopEvent 选项以了解两者的区别）。地图 本身放置在视口中的另一个元素中。

图层以 Collection 的形式存储在 layerGroups 中。库提供了一个顶层组。这就是 getLayerGroup 和 setLayerGroup 所访问的组。在 options 中传入的图层会被添加到这个组中，addLayer 和 removeLayer 用于更改该组中的 图层集合。getLayers 是 getLayerGroup().getLayers() 的便捷方法。注意，LayerGroup 是 BaseLayer 的子类，因此在 options 中传入的图层或通过 addLayer 添加的图层可以是组，组中又可以包含其他 组，以此类推。

new Map(options)

Map.js, line 250
Name Type Description
controls Collection<Control> | Array<Control> | undefined

初始添加到地图的控件。如果未指定，则使用默认值。在 Worker 中，默认不添加控件。
pixelRatio number (defaults to window.devicePixelRatio)

设备上物理像素与设备无关像素（dips）之间的比率。
interactions Collection<Interaction> | Array<Interaction> | undefined

初始添加到地图的交互。如果未指定，则使用默认值。在 Worker 中，默认不添加交互。
keyboardEventTarget HTMLElement | Document | string | undefined

监听键盘事件的元素。这决定了 KeyboardPan 和 KeyboardZoom 交互何时触发。例如，如果此选项设置为 document，键盘交互将始终触发。如果未指定此选项，库监听键盘事件的元素是地图目标（即用户提供的地图 div）。如果不是 document，目标元素需要获得焦点才能触发按键事件，这要求目标元素具有 tabindex 属性。
layers Array<BaseLayer> | Collection<BaseLayer> | LayerGroup | undefined

图层。如果未定义，将渲染一个没有图层的地图。注意图层按提供的顺序渲染，因此如果您希望矢量图层显示在瓦片图层之上，它必须位于瓦片图层之后。
maxTilesLoading number (defaults to 16)

同时加载的最大瓦片数。
moveTolerance number (defaults to 1)

光标必须移动的最小像素距离，才能被检测为地图移动事件而非点击。增加此值可以使点击地图更容易。
overlays Collection<Overlay> | Array<Overlay> | undefined

初始添加到地图的覆盖物。默认不添加覆盖物。
target HTMLElement | string | HTMLCanvasElement | OffscreenCanvas | undefined

地图的容器，可以是元素本身或元素的 id。如果构造时未指定，必须调用 setTarget 才能渲染地图。如果通过元素传递，容器可以在辅助文档中。用于 Worker 或导出地图时，请使用 OffscreenCanvas 或 HTMLCanvasElement 作为目标，宽度和高度为物理像素，可选择乘以与地图像素比匹配的比例变换。对于无障碍访问（地图导航的焦点和键盘事件），target 元素必须具有正确配置的 tabindex 属性。如果 target 元素在 Shadow DOM 内，tabindex 属性必须设置在自定义元素的宿主元素上。注意：CSS transform 对目标元素的支持仅限于 scale。
view View | Promise<ViewOptions> | undefined

地图的视图。除非在构造时指定或通过 setView 设置，否则不会获取任何图层源。
触发事件：
  • change (BaseEvent) - 通用更改事件。当修订计数器增加时触发。
  • change:layerGroup (ObjectEvent)
  • change:size (ObjectEvent)
  • change:target (ObjectEvent)
  • change:view (ObjectEvent)
  • click (MapBrowserEvent) - 单击且无拖拽。双击会触发两次此事件。
  • dblclick (MapBrowserEvent) - A true double click, with no dragging.
  • error (BaseEvent) - 通用错误事件。 当发生错误时触发。
  • loadend (MapEvent) - 当额外地图数据加载完成时触发。
  • loadstart (MapEvent) - 当额外地图数据（瓦片、图像、要素）开始加载时触发。
  • moveend (MapEvent) - 地图移动后触发。
  • movestart (MapEvent) - 当地图开始移动时触发。
  • pointerdrag (MapBrowserEvent) - 当拖动指针时触发。
  • pointermove (MapBrowserEvent) - 当移动指针时触发。 Note that on touch devices this is 当the map is panned, so is not the same as mousemove.
  • postcompose (RenderEvent) - Triggered after layers are composed. When dispatched by the map, the event object will not have a context set. When dispatched by a layer, the event object will have a context set. Only WebGL layers currently dispatch this event.
  • postrender (MapEvent) - 当地图帧渲染完成后触发。
  • precompose (RenderEvent) - Triggered before layers are composed. When dispatched by the map, the event object will not have a context set. When dispatched by a layer, the event object will have a context set. Only WebGL layers currently dispatch this event.
  • propertychange (ObjectEvent) - 当属性更改时触发。
  • rendercomplete (RenderEvent) - 当rendering is complete, i.e. all sources and tiles have finished loading for the current viewport, and all tiles are faded in. The event object will not have a context set.
  • singleclick (MapBrowserEvent) - 真正的单击，无拖拽且无双击。请注意，此 事件会延迟 250 毫秒，以确保不是双击。

Extends

Observable Properties

Name Type Settable ObjectEvent type Description
layerGroup LayerGroup yes change:layergroup

包含此地图中图层的图层组。
size Size | undefined yes change:size

地图在 DOM 中的像素尺寸。
target HTMLElement | string | undefined yes change:target

地图渲染所在的元素或元素 ID。
view View yes change:view

控制此地图的视图。

Methods

addControl(control)

Map.js, line 615

将给定的控件添加到地图。

Name Type Description
control Control

控件。

addInteraction(interaction)

Map.js, line 628

将给定的交互添加到地图。如果要在集合的其他位置添加交互，请使用 getInteractions() 和 Collection 上的可用方法。这可用于从 handleEvent 函数停止事件传播。交互以与此集合相反的顺序处理事件。

Name Type Description
interaction Interaction

要添加的交互。

addLayer(layer)

Map.js, line 639

将给定图层添加到此地图的顶部。如果要在堆栈的其他位置添加图层，请使用 getLayers() 和 Collection 上的可用方法。

Name Type Description
layer BaseLayer

图层。

addOverlay(overlay)

Map.js, line 657

将给定的覆盖物添加到地图。

Name Type Description
overlay Overlay

覆盖物。

changed() inherited

Observable.js, line 68

增加修订计数器并分发 'change' 事件。

dispatchEvent(event){boolean | undefined} inherited

events/Target.js, line 85

分发事件并调用所有监听此类型事件的监听器。事件参数可以是一个字符串或一个 具有 type 属性的对象。

Name Type Description
event BaseEvent | string

事件对象。
返回值：
如果有人在事件对象上调用了 preventDefault 或任何监听器返回 false，则返回 false。

forEach要素AtPixel(pixel, callback, options){T | undefined}

Map.js, line 709

检测与视口上像素相交的要素，并对每个相交的要素执行回调函数。可以通过 options 中的 layerFilter 选项配置参与检测的图层。 对于没有填充的多边形，仅使用描边进行命中检测。 多边形必须应用填充样式才能确保检测到多边形内部的像素。填充可以是透明的。

Name Type Description
pixel Pixel

像素。
callback function

要素回调。回调将使用两个参数调用。第一个参数是像素处的一个 feature 或 render feature，第二个是要素的 layer，对于非托管图层将为 null。要停止检测，回调函数可以返回真值。
options

可选选项。

Name Type Description
layerFilter undefined | function

图层过滤函数。过滤函数将接收一个参数 layer-candidate，并应返回布尔值。只有可见且此函数返回 true 的图层才会被测试要素。默认情况下，将测试所有可见图层。
hitTolerance number (defaults to 0)

命中检测容差（CSS 像素）。给定位置半径内的像素将被检查是否包含要素。
checkWrapped boolean (defaults to true)

检查环绕 将在 +/- 1 个世界宽度范围内检查环绕的几何对象。 仅在使用可环绕的投影时有效。
返回值：
Callback result, i.e. the return value of last callback execution, or the first truthy callback return value.

get(key){*} inherited

Object.js, line 136

获取一个值。

Name Type Description
key string

键名。
返回值：
值。

getAllLayers(){Array<Layer>}

Map.js, line 760

从所有图层组获取所有图层。

返回值：
Layers.

getControls(){Collection<Control>}

Map.js, line 910

获取地图控件。修改此集合会更改与地图关联的控件。

返回值：
控件。

getCoordinateFromPixel(pixel){Coordinate}

Map.js, line 883

获取给定像素的坐标。返回用户投影中的坐标。

Name Type Description
pixel Pixel

地图视口中的像素位置。
返回值：
The coordinate for the pixel position.

getEventCoordinate(event){Coordinate}

Map.js, line 813

返回浏览器事件在用户投影中的坐标。

Name Type Description
event MouseEvent

事件。
返回值：
坐标。

getEventPixel(event){Pixel}

Map.js, line 832

返回浏览器事件相对于视口的地图像素位置。

Name Type Description
event UIEvent | Object

事件。
返回值：
像素。

getFeaturesAtPixel(pixel, options){Array<要素Like>}

Map.js, line 743

获取与视口上像素相交的所有要素。对于没有填充的多边形，仅使用描边进行命中检测。多边形必须应用填充样式才能确保检测到多边形内部的像素。填充可以是透明的。

Name Type Description
pixel Pixel

像素。
options

可选选项。

Name Type Description
layerFilter undefined | function

图层过滤函数。过滤函数将接收一个参数 layer-candidate，并应返回布尔值。只有可见且此函数返回 true 的图层才会被测试要素。默认情况下，将测试所有可见图层。
hitTolerance number (defaults to 0)

命中检测容差（CSS 像素）。给定位置半径内的像素将被检查是否包含要素。
checkWrapped boolean (defaults to true)

检查环绕 将在 +/- 1 个世界宽度范围内检查环绕的几何对象。 仅在使用可环绕的投影时有效。
返回值：
The detected features or an empty array if none were found.

getInteractions(){Collection<Interaction>}

Map.js, line 945

获取地图交互。修改此集合会更改与地图关联的交互。

交互用于例如平移、缩放和旋转。

返回值：
交互。

getKeys(){Array.<string>} inherited

Object.js, line 149

获取对象属性名列表。

返回值：
属性名列表。

getLayerGroup(){LayerGroup}

Map.js, line 955

获取与此地图关联的图层组。

返回值：
A layer group containing the layers in this map.

getLayers(){Collection<BaseLayer>}

Map.js, line 981

获取与此地图关联的图层集合。

返回值：
Layers.

getOverlayById(id){Overlay | null}

Map.js, line 932

通过标识符获取覆盖物（overlay.getId() 返回的值）。注意索引将字符串和数字标识符视为相同。因此 map.getOverlayById(2) 将返回 id 为 '2' 或 2 的覆盖物。

Name Type Description
id string | number

覆盖物标识符。
返回值：
覆盖物。

getOverlays(){Collection<Overlay>}

Map.js, line 920

获取地图覆盖物。修改此集合会更改与地图关联的覆盖物。

返回值：
覆盖物。

getPixelFromCoordinate(coordinate){Pixel}

Map.js, line 1015

获取坐标对应的像素。接收用户投影中的坐标并返回对应的像素。

Name Type Description
coordinate Coordinate

地图坐标。
返回值：
A pixel position in the map viewport.

getPixelRatio(){number}

Map.js, line 1045

获取渲染地图的像素比。

返回值：
像素比。

getProperties(){NoInfer.<Properties>} inherited

Object.js, line 158

获取包含所有属性名和值的对象。

返回值：
对象。

getRevision(){number} inherited

Observable.js, line 79

获取此对象的版本号。 每次对象被修改时，其版本号将递增。

返回值：
版本号。

getSize(){Size | undefined}

Map.js, line 1076

获取size 此地图的.

返回值：
The size in pixels of the map in the DOM.

getTarget(){HTMLElement | string | undefined}

Map.js, line 859

获取渲染此地图的目标。注意此方法返回的是作为选项或在 setTarget 中输入的值：如果是元素，则返回元素；如果是字符串，则返回字符串。

返回值：
The Element or id of the Element that the map is rendered in.

getTargetElement(){HTMLElement}

Map.js, line 872

获取渲染此地图的 DOM 元素。与 getTarget 不同，此方法始终返回 Element，如果地图没有目标则返回 null。

返回值：
The element that the map is rendered in.

getView(){View}

Map.js, line 1089

获取与此地图关联的视图。视图管理中心和分辨率等属性。

返回值：
The view that controls this map.

getViewport(){HTMLElement}

Map.js, line 1098

作为地图视口的元素。

返回值：
Viewport.

has要素AtPixel(pixel, options){boolean}

Map.js, line 786

检测要素是否与视口上的某个像素相交。可以通过 layerFilter 选项配置参与检测的图层。对于没有填充的多边形，仅使用描边进行命中检测。多边形必须应用填充样式才能确保检测到多边形内部的像素。填充可以是透明的。

Name Type Description
pixel Pixel

像素。
options

可选选项。

Name Type Description
layerFilter undefined | function

图层过滤函数。过滤函数将接收一个参数 layer-candidate，并应返回布尔值。只有可见且此函数返回 true 的图层才会被测试要素。默认情况下，将测试所有可见图层。
hitTolerance number (defaults to 0)

命中检测容差（CSS 像素）。给定位置半径内的像素将被检查是否包含要素。
checkWrapped boolean (defaults to true)

检查环绕 将在 +/- 1 个世界宽度范围内检查环绕的几何对象。 仅在使用可环绕的投影时有效。
返回值：
Is there a feature at the given pixel?

on(type, listener){EventsKey | Array<EventsKey>} inherited

Observable.js, line 152

监听特定类型的事件。

Name Type Description
type string | Array.<string>

事件类型或事件类型数组。
listener function

监听器函数。
返回值：
监听器的唯一键。如果第一个参数是事件类型数组，则返回键的数组。

once(type, listener){EventsKey | Array<EventsKey>} inherited

Observable.js, line 164

仅监听一次特定类型的事件。

Name Type Description
type string | Array.<string>

事件类型或事件类型数组。
listener function

监听器函数。
返回值：
监听器的唯一键。如果第一个参数是事件类型数组，则返回键的数组。

removeControl(control){Control | undefined}

Map.js, line 1550

从地图移除给定的控件。

Name Type Description
control Control

控件。
返回值：
The removed control (or undefined if the control was not found).

removeInteraction(interaction){Interaction | undefined}

Map.js, line 1561

从地图移除给定的交互。

Name Type Description
interaction Interaction

要移除的交互。
返回值：
The removed interaction (or undefined if the interaction was not found).

removeLayer(layer){BaseLayer | undefined}

Map.js, line 1572

从地图中移除给定图层。

Name Type Description
layer BaseLayer

图层。
返回值：
The removed layer (or undefined if the layer was not found).

removeOverlay(overlay){Overlay | undefined}

Map.js, line 1592

从地图移除给定的覆盖物。

Name Type Description
overlay Overlay

覆盖物。
返回值：
The removed overlay (or undefined if the overlay was not found).

render()

Map.js, line 1537

请求地图渲染（在下一个动画帧）。

renderSync()

Map.js, line 1510

以同步方式请求立即渲染。

set(key, value, silent) inherited

Object.js, line 218

设置一个值。

Name Type Description
key string

键名。
value *

值。
silent boolean | undefined

更新但不触发事件。

setLayerGroup(layerGroup)

Map.js, line 1714

设置此地图的图层组。

Name Type Description
layerGroup LayerGroup

包含此地图中图层的图层组。

setLayers(layers)

Map.js, line 964

清除所有现有图层并向地图添加图层。

Name Type Description
layers Array<BaseLayer> | Collection<BaseLayer>

要添加到地图的图层。

setPixelRatio(pixelRatio)

Map.js, line 1054

设置渲染地图的像素比。

Name Type Description
pixelRatio number

像素比。

setProperties(values, silent) inherited

Object.js, line 238

设置一组键值对。 注意，这会更改任何现有属性并添加新属性（不会移除任何现有属性）。

Name Type Description
values Partial.<NoInfer.<Properties>>

值。
silent boolean | undefined

更新但不触发事件。

setSize(size)

Map.js, line 1728

设置size 此地图的.

Name Type Description
size Size | undefined

地图在 DOM 中的像素尺寸。

setTarget(target)

Map.js, line 1742

设置渲染此地图的目标元素。为实现可访问性（地图导航的焦点和键盘事件），目标元素必须具有正确配置的 tabindex 属性。如果目标元素位于 Shadow DOM 内，则必须在自定义元素的宿主元素上设置 tabindex 属性。

Name Type Description
target HTMLElement | string | undefined

地图渲染所在的元素或元素 ID。

setView(view)

Map.js, line 1755

设置此地图的视图。

Name Type Description
view View | Promise<ViewOptions> | null

控制此地图的视图。也可以传递一个解析为视图构造选项的 Promise。此替代方案允许视图属性由加载视图相关元数据的数据源或其他组件解析。

un(type, listener) inherited

Observable.js, line 173

取消监听特定类型的事件。

Name Type Description
type string | Array.<string>

事件类型或事件类型数组。
listener function

监听器函数。

unset(key, silent) inherited

Object.js, line 262

取消设置一个属性。

Name Type Description
key string

键名。
silent boolean | undefined

取消设置但不触发事件。

updateSize()

Map.js, line 1773

强制重新计算地图视口大小。当第三方代码更改了地图视口的大小时应调用此方法。