Skip to content

Map

Map

地图类,表示页面上渲染的地图区域

继承Evented

Examples

javascript
const map = new DiMap.Map({
  container: "container",
  style: "dimap://styles/normal",
  center: [116.39, 39.9],
  zoom: 10
})
map.on("load", () => {
  console.log("map loaded")
})

constructor

构造一个地图实例

Parameters

showTerrainWireframe

控制地形网格线框的可见性。

Type: boolean

showTileBoundaries

设置是否显示瓦片边界。

Type: boolean

showCollisionBoxes

设置是否显示碰撞检测边界。

Type: boolean

showPadding

设置是否显示地图填充边界。

Type: boolean

repaint

设置是否重绘地图。

Type: boolean

scrollZoom

地图滚轮缩放处理程序

Type: ScrollZoomHandler

boxZoom

地图框选缩放处理程序

Type: BoxZoomHandler

dragRotate

地图拖动旋转处理程序

Type: DragRotateHandler

dragPan

地图拖动平移处理程序

Type: DragPanHandler

keyboard

地图键盘操作处理程序

Type: KeyboardHandler

doubleClickZoom

地图双击缩放处理程序

Type: DoubleClickZoomHandler

touchZoomRotate

地图触摸缩放旋转处理程序

Type: TouchZoomRotateHandler

touchPitch

地图触摸俯仰处理程序

Type: TouchPitchHandler

操作控件

addControl

添加一个控件

Parameters

参数名必选类型描述
controlControl | IControl待添加的控件
position"top-right" | "top-left" | "bottom-right" | "bottom-left"控件在地图中的位置

Returns Map 返回当前地图实例

removeControl

移除一个控件

Parameters

Returns Map 返回当前地图实例

hasControl

检查地图实例是否包含指定控件

Parameters

Returns boolean 若包含则返回 true,否则返回 false

getContainer

获取包含地图的容器元素。

Returns HTMLElement 包含地图的容器元素。

getCanvasContainer

获取包含地图画布的容器元素。

Returns HTMLElement 包含地图画布的容器元素。

getCanvas

获取地图的画布元素。

Returns HTMLCanvasElement 地图的画布元素。

操作地图实例

resize

调整地图容器的大小

Parameters

  • eventData EventData? 可选参数,包含 width 和 height 属性,表示调整后的大小

Returns Map 返回当前地图实例

getBounds

获取当前地图视野内所有图层的边界范围

Returns LngLatBounds 返回 LngLatBounds 类型的对象,表示边界范围

getMaxBounds

获取地图的最大边界范围

Returns (LngLatBounds | null) 若已设置则返回 LngLatBounds 类型的对象,否则返回 null

setMaxBounds

设置地图的最大边界范围

Parameters

Returns Map 返回当前地图实例

setMinZoom

设置地图的最小缩放级别

Parameters

  • minZoom (number | null)? 可选参数,表示最小缩放级别

Returns Map 返回当前地图实例

getMinZoom

获取地图的最小缩放级别

Returns number 返回最小缩放级别

setMaxZoom

设置地图的最大缩放级别

Parameters

  • maxZoom (number | null)? 可选参数,表示最大缩放级别

Returns Map 返回当前地图实例

getMaxZoom

获取地图的最大缩放级别

Returns number 返回最大缩放级别

setMinPitch

设置地图的最小倾斜度

Parameters

  • minPitch (number | null)? 可选参数,表示最小倾斜度

Returns Map 返回当前地图实例

getMinPitch

获取地图的最小倾斜度

Returns number 返回最小倾斜度

setMaxPitch

设置地图的最大倾斜度

Parameters

  • maxPitch (number | null)? 可选参数,表示最大倾斜度

Returns Map 返回当前地图实例

getMaxPitch

获取地图的最大倾斜度

Returns number 返回最大倾斜度

getRenderWorldCopies

获取当前地图是否启用世界地图复制

Returns boolean 若启用则返回 true,否则返回 false

setRenderWorldCopies

启用或禁用地图的世界地图复制功能

Parameters

  • renderWorldCopies boolean? 可选参数,表示是否启用世界地图复制

Returns Map 返回当前地图实例

坐标转换

project

将经纬度坐标转换为屏幕坐标

Parameters

Returns Point 返回 Point 类型的对象,表示屏幕坐标

unproject

将屏幕坐标转换为经纬度坐标

Parameters

Returns LngLat 返回 LngLat 类型的对象,表示经纬度坐标

getProjection

获取地图投影方式

Returns Projection 返回地图的投影方式

setProjection

设置地图投影方式

Parameters

Returns Map 返回地图实例,方便链式调用

地图移动状态

isMoving

检查地图是否正在移动

Returns boolean 若正在移动则返回 true,否则返回 false

isZooming

检查地图是否正在缩放

Returns boolean 若正在缩放则返回 true,否则返回 false

isRotating

检查地图是否正在旋转

Returns boolean 若正在旋转则返回 true,否则返回 false

监听地图事件

Examples

javascript
| 事件名称                                                   | 是否支持绑定到 `layerId`     |
|-----------------------------------------------------------|---------------------------|
| [`mousedown`](#map.event:mousedown)                       | yes                       |
| [`mouseup`](#map.event:mouseup)                           | yes                       |
| [`mouseover`](#map.event:mouseover)                       | yes                       |
| [`mouseout`](#map.event:mouseout)                         | yes                       |
| [`mousemove`](#map.event:mousemove)                       | yes                       |
| [`mouseenter`](#map.event:mouseenter)                     | yes (必须)                |
| [`mouseleave`](#map.event:mouseleave)                     | yes (必须)                |
| [`click`](#map.event:click)                               | yes                       |
| [`dblclick`](#map.event:dblclick)                         | yes                       |
| [`contextmenu`](#map.event:contextmenu)                   | yes                       |
| [`touchstart`](#map.event:touchstart)                     | yes                       |
| [`touchend`](#map.event:touchend)                         | yes                       |
| [`touchcancel`](#map.event:touchcancel)                   | yes                       |
| [`wheel`](#map.event:wheel)                               |                           |
| [`resize`](#map.event:resize)                             |                           |
| [`remove`](#map.event:remove)                             |                           |
| [`touchmove`](#map.event:touchmove)                       |                           |
| [`movestart`](#map.event:movestart)                       |                           |
| [`move`](#map.event:move)                                 |                           |
| [`moveend`](#map.event:moveend)                           |                           |
| [`dragstart`](#map.event:dragstart)                       |                           |
| [`drag`](#map.event:drag)                                 |                           |
| [`dragend`](#map.event:dragend)                           |                           |
| [`zoomstart`](#map.event:zoomstart)                       |                           |
| [`zoom`](#map.event:zoom)                                 |                           |
| [`zoomend`](#map.event:zoomend)                           |                           |
| [`rotatestart`](#map.event:rotatestart)                   |                           |
| [`rotate`](#map.event:rotate)                             |                           |
| [`rotateend`](#map.event:rotateend)                       |                           |
| [`pitchstart`](#map.event:pitchstart)                     |                           |
| [`pitch`](#map.event:pitch)                               |                           |
| [`pitchend`](#map.event:pitchend)                         |                           |
| [`boxzoomstart`](#map.event:boxzoomstart)                 |                           |
| [`boxzoomend`](#map.event:boxzoomend)                     |                           |
| [`boxzoomcancel`](#map.event:boxzoomcancel)               |                           |
| [`webglcontextlost`](#map.event:webglcontextlost)         |                           |
| [`webglcontextrestored`](#map.event:webglcontextrestored) |                           |
| [`load`](#map.event:load)                                 |                           |
| [`render`](#map.event:render)                             |                           |
| [`idle`](#map.event:idle)                                 |                           |
| [`error`](#map.event:error)                               |                           |
| [`data`](#map.event:data)                                 |                           |
| [`styledata`](#map.event:styledata)                       |                           |
| [`sourcedata`](#map.event:sourcedata)                     |                           |
| [`dataloading`](#map.event:dataloading)                   |                           |
| [`styledataloading`](#map.event:styledataloading)         |                           |
| [`sourcedataloading`](#map.event:sourcedataloading)       |                           |
| [`styleimagemissing`](#map.event:styleimagemissing)       |                           |

on

绑定地图事件处理程序。

Parameters

参数名必选类型描述
typestring | MapLayerEventType | MapEventType要绑定的事件类型。
layerstring | ReadonlyArray<string>事件将被应用到的图层的名称或名称数组。(仅 MapLayerEventType 需要此参数)
listenerFunction事件触发时要调用的回调函数。

Returns Map 该地图的实例。

once

在地图上添加一次性事件监听器,当事件触发时,监听器将自动从地图中移除

Parameters

参数名必选类型描述
typestring | MapLayerEventType | MapEventType要监听的事件类型
layerstring | ReadonlyArray<string>事件将被应用到的图层的名称或名称数组(MapLayerEventType 和异步监听 MapEventType 需要传入此参数)
listenerfunction (ev: any): void事件触发时要调用的回调函数

Returns

Map 返回地图实例,方便链式调用

Promise<any> 返回一个 Promise,以便异步等待事件的第一个参数

off

从地图中移除事件监听器

Parameters

参数名必选类型描述
typestring | MapLayerEventType | MapEventType要移除的事件类型
layerstring | ReadonlyArray<string>事件被应用到的图层的名称或名称数组(仅 MapLayerEventType 需要此参数)
listenerfunction (ev: any): void要移除的特定监听器函数(如省略则移除该类型的所有监听器)

Returns Map 返回地图实例,方便链式调用

地图元素查询

queryRenderedFeatures

查询指定点或框范围内的渲染要素

Parameters

参数名必选类型描述
pointOrBoxPointLike | [PointLike, PointLike]指定点或框范围
optionsObject可选参数对象
options.layersArray<string>指定查询的图层
options.filterArray过滤查询结果的函数数组
options.limitnumber查询结果的最大数量
options.offsetnumber查询结果的偏移量

Returns Array<MapboxGeoJSONFeature> 渲染要素数组

querySourceFeatures

查询指定数据源的 features

Parameters

querySourceFeatures 方法 - 查询指定数据源的要素

参数名必选类型描述
sourceIDstring数据源的 ID
parametersobject过滤选项
parameters.sourceLayerstringundefined源图层名称
parameters.filterany[]| undefined过滤条件数组
parameters.validateFilterOptions是否验证过滤条件

Returns Array<MapboxGeoJSONFeature> 匹配的 features 数组

操作地图样式表

setStyle

设置地图的样式

Parameters

setStyle 方法 - 设置地图的样式

参数名必选类型描述
styleStyle | string新的地图样式
optionsobject可选配置项
options.diffboolean| undefined是否使用差分算法来比较和更新新旧样式
options.localIdeographFontFamilystring | undefined中文本地字体的名称

Returns Map 当前地图对象

getStyle

返回地图当前使用的样式。

Returns Style 当前地图的样式。

isStyleLoaded

判断地图的样式是否已加载完毕。

Returns boolean 如果样式已加载完毕,则返回true;否则返回false。

操作地图数据源

addSource

添加地图数据源。

Parameters

参数名必选类型描述
idstring数据源的唯一标识符
sourceAnySourceData数据源配置对象

Returns Map 当前地图实例。

isSourceLoaded

判断指定的地图数据源是否已经加载完毕。

Parameters

  • id string 数据源的唯一标识符。

Returns boolean 如果数据源已加载完毕,则返回true;否则返回false。

areTilesLoaded

判断所有地图瓦片是否已经加载完毕。

Returns boolean 如果所有地图瓦片都已经加载完毕,则返回true;否则返回false。

removeSource

移除指定的地图数据源。

Parameters

  • id string 数据源的唯一标识符。

Returns Map 当前地图实例。

getSource

获取指定的地图数据源对象。

Parameters

  • id string 数据源的唯一标识符。

Returns (AnySourceImpl | undefined) 指定的地图数据源对象,如果不存在则返回undefined。

操作图像

addImage

添加一个新的图片到地图中。

Parameters

参数名必选类型描述
namestring图片的唯一标识符
imageHTMLImageElement | ArrayBufferView | {width: number, height: number, data: (Uint8Array | Uint8ClampedArray)} | ImageData | ImageBitmap图片数据
optionsObject可选项
options.pixelRationumber像素比例,默认值为1
options.sdfboolean是否使用SDF渲染,默认值为false
options.stretchXArray<[number, number]>横向拉伸范围
options.stretchYArray<[number, number]>纵向拉伸范围
options.content[number, number, number, number]图片内容区域

Returns void

updateImage

更新地图中指定名称的图片。

Parameters

updateImage 方法 - 更新地图中指定名称的图片

参数名必选类型描述
namestring图片的唯一标识符
imageHTMLImageElement | ArrayBufferView | {width: number, height: number, data: (Uint8Array | Uint8ClampedArray)} | ImageData | ImageBitmap新的图片数据

Returns void

hasImage

判断地图中是否存在指定名称的图片。

Parameters

  • name string 图片的唯一标识符。

Returns boolean 存在返回true,不存在返回false。

removeImage

删除地图中指定名称的图片。

Parameters

  • name string 图片的唯一标识符。

Returns void

loadImage

加载图片并调用回调函数。

Parameters

参数名必选类型描述
urlstring图片的URL
callbackFunction回调函数,如果加载失败则传入错误对象,否则传入图片对象

Returns void

listImages

获取所有已加载的图像的名称列表。

Returns Array<string> 包含所有已加载的图像名称的数组。

操作图层

addLayer

添加一个图层到地图中。

Parameters

参数名必选类型描述
layerAnyLayer要添加到地图中的图层
beforestring在此图层之前插入的另一个图层的ID

Returns Map 该地图的实例。

moveLayer

将指定图层移动到另一个图层之前。

Parameters

参数名必选类型描述
idstring要移动的图层的ID
beforeIdstring目标位置之前的另一个图层的ID

Returns Map 该地图的实例。

removeLayer

从地图中删除指定的图层。

Parameters

  • id string 要删除的图层的ID。

Returns Map 该地图的实例。

getLayer

获取指定的图层对象。

Parameters

  • id string 要获取的图层的ID。

Returns AnyLayer 指定的图层对象。

setFilter

为指定的图层设置过滤器。

Parameters

setFilter 方法 - 为指定的图层设置过滤器

参数名必选类型描述
layerstring要设置过滤器的图层的ID
filterArray<any> | boolean | null过滤器函数或布尔表达式,设为null可删除现有过滤器
optionsFilterOptions | null过滤器选项

Returns Map 该地图的实例。

setLayerZoomRange

设置指定图层的缩放级别范围。

Parameters

参数名必选类型描述
layerIdstring要设置缩放级别范围的图层的ID
minzoomnumber允许图层显示的最小缩放级别
maxzoomnumber允许图层显示的最大缩放级别

Returns Map 该地图的实例。

getFilter

获取指定图层的过滤器。

Parameters

  • layer string 要获取过滤器的图层的ID。

Returns Array<any> 该图层的过滤器。

setPaintProperty

为指定图层设置指定属性的绘制属性。

Parameters

参数名必选类型描述
layerstring要设置绘制属性的图层的ID
namestring要设置的绘制属性的名称
valueany要设置的绘制属性的值
optionsFilterOptions | null设置绘制属性的选项

Returns Map 该地图的实例。

getPaintProperty

获取指定图层的指定绘制属性的值。

Parameters

参数名必选类型描述
layerstring要获取绘制属性值的图层的ID
namestring要获取的绘制属性的名称

Returns any 指定的绘制属性的值。

setLayoutProperty

为指定图层设置指定属性的布局属性。

Parameters

参数名必选类型描述
layerstring要设置布局属性的图层的ID
namestring要设置的布局属性的名称
valueany要设置的布局属性的值
optionsFilterOptions | null设置布局属性的选项

Returns Map 该地图的实例。

getLayoutProperty

获取指定图层的指定布局属性的值。

Parameters

参数名必选类型描述
layerstring要获取布局属性的图层的ID
namestring要获取的布局属性的名称

Returns any 指定图层的指定布局属性的值。

操作地图样式属性

setLight

设置地图的灯光。

Parameters

参数名必选类型描述
lightLight要设置的灯光
optionsFilterOptions设置灯光的选项

Returns Map 该地图的实例。

getLight

获取地图的灯光。

Returns Light 地图的灯光。

setTerrain

设置地图的地形。

Parameters

Returns Map 该地图的实例。

getTerrain

获取地图的地形。

Returns (TerrainSpecification | null) 地图的地形规范。

getFog

获取地图雾效对象,如果没有设置雾效则返回 null

Returns (Fog | null) 返回地图雾效对象或 null

setFog

设置地图雾效

Parameters

  • fog Fog 要设置的雾效对象

Returns Map 返回地图实例,方便链式调用

操作地图元素状态

setFeatureState

设置指定要素的状态。

Parameters

参数名必选类型描述
featureFeatureIdentifier | MapboxGeoJSONFeature要设置状态的要素标识符或 GeoJSON 要素
stateObject<string, any>要为要素设置的状态对象

Returns void

getFeatureState

获取指定要素的状态。

Parameters

Returns Object<string, any> 要素的状态对象。

removeFeatureState

从指定要素中删除指定的状态属性,或从指定要素中删除所有状态属性。

Parameters

参数名必选类型描述
targetFeatureIdentifier | MapboxGeoJSONFeature要从中删除状态属性的要素标识符或 GeoJSON 要素
keystring要删除的状态属性的键。如果未指定,则删除所有状态属性

Returns void

地图生命周期

loaded

检查地图是否已加载。

Returns boolean 如果地图已加载,则为 true;否则为 false。

remove

从页面中删除地图。

Returns void

triggerRepaint

重新绘制地图。

Returns void

操作相机视角

queryTerrainElevation

查询给定点的地形高程。

Parameters

参数名必选类型描述
lngLatLngLatLike要查询高程的点的地理坐标
optionsElevationQueryOptions查询高程的选项

Returns (number | null) 给定点的地形高程(单位:米)。如果查询失败,则返回 null。

getCenter

获取地图的中心点坐标。

Returns LngLat 地图中心点的经纬度坐标。

setCenter

将地图中心点设置为指定坐标。

Parameters

参数名必选类型描述
centerLngLatLike新的地图中心点的经纬度坐标
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

panBy

以指定的像素偏移量平移地图。

Parameters

参数名必选类型描述
offsetPointLike像素坐标的偏移量,指定为{ x, y }
optionsAnimationOptions平移动画的选项
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

panTo

将地图中心点平移到指定的经纬度坐标。

Parameters

参数名必选类型描述
lnglatLngLatLike目标中心点的经纬度坐标
optionsAnimationOptions平移动画的选项
eventdataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

getZoom

获取地图的当前缩放级别。

Returns number 当前缩放级别。

setZoom

将地图的缩放级别设置为指定的级别。

Parameters

参数名必选类型描述
zoomnumber目标缩放级别
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

zoomTo

缩放地图以达到指定的缩放级别。

Parameters

参数名必选类型描述
zoomnumber目标缩放级别
optionsAnimationOptions缩放动画的选项
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

zoomIn

将地图的缩放级别增加一级。

Parameters

参数名必选类型描述
optionsAnimationOptions缩放动画的选项
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

zoomOut

将地图的缩放级别减少一级。

Parameters

参数名必选类型描述
optionsAnimationOptions缩放动画的选项
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

getBearing

获取地图的当前方向(以度数为单位)。

Returns number 当前方向的角度(以度数为单位)。

setBearing

将地图的方向设置为指定的角度(以度数为单位)。

Parameters

参数名必选类型描述
bearingnumber目标方向的角度(以度数为单位)
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

getPadding

获取地图填充区域的大小,单位为像素。

Returns PaddingOptions 当前填充区域的大小。

setPadding

将地图填充区域设置为指定大小,单位为像素。

Parameters

参数名必选类型描述
paddingPaddingOptions目标填充区域的大小
eventDataEventData传递给事件处理程序的事件数据

Returns Map 该地图的实例。

rotateTo

旋转地图,使其朝向指定方向。

Parameters

参数名必选类型描述
bearingnumber旋转后地图的方向(以度为单位,正北方向为0度,顺时针旋转)
optionsAnimationOptions旋转动画的选项
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

resetNorth

重置地图的方向为正北方向。

Parameters

参数名必选类型描述
optionsAnimationOptions旋转动画的选项
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

resetNorthPitch

重置地图的方向和倾斜角度为初始状态。

Parameters

参数名必选类型描述
optionsAnimationOptions | null重置动画的选项
eventDataEventData| null触发事件时的数据

Returns Map 该地图的实例。

snapToNorth

旋转地图,使其方向朝向正北方向。

Parameters

参数名必选类型描述
optionsAnimationOptions旋转动画的选项
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

getPitch

获取地图的倾斜角度。

Returns number 地图的倾斜角度(以度为单位)。

setPitch

设置地图的倾斜角度。

Parameters

参数名必选类型描述
pitchnumber要设置的倾斜角度(以度为单位)
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

cameraForBounds

计算缩放和中心点以匹配给定的边界。

Parameters

参数名必选类型描述
boundsLngLatBoundsLike匹配的边界
optionsCameraForBoundsOptions计算相机选项

Returns (CameraForBoundsResult | undefined) 一个包含缩放、中心点和边框信息的对象。

fitBounds

调整视野以适合指定的地理边界。

Parameters

参数名必选类型描述
boundsLngLatBoundsLike地理边界
optionsFitBoundsOptions拟合边界选项
eventDataEventData触发事件的数据

Returns Map 该地图的实例。

fitScreenCoordinates

调整视野以适合两个屏幕点之间的地理边界,使其呈现在窗口的正面。

Parameters

参数名必选类型描述
p0PointLike屏幕上的点的像素坐标
p1PointLike屏幕上的点的像素坐标
bearingnumber视角的旋转方向(以度为单位)
optionsany可选参数
eventDataEventData触发事件的数据

Returns Map 该地图的实例。

jumpTo

立即跳转到指定的地图状态,没有动画过渡。

Parameters

参数名必选类型描述
optionsCameraOptions指定的地图状态
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

getFreeCameraOptions

获取自由摄像机模式的选项。

Returns FreeCameraOptions 自由摄像机模式的选项。

setFreeCameraOptions

设置自由摄像机模式的选项。

Parameters

参数名必选类型描述
optionsFreeCameraOptions自由摄像机模式的选项
eventDataObject触发事件时的数据

Returns Map 该地图的实例。

easeTo

平滑地过渡到指定的地图状态。

Parameters

参数名必选类型描述
optionsEaseToOptions指定的地图状态
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

flyTo

平滑地飞行到指定的地图状态。

Parameters

参数名必选类型描述
optionsFlyToOptions指定的地图状态
eventDataEventData触发事件时的数据

Returns Map 该地图的实例。

isEasing

是否正在进行平滑的过渡动画。

Returns boolean 如果正在进行平滑的过渡动画,则为 true,否则为 false。

stop

停止当前正在进行的平滑过渡动画。

Returns Map 该地图的实例。