类：地图

ol/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。库提供了一个顶层组。这是由 getLayerGroup 和 setLayerGroup 访问的对象。在选项中输入的图层会被添加到此组中，并且 addLayer 和 removeLayer 会更改组内的图层集合。getLayers 是 getLayerGroup().getLayers() 的便捷函数。请注意，LayerGroup 是 BaseLayer 的子类，因此在选项中输入的图层或通过 addLayer 添加的图层可以是组，这些组可以包含更多的组，以此类推。

new Map(options)

Map.js, line 248
Name Type 描述
controls Collection<Control> | Array<Control> | undefined

初始添加到地图的控件。如果未指定，defaults它被使用。在工作线程中，默认不添加任何控件。
pixelRatio number (defaults to window.devicePixelRatio)

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

初始添加到地图的交互。如果未指定，defaults被使用。在工作线程中，默认情况下不会添加任何交互。
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才能渲染地图。如果通过元素传递，容器可以位于外部文档中。要在工作线程中使用或导出地图时，请使用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地图浏览器事件 - 指针移动时触发。注意：在触摸设备上，此事件在地图平移时触发，故不同于鼠标移动事件。
  • postcompose RenderEvent渲染事件 - 在图层渲染完成后触发。若由地图触发，事件对象不包含上下文；若由图层触发，事件对象包含上下文。目前仅WebGL图层会触发此事件。
  • postrender (MapEvent) - 在渲染一个地图帧后触发。
  • precompose RenderEvent渲染事件：在图层渲染之前触发。若由地图触发，事件对象不含上下文设置；若由图层触发，则包含上下文设置。当前仅WebGL图层会触发此事件。
  • propertychange （对象事件（ObjectEvent）） - 当属性更改时触发。
  • rendercomplete (RenderEvent) - 在渲染完成时触发，即当前视口的所有源和瓦片已完成加载，并且所有瓦片已淡入。事件对象不会设置上下文。
  • singleclick (MapBrowserEvent) - 一次真正的单击事件，无拖拽且无双击。为确保非双击，该事件会延迟250毫秒触发。

继承

可观察属性

Name Type 可设置 ObjectEvent type 描述
layerGroup LayerGroup 是的 change:layergroup

包含本地图所有图层的图层组。
size Size | undefined 是 change:size

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

地图渲染的元素或其ID。
view View 是 change:view

控制此地图的视图。

方法

addControl(control)

Map.js, line 613

将指定控件添加到地图中。

Name Type 描述
control Control

控件。

addInteraction(interaction)

Map.js, line 626

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

Name Type 描述
interaction Interaction

待添加的交互。

addLayer(layer)

Map.js, line 637

将给定图层添加到此地图的图层堆叠顺序顶部。若需在图层堆叠顺序中的其他位置添加图层，请使用 getLayers() 以及 Collection 上提供的方法。

Name Type 描述
layer BaseLayer

图层.

addOverlay(overlay)

Map.js, line 655

将指定叠加层添加到地图中。

Name Type 描述
overlay Overlay

覆盖物.

changed() inherited

Observable.js, line 68

递增修订计数器并触发'change'事件。

dispatchEvent(event){boolean | undefined} inherited

events/Target.js, line 85

分发事件并调用所有监听此类型事件的监听器。事件参数可以是字符串，也可以是包含 type 属性的对象。

Name Type 描述
event BaseEvent | string

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

forEachFeatureAtPixel(pixel, callback, options){T | undefined}

Map.js, line 707

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

Name Type 描述
pixel Pixel

像素.
callback function

要素回调：回调函数会被调用并接收两个参数。第一个参数是要素，feature 或 render feature 在像素级别；第二个参数是 layer 要素的属性，在非托管层中为 null。要停止检测，回调函数可返回真值。
options

Optional options.

Name Type 描述
layerFilter undefined | function

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

CSS像素命中容差：检查给定位置周围半径内的像素是否存在地理要素。
checkWrapped boolean (defaults to true)

Check-Wrapped 用于检查在世界宽度 +/-1 范围内的环绕几何体，且仅在使用支持环绕的投影时生效。
返回：
回调结果，即最后一次回调执行的返回值，或第一个返回真值的回调的返回值。

get(key){*} inherited

Object.js, line 135

获取一个值。

Name Type 描述
key string

键名。
返回：
值。

getAllLayers(){Array<Layer>}

Map.js, line 758

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

返回：
图层.

getControls(){Collection<Control>}

Map.js, line 908

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

返回：
控件.

getCoordinateFromPixel(pixel){Coordinate}

Map.js, line 881

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

Name Type 描述
pixel Pixel

地图视口中的像素位置。
返回：
像素坐标。

getEventCoordinate(event){Coordinate}

Map.js, line 811

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

Name Type 描述
event MouseEvent

事件。
返回：
坐标。

getEventPixel(event){Pixel}

Map.js, line 830

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

Name Type 描述
event UIEvent | Object

事件。
返回：
像素.

getFeaturesAtPixel(pixel, options){Array<FeatureLike>}

Map.js, line 741

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

Name Type 描述
pixel Pixel

像素.
options

Optional options.

Name Type 描述
layerFilter undefined | function

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

命中检测容差（以CSS像素为单位）。将检查给定位置周围半径内的像素是否存在要素。
checkWrapped boolean (defaults to true)

包裹检查功能将在 ±1 个世界宽度的范围内检测包裹几何图形，但仅当使用支持包裹的投影时才有效。
返回：
检测到的要素，或空数组（如果未找到）。

getInteractions(){Collection<Interaction>}

Map.js, line 943

获取地图交互集合。修改该集合将改变与地图关联的交互。

交互功能用于平移、缩放和旋转等操作。

返回：
交互.

getKeys(){Array.<string>} inherited

Object.js, line 148

获取对象属性名称列表。

返回：
属性名列表

getLayerGroup(){LayerGroup}

Map.js, line 953

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

返回：
包含此地图中图层的图层组。

getLayers(){Collection<BaseLayer>}

Map.js, line 979

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

返回：
图层.

getOverlayById(id){Overlay | null}

Map.js, line 930

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

Name Type 描述
id string | number

叠加标识符。
返回：
覆盖物.

getOverlays(){Collection<Overlay>}

Map.js, line 918

获取地图叠加层。修改该集合会更改与地图关联的叠加层。

返回：
覆盖物.

getPixelFromCoordinate(coordinate){Pixel}

Map.js, line 1013

根据坐标获取像素。此方法接受用户投影中的坐标，并返回对应的像素。

Name Type 描述
coordinate Coordinate

地图坐标。
返回：
地图视口内的像素坐标。

getProperties(){Object.<string, *>} inherited

Object.js, line 157

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

返回：
对象。

getRevision(){number} inherited

Observable.js, line 79

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

返回：
修订。

getSize(){Size | undefined}

Map.js, line 1052

获取该地图的尺寸。

返回：
DOM中地图的像素大小。

getTarget(){HTMLElement | string | undefined}

Map.js, line 857

获取此地图的渲染目标。请注意，该方法返回在构造函数选项中或通过 setTarget 设置的值：如果设置的是 DOM 元素，则返回该元素；如果设置的是字符串（元素 ID），则返回该字符串。

返回：
地图被渲染的元素或其ID。

getTargetElement(){HTMLElement}

Map.js, line 870

获取此地图渲染到的DOM元素。与getTarget相比，该方法总是返回Element；若地图无目标，则返回null。

返回：
地图被渲染的元素。

getView(){View}

Map.js, line 1065

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

返回：
控制该地图的视图。

getViewport(){HTMLElement}

Map.js, line 1074

获取作为地图视口的元素。

返回：
视口。

hasFeatureAtPixel(pixel, options){boolean}

Map.js, line 784

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

Name Type 描述
pixel Pixel

像素.
options

Optional options.

Name Type 描述
layerFilter undefined | function

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

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

Check-Wrapped 将检查在正负一个世界宽度范围内的包裹几何体，但仅在使用可包裹的投影时才生效。
返回：
在给定像素处是否存在要素？

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

Observable.js, line 152

监听特定类型的事件。

Name Type 描述
type string | Array.<string>

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

监听器函数。
返回：
监听器的唯一键。如果以事件类型数组作为第一个参数调用，则返回将是键的数组。

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

Observable.js, line 164

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

Name Type 描述
type string | Array.<string>

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

监听器函数。
返回：
监听器的唯一键。若以事件类型数组作为第一个参数调用，则返回将是键数组。

removeControl(control){Control | undefined}

Map.js, line 1523

从地图中移除指定的控件。

Name Type 描述
control Control

控件。
返回：
被移除的控件（若控件未找到，则为未定义）。

removeInteraction(interaction){Interaction | undefined}

Map.js, line 1534

从地图中移除指定的交互。

Name Type 描述
interaction Interaction

移除交互
返回：
被移除的交互（若未找到则为未定义）。

removeLayer(layer){BaseLayer | undefined}

Map.js, line 1545

从地图中移除给定图层。

Name Type 描述
layer BaseLayer

图层.
返回：
已移除的图层（若图层未找到，则返回未定义）。

removeOverlay(overlay){Overlay | undefined}

Map.js, line 1565

从地图中移除指定的叠加层。

Name Type 描述
overlay Overlay

覆盖物.
返回：
已删除的覆盖层（若未找到覆盖层，则为未定义）。

render()

Map.js, line 1510

请求在下一个动画帧进行地图渲染。

renderSync()

Map.js, line 1483

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

set(key, value, silent) inherited

Object.js, line 215

设置值。

Name Type 描述
key string

键名。
value *

值。
silent boolean | undefined

更新而不触发事件。

setLayerGroup(layerGroup)

Map.js, line 1687

设置该地图的图层组。

Name Type 描述
layerGroup LayerGroup

包含此地图所有图层的图层组。

setLayers(layers)

Map.js, line 962

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

Name Type 描述
layers Array<BaseLayer> | Collection<BaseLayer>

待添加到地图的图层。

setProperties(values, silent) inherited

Object.js, line 235

设置键值对集合。请注意，此操作会修改现有属性并添加新属性（不会删除任何现有属性）。

Name Type 描述
values Object.<string, *>

值。
silent boolean | undefined

更新时不触发事件。

setSize(size)

Map.js, line 1701

设置此地图的尺寸。

Name Type 描述
size Size | undefined

DOM中地图的像素尺寸。

setTarget(target)

Map.js, line 1715

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

Name Type 描述
target HTMLElement | string | undefined

地图渲染的元素或其ID。

setView(view)

Map.js, line 1728

设置此地图的视图。

Name Type 描述
view View | Promise<ViewOptions> | null

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

un(type, listener) inherited

Observable.js, line 173

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

Name Type 描述
type string | Array.<string>

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

监听函数。

unset(key, silent) inherited

Object.js, line 259

移除属性。

Name Type 描述
key string

键名。
silent boolean | undefined

在不触发事件的情况下取消设置。

updateSize()

Map.js, line 1746

强制重新计算地图视口大小。当第三方代码更改地图视口尺寸时，应调用此函数。