Map

此类是地图API的核心类，用来实例化一个地图。

构造函数

#new Map(container: string | HTMLElement, options?: MapOptions): Map

在指定的容器内创建地图实例，之后需要调用Map.centerAndZoom()方法对地图进行初始化。未进行初始化的地图将不能进行任何操作。

参数类型说明

container string | HTMLElement Map对象的容器可以是DOM元素对象或容器的ID

options 可选

MapOptions

地图初始化选项

属性	类型	说明
`center`	`Point`	地图初始中心点。需与 zoom 一同传入才会自动初始化视野。
`displayOptions`	`DisplayOptions`	配置地图显示元素。该参数详细信息请参见 setDisplayOptions 方法。
`enableAdaptiveMinZoom`	`boolean`	是否自动限制最小缩放级别
`enableAutoResize`	`boolean`	是否自动检测地图容器变化并自适应
`enableDblclickZoom`	`boolean`	是否启用双击缩放，左键双击放大、右键双击缩小
`enableDragging`	`boolean`	是否允许拖拽（包括了旋转、倾斜、移动）
`enableIconInfoWindow`	`boolean`	点击底图标注时，是否显示信息窗，在enableIconClick为true时生效
`enableKeyboard`	`boolean`	是否开启键盘快捷键操作地图
`enableMapClick`	`boolean`	是否开启底图可点功能
`enablePinchZoom`	`boolean`	是否允许手势缩放地图
`enableRotate`	`boolean`	是否允许地图旋转
`enableRotateGestures`	`boolean`	是否允许通过手势旋转地图
`enableTilt`	`boolean`	是否允许地图倾斜
`enableTiltGestures`	`boolean`	是否允许通过手势倾斜地图
`enableWheelZoom`	`boolean`	是否允许鼠标滚轮、触摸板滑动缩放地图，默认值为 true
`fixCenterWhenPinch`	`boolean`	手势缩放是否固定中心点，不固定时由手指中心点决定
`fixCenterWhenResize`	`boolean`	地图容器尺寸变化时，是否保持地图中心点不变。默认情况下，当地图容器尺寸变化时，地图上的任意一点距离地图左上角的位置不变，即视觉上地图是稳定的，但是地图的中心点坐标却是变化的。
`heading`	`number`	地图初始旋转角度，0 表示正北，顺时针为正，单位为度，取值范围 [0, 360)。
`mapType`	`MapTypeId`	地图类型
`maxZoom`	`number`	地图允许展示的最大级别，取值范围 [3, 21]
`minZoom`	`number`	地图允许展示的最小级别。取值范围 [3, 21]
`overlayTop`	`boolean`	覆盖物是否显示在文字上面
`tilt`	`number`	地图初始倾斜角度，0 表示俯视，单位为度，取值范围 [0, 73]。
`zoom`	`number`	地图初始缩放级别。需与 center 一同传入才会自动初始化视野。
`zoomCenter`	`Point`	指定缩放中心点，当设置此属性后，地图缩放总是以此点为中心进行。

返回值 Map

示例代码1

const map = new BMap.Map('container');

示例代码2

const map = new BMap.Map('container', {
  center: new BMap.Point(116.378351, 39.89585),
  zoom: 18,
  enableWheelZoom: true
});

方法

#addContextMenu(menu: ContextMenu): void

添加右键菜单

参数	类型	说明
`menu`	`ContextMenu`	右键菜单实例

返回值 void

示例代码1

const contextMenu = new BMap.ContextMenu();
contextMenu.addItem(new BMap.MenuItem('放大', () => map.zoomIn()));
map.addContextMenu(contextMenu);

#addControl(control: Control): void
将控件添加到地图，一个控件实例只能向地图中添加一次

参数类型说明
control Control 控件实例
返回值 void
示例代码1
```
map.addControl(new BMap.NavigationControl());
```

参数	类型	说明
`control`	`Control`	控件实例

#addEventListener<K extends keyof MapEventMap>(
event: K,
handler: (e: MapEventMap[K]) => void,
): void

添加事件监听

参数	类型	说明
`event`	`K`	事件名称
`handler`	`(e: MapEventMap[K]) => void`	事件处理函数

返回值 void

示例代码1：地图初始化事件

map.addEventListener('load', (e) => {
  console.log(e.type, e.target, e.zoom);
});

示例代码2：鼠标点击事件

map.addEventListener('click', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('dblclick', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('rightclick', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('rightdblclick', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});

示例代码3：鼠标交互事件

map.addEventListener('mousemove', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('mousedown', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('mouseup', (e) => {
  console.log(e.type, e.target, e.point, e.pixel, e.overlay);
});
map.addEventListener('mouseover', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('mouseout', (e) => {
  console.log(e.type, e.target);
});

示例代码4：地图拖拽事件

map.addEventListener('dragstart', (e) => {
  console.log(e.type, e.target, e.pixel, e.point);
});
map.addEventListener('dragging', (e) => {
  console.log(e.type, e.target, e.pixel, e.point);
});
map.addEventListener('dragend', (e) => {
  console.log(e.type, e.target, e.pixel, e.point);
});

示例代码5：地图移动事件

map.addEventListener('movestart', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('moving', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('moveend', (e) => {
  console.log(e.type, e.target);
});

示例代码6：地图缩放事件

map.addEventListener('zoomstart', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('zoomend', (e) => {
  console.log(e.type, e.target);
});

示例代码7：地图缩放过程与越界事件

map.addEventListener('zooming', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('zoomexceeded', (e) => {
  console.log(e.type, e.target, e.targetZoom);
});

示例代码8：覆盖物事件

map.addEventListener('addoverlay', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('removeoverlay', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('clearoverlays', (e) => {
  console.log(e.type, e.target);
});

示例代码9：覆盖物添加前事件

map.addEventListener('beforeaddoverlay', (e) => {
  console.log(e.type, e.target);
});

示例代码10：控件与右键菜单事件

map.addEventListener('addcontrol', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('removecontrol', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('addcontextmenu', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('removecontextmenu', (e) => {
  console.log(e.type, e.target);
});

示例代码11：地图类型事件

map.addEventListener('maptypechange', (e) => {
  console.log(e.type, e.target, e.mapType, e.zoomLevel);
});

示例代码12：样式与语言事件

map.addEventListener('style_willchange', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('style_loaded', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('style_loaded_error', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('style_loaded_timeout', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('language_change', (e) => {
  console.log(e.type, e.target);
});

示例代码13：瓦片加载与地图尺寸事件

map.addEventListener('tilesloaded', (e) => {
  console.log(e.type, e.target);
});
map.addEventListener('resize', (e) => {
  console.log(e.type, e.target, e.size);
});

#addLayer(
    layer:
        | TileLayer
        | RasterTileLayer
        | WMSLayer
        | WMTSLayer
        | GeoJSONLayer
        | DistrictLayer
        | DOMLayer
        | LineLayer
        | FillLayer
        | PointShapeLayer
        | PointIconLayer,
): void
统一添加图层方法，自动根据图层类型分发到对应处理逻辑。支持NormalLayer、TileLayer、GeoJSONLayer、DistrictLayer、DOMLayer等所有图层类型

参数类型说明
layer | TileLayer | RasterTileLayer | WMSLayer | WMTSLayer | GeoJSONLayer | DistrictLayer | DOMLayer | LineLayer | FillLayer | PointShapeLayer | PointIconLayer 图层实例
返回值 void
示例代码1
```
const lineLayer = new BMap.LineLayer({ style: { strokeColor: '#0055ff', strokeWeight: 4 } });
map.addLayer(lineLayer);
```

参数	类型	说明
`layer`	`\| TileLayer \| RasterTileLayer \| WMSLayer \| WMTSLayer \| GeoJSONLayer \| DistrictLayer \| DOMLayer \| LineLayer \| FillLayer \| PointShapeLayer \| PointIconLayer`	图层实例

#addMapLabels(labels: MapLabel | MapLabel[]): string[]

在底图上添加文字，这些文字会和底图文字一同参与避让。

参数	类型	说明
`labels`	`MapLabel \| MapLabel[]`	底图标注数组

返回值 string[]

实际写入的 uid 数组，可用 removeMapLabels 移除

示例代码1

map.addMapLabels([
  {
    text: '自定义标注',
    position: new BMap.Point(116.404, 39.915)
  }
]);

示例代码2

map.addMapLabels([
  {
     position: new BMap.Point(116, 39),
     text: '自定义标注2',
     displayRange: [3, 21],
     textMargin: 8,
      style: {
         fontSize: 30,
          haloSize: 2,
          color: 'rgba(80,92,88,1)',
          strokeColor: '#fff'
      },
      uid: 'fd7e3d0c879487d4c7f025be',
      direction: 3
  }
]);

#addOverlay(overlay: Overlay): void
将覆盖物添加到地图中，一个覆盖物实例只能向地图中添加一次

参数类型说明
overlay Overlay 覆盖物实例
返回值 void
示例代码1
```
const marker = new BMap.Marker(new BMap.Point(116.404, 39.915));
map.addOverlay(marker);
```

参数	类型	说明
`overlay`	`Overlay`	覆盖物实例

#addTileLayer(tileLayer: TileLayer): void
添加一个自定义地图图层

参数类型说明
tileLayer TileLayer 自定义图层实例
返回值 void
已弃用
自 4.0 起
请使用 addLayer

参数	类型	说明
`tileLayer`	`TileLayer`	自定义图层实例

#cancelViewAnimation(viewAnimation: ViewAnimation): void

停止视角动画

参数	类型	说明
`viewAnimation`	`ViewAnimation`	要停止的视角动画实例

返回值 void

示例代码1

const viewAnimation = new BMap.ViewAnimation([
  { center: new BMap.Point(116.404, 39.915), zoom: 11, tilt: 0, heading: 0, percentage: 0 },
  { center: new BMap.Point(116.404, 39.915), zoom: 18, tilt: 60, heading: 180, percentage: 1 }
], { duration: 5000 });
map.startViewAnimation(viewAnimation);
// 2 秒后取消动画
setTimeout(() => {
  map.cancelViewAnimation(viewAnimation);
}, 2000);

#centerAndZoom(
    center: Point,
    zoom: number,
    options?: { callback?: () => void; noAnimation?: boolean },
): void

同时设置地图的中心点和缩放级别。默认无动画效果。

参数类型说明

center Point 地图中心点坐标

zoom number 缩放级别

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画完成后的回调函数
`noAnimation` 可选	`boolean`	是否禁用动画效果，默认值：true

返回值 void

示例代码1

map.centerAndZoom(new BMap.Point(116.404, 39.915), 15);

示例代码2：启用动画

map.centerAndZoom(new BMap.Point(116.404, 39.915), 15, {
  noAnimation: false
});

示例代码3：设置动画完成后的回调

map.centerAndZoom(new BMap.Point(116.404, 39.915), 15, {
  noAnimation: false,
  callback: () => console.log('动画完成')
});

centerAndZoom(
    city: string,
    zoom?: number,
    options?: { callback?: () => void; noAnimation?: boolean },
): void

按城市名设置地图中心点和缩放级别。不传zoom时，地图将自动适配展示该城市的最佳缩放级别

参数类型说明

city string 城市名称，如"北京"

zoom 可选 number 缩放级别，不传则自动适配

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画完成后的回调函数
`noAnimation` 可选	`boolean`	是否禁用动画效果，默认值：true

返回值 void

示例代码4

map.centerAndZoom('北京');

示例代码5：指定缩放级别

map.centerAndZoom('北京', 12);

#checkResize(): void
地图容器变化后调用此方法用来重新铺图

返回值 void

#clearLabels(): void
清空当前map所有的自定义底图标注

返回值 void

#clearOverlays(): void
清除地图上所有覆盖物

返回值 void

#closeInfoWindow(): void
关闭在地图上打开的信息窗口。在标注上打开的信息窗口也可通过此方法进行关闭

返回值 void

#continueViewAnimation(viewAnimation: ViewAnimation): void

继续视角动画

参数	类型	说明
`viewAnimation`	`ViewAnimation`	要继续的视角动画实例

返回值 void

示例代码1

const viewAnimation = new BMap.ViewAnimation([
  { center: new BMap.Point(116.404, 39.915), zoom: 11, tilt: 0, heading: 0, percentage: 0 },
  { center: new BMap.Point(116.404, 39.915), zoom: 18, tilt: 60, heading: 180, percentage: 1 }
], { duration: 5000 });
map.startViewAnimation(viewAnimation);
// 2 秒后暂停，再 2 秒后继续
setTimeout(() => {
  map.pauseViewAnimation(viewAnimation);
  setTimeout(() => {
    map.continueViewAnimation(viewAnimation);
  }, 2000);
}, 2000);

#destroy(): void
销毁地图，当使用 WebGL 渲染地图时，如果确认不再使用该地图实例，则需要调用本方法销毁 WebGL 上下文，否则频繁创建新地图实例会导致浏览器报：too many WebGL context 的警告

返回值 void

#disableAutoResize(): void
禁用自动适应容器尺寸变化

返回值 void

#disableContinuousZoom(): void
关闭双击平滑缩放效果

返回值 void

#disableDoubleClickZoom(): void
取消地图双击缩放

返回值 void

#disableDragging(): void
禁用地图拖拽

返回值 void

#disableIconInfoWindow(): void
关闭点击底图标注后自动展示信息窗口

返回值 void

#disableInertialDragging(): void
禁用地图惯性拖拽

返回值 void

#disableKeyboard(): void
禁用键盘操作

返回值 void

#disableMapClick(): void
关闭底图可点功能

返回值 void

#disablePinchToZoom(): void
禁用双指缩放地图。

返回值 void

#disablePreferredLanguage(): void
禁用首选语言

返回值 void

#disableResizeOnCenter(): void
关闭图区resize中心点不变

返回值 void

#disableRotate(): void
禁用地图旋转

返回值 void

#disableRotateGestures(): void
禁用手势旋转地图

返回值 void

#disableScrollWheelZoom(): void
禁止地图被鼠标滚轮缩放

返回值 void

#disableTilt(): void
禁用地图倾斜

返回值 void

#enableAutoResize(): void
启用自动适应容器尺寸变化，默认启用

返回值 void

#enableContinuousZoom(): void
开启双击平滑缩放效果

返回值 void

#enableDoubleClickZoom(): void
启用地图双击缩放，左键双击放大、右键双击缩小

返回值 void

#enableDragging(): void
启用地图拖拽，默认启用

返回值 void

#enableIconInfoWindow(): void
开启点击底图标注后自动展示信息窗口，同时会开启底图标注点击

返回值 void

#enableInertialDragging(): void
启用地图惯性拖拽，默认禁用

返回值 void

#enableKeyboard(): void
启用键盘操作，默认禁用。键盘的上、下、左、右键可连续移动地图。同时按下其中两个键可使地图进行对角移动。PgUp、PgDn、Home和End键会使地图平移其1/2的大小。+、-键会使地图放大或缩小一级

返回值 void

#enableMapClick(): void
开启底图可点功能

返回值 void

#enablePinchToZoom(): void
启用双指缩放地图。

返回值 void

#enablePreferredLanguage(language?: Language): void
启用首选语言

参数类型说明
language 可选 Language 语言代码，使用 BMAP_LANGUAGE_* 常量
返回值 void
示例代码1
```
map.enablePreferredLanguage(BMAP_LANGUAGE_EN);
```

参数	类型	说明
`language` 可选	`Language`	语言代码，使用 `BMAP_LANGUAGE_*` 常量

#enableResizeOnCenter(): void
开启图区resize中心点不变

返回值 void

#enableRotate(): void
启用地图旋转

返回值 void

#enableRotateGestures(): void
启用手势旋转地图

返回值 void

#enableScrollWheelZoom(): void
允许地图可被鼠标滚轮缩放，默认禁用

返回值 void

#enableTilt(): void
启用地图倾斜

返回值 void

#flyTo(
    center: Point,
    zoom: number,
    options?: { callback?: () => void; noAnimation?: boolean },
): void

飞到指定的中心点和级别，提供给定位缩放地图使用

参数类型说明

center Point 目标中心点

zoom number 目标缩放级别

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后的回调函数
`noAnimation` 可选	`boolean`	是否禁用动画效果

返回值 void

示例代码1

map.flyTo(new BMap.Point(116.404, 39.915), 15);

示例代码2

map.flyTo(new BMap.Point(116.404, 39.915), 15, {
  callback: () => console.log('飞行完成')
});

#getBounds(): Bounds
获取地图当前视野范围的矩形区域，以地理坐标表示。如果地图尚未初始化则返回一个空的 Bounds 实例。

返回值 Bounds

#getCenter(): Point
返回地图当前中心点

返回值 Point

#getContainer(): HTMLElement
返回地图的DOM容器元素。当创建用户自定义控件时，需要自行实现Control.initialize()方法，并将控件的容器元素添加到地图上，通过此方法可获得地图容器

返回值 HTMLElement

#getContainerSize(): Size
获取地图容器尺寸

返回值 Size

#getCoordType(): string
获取地图坐标类型，为CoordType常量

返回值 string

#getCurrentMaxTilt(): number
获取当前地图允许的最大倾斜角度

返回值 number

#getDefaultCursor(): string
获取地图默认的鼠标指针样式，返回cursor值

返回值 string

#getDistance(start: Point, end: Point): number
返回两点之间的距离，单位是米

参数类型说明
start Point 起点地理坐标
end Point 终点地理坐标
返回值 number
示例代码1
```
const dist = map.getDistance(
  new BMap.Point(116.404, 39.915),
  new BMap.Point(117.200, 39.084)
);
console.log(`距离：${dist.toFixed(0)} 米`);
```

参数	类型	说明
`start`	`Point`	起点地理坐标
`end`	`Point`	终点地理坐标

#getDraggingCursor(): string
返回拖拽地图时的鼠标指针样式

返回值 string

#getHeading(): number
获取地图当前旋转角度。返回值为带符号角度，取值范围 -180~180，正值表示顺时针偏离正北，负值表示逆时针偏离正北。注意：返回值与 setHeading 的入参不保证数值一致，例如 setHeading(270) 后 getHeading() 返回 -90。

返回值 number

#getInfoWindow(): InfoWindow
获取当前打开的信息窗口实例，如果当前地图没有处于打开状态信息窗口，则返回 null

返回值 InfoWindow

#getMapType(): MapType
返回当前地图类型实例，与全局常量 BMAP_NORMAL_MAP 等同源

返回值 MapType

#getMaxZoom(): number
获取地图允许的最大缩放级别

返回值 number

#getMinZoom(): number
获取地图允许的最小缩放级别

返回值 number

#getOverlays(): Overlay[]
获取当前地图上的所有覆盖物，返回覆盖物对象的集合

返回值 Overlay[]

#getPanes(): MapPanes
获取覆盖物容器元素，返回地图覆盖物容器对象

返回值 MapPanes

#getScreenshot(): string
获取地图截图，地球模式不支持。需要初始化地图配置preserveDrawingBuffer：true，否则是黑屏

返回值 string

#getSize(): Size
返回地图当前尺寸，以像素表示

返回值 Size

#getTheme(): string
获取当前地图 UI 主题名称，未设置时返回 'light'

返回值 string

#getTilt(): number
获取地图当前倾斜角度

返回值 number

#getViewport(view: Bounds | Point[], viewportOptions?: ViewportOptions): Viewport

根据提供的地理区域或坐标获得最佳的地图视野，返回的对象中包含center和zoom属性，分别表示地图的中心点和级别。此方法仅返回视野信息，不会将新的中心点和级别做用到当前地图上

参数类型说明

view Bounds | Point[] 地理坐标数组

viewportOptions 可选

ViewportOptions

视野计算选项

属性	类型	说明
`callback`	`Function`	视野调整结束后的回调函数
`enableAnimation`	`boolean`	是否启用动画效果移动地图，当调整后的级别与当前地图级别一致时，将使用动画效果移动地图
`margins`	`number[]`	视野调整的预留边距，依次为上、右、下、左，例如： margins: [30, 20, 0, 20] 表示坐标点会限制在上述区域内
`zoomFactor`	`number`	地图级别的偏移量，您可以在方法得出的结果上增加一个偏移值。例如map.setViewport计算出地图的级别为10，如果zoomFactor为-1，则最终的地图级别为9

返回值 Viewport

示例代码1

const vp = map.getViewport([
  new BMap.Point(116.404, 39.915),
  new BMap.Point(117.200, 39.084)
]);
console.log(vp.center, vp.zoom);

示例代码2

const vp = map.getViewport(
  [
    new BMap.Point(116.404, 39.915),
    new BMap.Point(117.200, 39.084)
  ],
  {
    margins: [50, 50, 50, 50]
  }
);
console.log(vp.center, vp.zoom);

#getZoom(): number
返回地图当前缩放级别

返回值 number

#getZoomUnits(level?: number): number
返回当前地图级别，一个像素对应多少单位的平面墨卡托坐标

参数类型说明
level 可选 number
返回值 number

参数	类型	说明
`level` 可选	`number`

#hideOverlayContainer(): void
不显示覆盖物

返回值 void

#isLoaded(): boolean
返回地图是否经过centerAndZoom进行初始化

返回值 boolean

#lnglatToMercator(lng: number, lat: number): [number, number]
经纬度球体坐标转换为墨卡托平面坐标

参数类型说明
lng number 经度
lat number 纬度
返回值 [number, number]
示例代码1
```
const mc = map.lnglatToMercator(116.404, 39.915);
```

参数	类型	说明
`lng`	`number`	经度
`lat`	`number`	纬度

#mercatorToLnglat(mcLng: number, mcLat: number): [number, number]
墨卡托平面坐标转换为经纬度球体坐标

参数类型说明
mcLng number 墨卡托经度
mcLat number 墨卡托纬度
返回值 [number, number]
示例代码1
```
const lnglat = map.mercatorToLnglat(12958190, 4825923);
```

参数	类型	说明
`mcLng`	`number`	墨卡托经度
`mcLat`	`number`	墨卡托纬度

#openInfoWindow(infoWnd: InfoWindow, point: Point): void
在地图上打开信息窗口

参数类型说明
infoWnd InfoWindow 信息窗口实例
point Point 信息窗口显示的地理坐标
返回值 void

参数	类型	说明
`infoWnd`	`InfoWindow`	信息窗口实例
`point`	`Point`	信息窗口显示的地理坐标

#overlayPixelToPoint(
pixel: Pixel,
options?: { center?: Point; zoom?: number },
): Point

根据覆盖物容器的坐标获取对应的地理坐标

参数类型说明

pixel Pixel 覆盖物容器像素坐标

options 可选

object

可选配置参数，通过此参数可以获得特定地图状态（中心点、级别）下的坐标值，不传则按当前地图状态换算

属性	类型	说明
`center` 可选	`Point`	指定地图的中心点
`zoom` 可选	`number`	指定地图的级别

返回值 Point

示例代码1

const point = map.overlayPixelToPoint(new BMap.Pixel(100, 200));

#panBy(
    x: number,
    y: number,
    options?: { callback?: () => void; noAnimation?: boolean },
): void

将地图在水平位置上移动x像素，垂直位置上移动y像素。如果指定的像素大于可视区域范围或者在配置中指定没有动画效果，则不执行滑动效果

参数类型说明

x number 水平方向移动的像素数，正值向右

y number 垂直方向移动的像素数，正值向下

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后的回调函数
`noAnimation` 可选	`boolean`	是否关闭动画

返回值 void

示例代码1

map.panBy(100, -50);

#panTo(
center: Point,
options?: object,
): void

将地图的中心点更改为给定的点，跳转到指定中心点进行渲染。如果该点在当前的地图视图中已经可见，则会以平滑动画的方式移动到中心点位置。可以通过配置强制移动过程不使用动画效果

参数类型说明

center Point 目标中心点坐标

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画完成后的回调函数
`duration` 可选	`number`	动画持续时间，单位ms
`noAnimation` 可选	`boolean`	是否禁用动画效果，默认值：false

返回值 void

示例代码1

map.panTo(new BMap.Point(116.404, 39.915));

示例代码2：禁用动画

map.panTo(new BMap.Point(116.404, 39.915), {
  noAnimation: true
});

示例代码3：设置动画持续时间

map.panTo(new BMap.Point(116.404, 39.915), {
  duration: 800
});

示例代码4：设置动画完成后的回调

map.panTo(new BMap.Point(116.404, 39.915), {
  callback: () => console.log('移动完成')
});

#pauseViewAnimation(viewAnimation: ViewAnimation): void

暂停视角动画

参数	类型	说明
`viewAnimation`	`ViewAnimation`	要暂停的视角动画实例

返回值 void

示例代码1

const viewAnimation = new BMap.ViewAnimation([
  { center: new BMap.Point(116.404, 39.915), zoom: 11, tilt: 0, heading: 0, percentage: 0 },
  { center: new BMap.Point(116.404, 39.915), zoom: 18, tilt: 60, heading: 180, percentage: 1 }
], { duration: 5000 });
map.startViewAnimation(viewAnimation);
// 2 秒后暂停
setTimeout(() => {
  map.pauseViewAnimation(viewAnimation);
}, 2000);

#pixelToPoint(
pixel: Pixel,
options?: object,
): Point

像素坐标转换为经纬度坐标

参数类型说明

pixel Pixel 地图像素坐标

options 可选

object

可选配置参数，通过此参数可以获得特定地图状态（中心点、级别、旋转、倾斜）下的坐标值，不传则按当前地图状态换算

属性	类型	说明
`center` 可选	`Point`	指定地图的中心点
`heading` 可选	`number`	指定地图的正北朝向
`tilt` 可选	`number`	指定地图的倾斜角度
`zoom` 可选	`number`	指定地图的级别

返回值 Point

示例代码1

const point = map.pixelToPoint(new BMap.Pixel(100, 200));

#pointToOverlayPixel(
point: Point,
options?: { center?: Point; zoom?: number },
): Pixel

根据地理坐标获取对应的覆盖物容器的坐标，此方法用于自定义覆盖物

参数类型说明

point Point 地理坐标点

options 可选

object

可选配置参数，通过此参数可以获得特定地图状态（中心点、级别）下的坐标值，不传则按当前地图状态换算

属性	类型	说明
`center` 可选	`Point`	指定地图的中心点
`zoom` 可选	`number`	指定地图的级别

返回值 Pixel

示例代码1

const pixel = map.pointToOverlayPixel(new BMap.Point(116.404, 39.915));

#pointToPixel(
point: Point,
options?: object,
): Pixel

经纬度坐标转换为像素坐标

参数类型说明

point Point 地理坐标点

options 可选

object

可选配置参数，通过此参数可以获得特定地图状态（中心点、级别、旋转、倾斜）下的坐标值，不传则按当前地图状态换算

属性	类型	说明
`center` 可选	`Point`	指定地图的中心点
`heading` 可选	`number`	指定地图的正北朝向
`tilt` 可选	`number`	指定地图的倾斜角度
`zoom` 可选	`number`	指定地图的级别

返回值 Pixel

示例代码1

const pixel = map.pointToPixel(new BMap.Point(116.404, 39.915));

#registerTheme(name: string, variables: Record<string, string>): void
注册自定义 UI 主题，注册后可通过 setTheme(name) 切换

参数类型说明
name string 主题名称
variables Record<string, string> 主题的 CSS 变量集合，支持的变量见 setTheme 的变量表
返回值 void
示例代码1
```
map.registerTheme('ocean', { '--bmap-color-primary': '#0080ff' });
map.setTheme('ocean');
```

参数	类型	说明
`name`	`string`	主题名称
`variables`	`Record<string, string>`	主题的 CSS 变量集合，支持的变量见 `setTheme` 的变量表

#removeContextMenu(menu: ContextMenu): void

移除右键菜单

参数	类型	说明
`menu`	`ContextMenu`	要移除的右键菜单实例

返回值 void

示例代码1

const contextMenu = new BMap.ContextMenu();
contextMenu.addItem(new BMap.MenuItem('放大', () => map.zoomIn()));
map.addContextMenu(contextMenu);
setTimeout(() => {
  map.removeContextMenu(contextMenu);
}, 2000);

#removeControl(control: Control): void
从地图中移除控件。如果控件从未被添加到地图中，则该移除不起任何作用

参数类型说明
control Control 要移除的控件实例
返回值 void
示例代码1
```
const navigationControl = new BMap.NavigationControl();
map.addControl(navigationControl);
setTimeout(() => {
  map.removeControl(navigationControl);
}, 2000);
```

参数	类型	说明
`control`	`Control`	要移除的控件实例

#removeEventListener<K extends keyof MapEventMap>(
event: K,
handler: (e: MapEventMap[K]) => void,
): void
移除事件监听，传入的 handler 须与 addEventListener 时一致

参数类型说明
event K 事件名称
handler (e: MapEventMap[K]) => void 要移除的事件处理函数
返回值 void
示例代码14
```
const onClick = (e: BMap.MapMouseEvent) => console.log(e.latlng);
map.addEventListener('click', onClick);
setTimeout(() => {
  map.removeEventListener('click', onClick);
}, 2000);
```

#removeLayer(
    layer:
        | TileLayer
        | RasterTileLayer
        | WMSLayer
        | WMTSLayer
        | GeoJSONLayer
        | DistrictLayer
        | DOMLayer
        | LineLayer
        | FillLayer
        | PointShapeLayer
        | PointIconLayer,
): void
统一移除图层方法，自动根据图层类型分发到对应处理逻辑

参数类型说明
layer | TileLayer | RasterTileLayer | WMSLayer | WMTSLayer | GeoJSONLayer | DistrictLayer | DOMLayer | LineLayer | FillLayer | PointShapeLayer | PointIconLayer 图层实例
返回值 void
示例代码1
```
map.removeLayer(lineLayer);
```

参数	类型	说明
`layer`	`\| TileLayer \| RasterTileLayer \| WMSLayer \| WMTSLayer \| GeoJSONLayer \| DistrictLayer \| DOMLayer \| LineLayer \| FillLayer \| PointShapeLayer \| PointIconLayer`	图层实例

#removeMapLabels(labelUids: string | string[]): void
从底图上移除文字标注，参数为uid数组，根据数组里的uid进行移除

参数类型说明
labelUids string | string[] 要移除的标注uid数组
返回值 void
示例代码1
```
map.removeMapLabels(['uid-001', 'uid-002']);
```

参数	类型	说明
`labelUids`	`string \| string[]`	要移除的标注uid数组

#removeOverlay(overlay: Overlay): void
从地图中移除覆盖物。如果覆盖物从未被添加到地图中，则该移除不起任何作用

参数类型说明
overlay Overlay 要移除的覆盖物实例
返回值 void
示例代码1
```
const marker = new BMap.Marker(new BMap.Point(116.404, 39.915));
map.addOverlay(marker);
setTimeout(() => {
  map.removeOverlay(marker);
}, 2000);
```

参数	类型	说明
`overlay`	`Overlay`	要移除的覆盖物实例

#removeTileLayer(tileLayer: TileLayer): void
移除一个自定义地图图层

参数类型说明
tileLayer TileLayer 要移除的自定义图层实例
返回值 void
已弃用
自 4.0 起
请使用 removeLayer

参数	类型	说明
`tileLayer`	`TileLayer`	要移除的自定义图层实例

#reset(): void
重新设置地图，恢复地图初始化时的中心点和级别

返回值 void

#resetHeading(options?: { callback?: () => void; noAnimation?: boolean }): void
将地图重置为正北方向，重置过程的动画不可被打断

参数类型说明
options 可选 object
可选配置参数
属性类型说明
callback 可选 void 动画结束后的回调函数
noAnimation 可选 boolean 是否关闭动画
返回值 void
示例代码1
```
map.resetHeading();
```

#restrictBounds(bounds: Bounds): void
限制地图显示范围

参数类型说明
bounds Bounds 地图可显示的地理范围
返回值 void
示例代码1
```
map.restrictBounds(new BMap.Bounds(
  new BMap.Point(115.7, 39.4),
  new BMap.Point(117.4, 41.2)
));
```

参数	类型	说明
`bounds`	`Bounds`	地图可显示的地理范围

#setBounds(bounds: Bounds): void
设置地图可拖动区域，参数为地图拖拽的区域范围

参数类型说明
bounds Bounds 允许拖动的地理范围
返回值 void
示例代码1
```
map.setBounds(new BMap.Bounds(
  new BMap.Point(115.7, 39.4),
  new BMap.Point(117.4, 41.2)
));
```

参数	类型	说明
`bounds`	`Bounds`	允许拖动的地理范围

#setCenter(
center: string | Point,
options?: { callback?: () => void; noAnimation?: boolean },
): void

设置地图中心点。center除了可以为坐标点以外，还支持城市名。

参数类型说明

center string | Point 地图中心点坐标或城市名称

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后调用此方法，如果没有动画则立即调用
`noAnimation` 可选	`boolean`	是否禁用动画效果，默认值：true

返回值 void

示例代码1

map.setCenter(new BMap.Point(116.404, 39.915));

示例代码2

map.setCenter(new BMap.Point(116.404, 39.915), {
  noAnimation: false,
  callback: () => console.log('移动完成')
});

#setCopyrightOffset(logo: object, cpy: object): void
设置版权信息位置，其中logo为logo位置，copyright为文字位置

参数类型说明
logo object logo 位置配置，包含 x、y 偏移量
cpy object 版权文字位置配置，包含 x、y 偏移量
返回值 void
示例代码1
```
map.setCopyrightOffset(
  { x: 10, y: 10 },
  { x: 10, y: 30 }
);
```

#setDefaultCursor(cursor: string): void
设置地图默认的鼠标指针样式。参数cursor应符合CSS的cursor属性规范

参数类型说明
cursor string CSS cursor 属性值，如 'pointer'、'crosshair'
返回值 void
示例代码1
```
map.setDefaultCursor('crosshair');
```

#setDisplayOptions(options: DisplayOptions): void

设置地图元素显示选项

参数类型说明

options

DisplayOptions

显示选项配置，可控制POI、路况、3D建筑等图层的显示状态

属性	类型	说明
`building`	`boolean`	是否显示3D建筑物（仅支持 WebGL 方式渲染的地图）
`indoor`	`boolean`	是否显示室内图（仅支持 WebGL 方式渲染的地图）
`isFlat`	`boolean`	是否将3D元素以平面形式展示
`labelMargin`	`number`	文字标注间距
`layer`	`boolean`	是否显示图层
`overlay`	`boolean`	是否显示覆盖物
`poi`	`boolean`	是否显示POI信息。注意：poi、poiText 与 poiIcon 均用来配置POI显示，当 poi 为 true 时，可配置另外两个选项；如果为 false，则另外两个选项不再生效。
`poiIcon`	`boolean`	是否显示POI的Icon
`poiText`	`boolean`	是否显示POI文字信息
`skyColors`	`string[]`	配置天空的颜色，数组中首个元素表示地面颜色，第二个元素表示天空颜色，从而形成渐变，支持只传入一个元素
`street`	`boolean`	是否显示路网（只对卫星图和地球模式有效）

返回值 void

示例代码1

map.setDisplayOptions({
  poiText: false,
  poiIcon: false
});

#setDraggingCursor(cursor: string): void
设置拖拽地图时的鼠标指针样式。参数cursor应符合CSS的cursor属性规范

参数类型说明
cursor string CSS cursor 属性值，如 'move'、'grab'
返回值 void
示例代码1
```
map.setDraggingCursor('grab');
```

#setHeading(
heading: number,
options?: { callback?: () => void; noAnimation?: boolean },
): void

设置地图旋转角度。传入任意角度值均可，内部会自动按一周（360 度）归一化，例如传入 450 等价于 90，传入 -90 等价于 270。

参数类型说明

heading number 旋转角度，单位为度。推荐使用 0~360 的罗盘角度（正北 0、正东 90、正南 180、正西 270），超出该范围会被自动归一化

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后的回调函数
`noAnimation` 可选	`boolean`	是否关闭动画

返回值 void

示例代码1

map.setHeading(45);

#setMapStyle(config: MapStyleConfig): void

设置个性化地图，参数为个性化配置对象，支持通过 styleId、styleJson 两种方式设置个性化地图样式。 styleId 和 styleJson 的获取地址：https://lbsyun.baidu.com/apiconsole/custommap。 styleId 必须由 AK 所属账号创建，否则将无权限获取样式。

参数	类型	说明
`config`	`MapStyleConfig`	个性化地图样式配置对象

返回值 void

示例代码1：使用 styleId

map.setMapStyle({ styleId: 'your-style-id' });

示例代码2：使用 styleId，并开启 merge 参数支持室内图

map.setMapStyle({ styleId: 'your-style-id', merge: true });

示例代码3：使用 styleJson 内联样式（通过个性化编辑器导出的 JSON）

map.setMapStyle({
  styleJson: [
    { featureType: 'land', elementType: 'geometry', stylers: { color: '#f5f4f4ff' } },
    { featureType: 'water', elementType: 'geometry', stylers: { color: '#86cee6ff' } },
    { featureType: 'green', elementType: 'geometry', stylers: { color: '#c1efc2ff' } },
    { featureType: 'road', elementType: 'geometry.fill', stylers: { color: '#a4bacfff' } },
    { featureType: 'local', elementType: 'geometry.fill', stylers: { color: '#d9e2f3ff' } },
    { featureType: 'fourlevelway', elementType: 'geometry.fill', stylers: { color: '#d9e2f3ff' } },
    { featureType: 'road', elementType: 'geometry.stroke', stylers: { color: '#e2e2e2ff' } }
  ]
});

#setMapType(mapType: MapType): void
设置地图类型

参数类型说明
mapType MapType 地图类型常量，如 BMAP_SATELLITE_MAP
返回值 void
示例代码1
```
map.setMapType(BMAP_SATELLITE_MAP);
```

#setMaxZoom(zoom: number): void
设置地图允许的最大级别。取值不得大于地图类型所允许的最大级别

参数类型说明
zoom number 最大缩放级别
返回值 void
示例代码1
```
map.setMaxZoom(18);
```

#setMinZoom(zoom: number): void
设置地图允许的最小级别。取值不得小于地图类型所允许的最小级别

参数类型说明
zoom number 最小缩放级别
返回值 void
示例代码1
```
map.setMinZoom(5);
```

#setTheme(theme: string, customVars?: Record<string, string>): void

设置地图 UI 主题。主题通过 CSS 变量控制 UI 控件、服务面板等的配色

支持的主题变量如下，变量名需与表中名称完全一致。未被 dark 主题覆盖的变量继续使用 light 的默认值。

变量	light 默认值	dark 默认值	用途
`--bmap-border-radius`	`6px`	同 light	基础圆角
`--bmap-border-radius-lg`	`16px`	同 light	大圆角
`--bmap-box-shadow`	`0 6px 16px 0 rgba(0, 0, 0, .08), 0 3px 6px -4px rgba(0, 0, 0, .12), 0 9px 28px 8px rgba(0, 0, 0, .05)`	`0 6px 16px 0 rgba(0,0,0,.45), 0 3px 6px -4px rgba(0,0,0,.55), 0 9px 28px 8px rgba(0,0,0,.35)`	通用浮层阴影
`--bmap-color-bg-base`	`#fff`	`#2b2d33`	基础背景色
`--bmap-color-bg-base-hover`	`rgba(0, 0, 0, .02)`	`rgba(255, 255, 255, .08)`	基础背景悬停色
`--bmap-color-bg-base-active`	`rgba(51, 136, 255, .06)`	`rgba(74, 144, 255, .18)`	基础背景激活色
`--bmap-color-primary`	`#1677ff`	`#5ba3ff`	主题主色
`--bmap-color-primary-bg`	`#eaf1ff`	`#1e2a40`	主色浅背景
`--bmap-color-primary-bg-hover`	`#dde8fc`	`#243450`	主色浅背景悬停色
`--bmap-color-text-base`	`#000`	`#e0e0e0`	基础文本色
`--bmap-color-text-weak`	`#5c6373`	`#b0b0c0`	弱化文本色
`--bmap-color-text-active`	`#1677ff`	`#5ba3ff`	激活文本色
`--bmap-color-text-secondary`	`#5a6070`	`#b0b0c0`	次要文本色
`--bmap-color-text-tertiary`	`#8a90a0`	`#9a9ab0`	三级文本色
`--bmap-color-border`	`#d9d9d9`	`#3a3d44`	基础边框色
`--bmap-color-border-secondary`	`#f0f0f0`	`#3a3d44`	次级边框和分割线颜色
`--bmap-color-fill`	`#f2f3f5`	`rgba(255, 255, 255, .08)`	通用次级填充色
`--bmap-font-size`	`14px`	同 light	基础字号
`--bmap-font-size-xs`	`12px`	同 light	小字号
`--bmap-font-size-lg`	`16px`	同 light	大字号
`--bmap-font-size-heading-1`	`38px`	同 light	一级标题字号
`--bmap-font-size-heading-2`	`30px`	同 light	二级标题字号
`--bmap-font-size-heading-3`	`24px`	同 light	三级标题字号
`--bmap-font-size-heading-4`	`20px`	同 light	四级标题字号
`--bmap-font-size-heading-5`	`16px`	同 light	五级标题字号
`--bmap-font-weight-bold`	`500`	同 light	基础强调字重
`--bmap-font-weight-bold-lg`	`700`	同 light	高强调字重
`--bmap-font-weight-lighter`	`400`	同 light	常规字重
`--bmap-line-height`	`1.2`	同 light	基础行高
`--bmap-line-width`	`1px`	同 light	基础线宽
`--bmap-line-type`	`solid`	同 light	基础线型
`--bmap-margin`	`16px`	同 light	基础外边距
`--bmap-margin-lg`	`24px`	同 light	大外边距
`--bmap-margin-xs`	`8px`	同 light	小外边距
`--bmap-margin-xxs`	`4px`	同 light	超小外边距
`--bmap-padding`	`16px`	同 light	基础内边距
`--bmap-padding-lg`	`24px`	同 light	大内边距
`--bmap-padding-xs`	`8px`	同 light	小内边距
`--bmap-padding-xxs`	`4px`	同 light	超小内边距

参数	类型	说明
`theme`	`string`	主题名称，内置 'light' 和 'dark'
`customVars` 可选	`Record<string, string>`	可选的 CSS 变量覆盖对象，未指定的变量回退到主题默认值

返回值 void

示例代码1

map.setTheme('dark');

示例代码2

map.setTheme('dark', { '--bmap-color-primary': '#00d2ff' });

#setTilt(
tilt: number,
options?: { callback?: () => void; noAnimation?: boolean },
): void

设置地图的倾斜角度

参数类型说明

tilt number 倾斜角度，单位为度，取值范围 0~73

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后的回调函数
`noAnimation` 可选	`boolean`	是否关闭动画

返回值 void

示例代码1

map.setTilt(45);

#setViewport(
view: Point[] | { getBounds(): Bounds }[] | Viewport,
viewportOptions?: ViewportOptions,
): void

根据提供的地理区域或坐标设置地图视野，调整后的视野会保证包含提供的地理区域或坐标，除坐标数组与视野对象外，还支持传入带 getBounds 方法的覆盖物数组

参数类型说明

view Point[] | { getBounds(): Bounds }[] | Viewport 地理坐标数组或视野对象

viewportOptions 可选

ViewportOptions

视野调整选项

属性	类型	说明
`callback`	`Function`	视野调整结束后的回调函数
`enableAnimation`	`boolean`	是否启用动画效果移动地图，当调整后的级别与当前地图级别一致时，将使用动画效果移动地图
`margins`	`number[]`	视野调整的预留边距，依次为上、右、下、左，例如： margins: [30, 20, 0, 20] 表示坐标点会限制在上述区域内
`zoomFactor`	`number`	地图级别的偏移量，您可以在方法得出的结果上增加一个偏移值。例如map.setViewport计算出地图的级别为10，如果zoomFactor为-1，则最终的地图级别为9

返回值 void

示例代码1

map.setViewport([
  new BMap.Point(116.404, 39.915),
  new BMap.Point(117.200, 39.084)
]);

示例代码2

map.setViewport(
  [
    new BMap.Point(116.404, 39.915),
    new BMap.Point(117.200, 39.084)
  ],
  {
    margins: [50, 50, 50, 50],
    zoomFactor: -1
  }
);

#setZoom(
zoom: number,
options?: object,
): void

将视图切换到指定的缩放等级，中心点坐标不变。注意：当有信息窗口在地图上打开时，地图缩放将保证信息窗口所在的坐标位置不动。

参数类型说明

zoom number 目标缩放级别

options 可选

object

可选配置参数

属性	类型	说明
`callback` 可选	`void`	动画结束后会调用此方法，如果没有动画则立即调用
`noAnimation` 可选	`boolean`	是否禁用动画效果
`zoomCenter` 可选	`Point`	缩放中心点，默认值：地图中心点

返回值 void

示例代码1

map.setZoom(15);

示例代码2

map.setZoom(15, {
  zoomCenter: new BMap.Point(116.404, 39.915),
  callback: () => console.log('缩放完成')
});

#showOverlayContainer(): void
显示覆盖物

返回值 void

#startViewAnimation(viewAnimation: ViewAnimation): void

启动视角动画

参数	类型	说明
`viewAnimation`	`ViewAnimation`	视角动画实例

返回值 void

示例代码1

const keyFrames = [
  {
    center: new BMap.Point(116.404, 39.915),
    zoom: 11, tilt: 0, heading: 0, percentage: 0
  },
  {
    center: new BMap.Point(116.404, 39.915),
    zoom: 18, tilt: 60, heading: 180, percentage: 1
  }
];
const viewAnimation = new BMap.ViewAnimation(keyFrames, {
  duration: 5000
});
map.startViewAnimation(viewAnimation);

#zoomIn(zoomCenter?: Point): void
放大一级视图

参数类型说明
zoomCenter 可选 Point 放大的中心点，默认为地图中心点
返回值 void

#zoomOut(zoomCenter?: Point): void
缩小一级视图

参数类型说明
zoomCenter 可选 Point 缩小的中心点，默认为地图中心点
返回值 void

参数	类型	说明
`logo`	`object`	logo 位置配置，包含 x、y 偏移量
`cpy`	`object`	版权文字位置配置，包含 x、y 偏移量