跳到主要内容
版本:4.x

Map

地图。相关api Taro.createMapContext。

支持情况:

参考文档

类型

ComponentType<MapProps>

示例代码

class App extends Component {
onTap () {}
render () {
return (
<Map onClick={this.onTap} />
)
}
}

MapProps

参数类型默认值必填说明
longitudenumber中心经度
latitudenumber中心纬度
scalenumber16缩放级别,取值范围为 3-20
minScalenumber3最小缩放级别 3-20
maxScalenumber20最大缩放级别 3-20
markersmarker[]标记点
coversany[]即将移除,请使用 markers
不推荐使用
polylinepolyline[]路线
circlescircle[]
controlscontrol[]控件(即将废弃,建议使用 cover-view 代替)
不推荐使用
includePointspoint[]缩放视野以包含所有给定的坐标点
showLocationbooleanfalse显示带有方向的当前定位点
polygonspolygon[]多边形
subkeystring个性化地图使用的 key
layerStylenumber1个性化地图配置的 style,不支持动态修改
rotatenumber0旋转角度,范围 0 ~ 360, 地图正北和设备 y 轴角度的夹角
skewnumber0倾斜角度,范围 0 ~ 40 , 关于 z 轴的倾角
showCompassbooleanfalse显示指南针
showScalebooleanfalse显示比例尺
enableOverlookingbooleanfalse开启俯视
enableZoombooleantrue是否支持缩放
enableScrollbooleantrue是否支持拖动
enableRotatebooleanfalse是否支持旋转
enableSatellitebooleanfalse是否开启卫星图
enableTrafficbooleanfalse是否开启实时路况
settingMapProps or { [key: string]: any; }配置项

提供 setting 对象统一设置地图配置。同时对于一些动画属性如 rotate 和 skew,通过 setData 分开设置时无法同时生效,需通过 settting 统一修改。
includePadding{ left: string or number; right: string or number; top: string or number; bottom: string or number; }视野在地图 padding 范围内展示
groundOverlaysgroundOverlays[]覆盖物,自定义贴图
tileOverlaytileOverlay覆盖物,网格贴图
enablePoibooleantrue是否展示 POI 点
enableBuildingbooleantrue是否展示建筑物
polygonpolygon[]覆盖物,多边形。
customMapStylestring设置地图样式。

default:默认样式
light:精简样式
panelspanels[]基于 map 高级定制渲染,设置覆盖在地图上的 view。
themestring
optimizebooleanfalse保持缩放比例不变
enableAutoMaxOverlookingbooleanfalse开启最大俯视角,俯视角度从 45 度拓展到 75 度
enable3Dbooleanfalse展示3D楼块
onTapCommonEventFunction点击地图时触发
onMarkerTapCommonEventFunction<onMarkerTapEventDetail>点击标记点时触发,e.detail = {markerId}
onLabelTapCommonEventFunction<onLabelTapEventDetail>点击label时触发,e.detail = {markerId}
onControlTapCommonEventFunction<onControlTapEventDetail>点击控件时触发,e.detail = {controlId}
onCalloutTapCommonEventFunction<onCalloutTapEventDetail>点击标记点对应的气泡时触发,e.detail = {markerId}
onUpdatedCommonEventFunction在地图渲染更新完成时触发
onRegionChangeCommonEventFunction<onRegionEventDetail<"begin"> or onRegionEventDetail<"end">>视野发生变化时触发
onPoiTapCommonEventFunction<onPoiTapEventDetail>点击地图poi点时触发,e.detail = {name, longitude, latitude}
onPolylineTapCommonEventFunction<onPolylineTapEventDetail>点击地图路线时触发,e.detail = {longitude, latitude}
onAbilitySuccessCommonEventFunction<onAbilityEventDetail>地图能力生效时触发,e.detail = {ability, errCode, errMsg}
onAbilityFailedCommonEventFunction<onAbilityEventDetail>地图能力失败时触发,e.detail = {ability, errCode, errMsg}
onAuthSuccessCommonEventFunction<{ errCode: number; errMsg: string; }>地图鉴权结果成功时触发,e.detail = {errCode, errMsg}
onInterpolatePointCommonEventFunction<onInterpolatePointEventDetail>MapContext.moveAlong 插值动画时触发。e.detail = {markerId, longitude, latitude, animationStatus: "interpolating" or "complete"}
onErrorCommonEventFunction<point>组件错误时触发,例如创建或鉴权失败,e.detail = {longitude, latitude}
onCallOutTapCommonEventFunction<onCalloutTapEventDetail>点击标记点对应的气泡时触发e.detail = {markerId}
onAnchorPointTapCommonEventFunction<point>点击定位标时触发,e.detail = {longitude, latitude}
onPanelTapCommonEventFunction<{ panelId: any; layoutId: any; }>点击 panel 时触发。
onInitCompleteCommonEventFunction地图初始化完成即将开始渲染第一帧时触发。

API 支持度

API微信小程序百度小程序支付宝小程序抖音小程序QQ 小程序京东小程序H5React NativeHarmony
MapProps.longitude✔️✔️✔️✔️✔️✔️
MapProps.latitude✔️✔️✔️✔️✔️✔️
MapProps.scale✔️✔️(取值范围为4-21)✔️(取值范围为5-18)✔️✔️✔️
MapProps.minScale✔️✔️
MapProps.maxScale✔️✔️
MapProps.markers✔️✔️✔️✔️✔️✔️
MapProps.covers✔️
MapProps.polyline✔️✔️✔️✔️✔️✔️
MapProps.circles✔️✔️✔️✔️✔️✔️
MapProps.controls✔️✔️✔️✔️
MapProps.includePoints✔️✔️✔️✔️✔️✔️
MapProps.showLocation✔️✔️✔️✔️✔️✔️
MapProps.polygons✔️✔️✔️✔️
MapProps.subkey✔️✔️
MapProps.layerStyle✔️✔️
MapProps.rotate✔️✔️✔️✔️
MapProps.skew✔️✔️✔️✔️
MapProps.showCompass✔️✔️✔️✔️✔️
MapProps.showScale✔️✔️✔️✔️
MapProps.enableOverlooking✔️✔️✔️✔️✔️
MapProps.enableZoom✔️✔️✔️✔️✔️
MapProps.enableScroll✔️✔️✔️✔️✔️
MapProps.enableRotate✔️✔️✔️✔️✔️
MapProps.enableSatellite✔️✔️✔️✔️
MapProps.enableTraffic✔️✔️✔️✔️
MapProps.setting✔️✔️✔️
MapProps.includePadding✔️
MapProps.groundOverlays✔️
MapProps.tileOverlay✔️
MapProps.enablePoi✔️✔️✔️
MapProps.enableBuilding✔️✔️✔️
MapProps.polygon✔️
MapProps.customMapStyle✔️
MapProps.panels✔️
MapProps.theme✔️
MapProps.optimize✔️
MapProps.enableAutoMaxOverlooking✔️
MapProps.enable3D✔️✔️✔️✔️
MapProps.onTap✔️✔️✔️✔️✔️✔️
MapProps.onMarkerTap✔️✔️✔️✔️✔️✔️
MapProps.onLabelTap✔️✔️
MapProps.onControlTap✔️✔️✔️✔️
MapProps.onCalloutTap✔️
MapProps.onUpdated✔️✔️✔️✔️
MapProps.onRegionChange✔️✔️✔️✔️✔️✔️
MapProps.onPoiTap✔️✔️✔️
MapProps.onPolylineTap✔️✔️✔️
MapProps.onAbilitySuccess✔️
MapProps.onAbilityFailed✔️
MapProps.onAuthSuccess✔️
MapProps.onInterpolatePoint✔️
MapProps.onError✔️
MapProps.onCallOutTap✔️✔️✔️✔️
MapProps.onAnchorPointTap✔️✔️
MapProps.onPanelTap✔️
MapProps.onInitComplete✔️

marker

标记点用于在地图上显示标记的位置

参数类型必填说明备注
idnumber标记点idmarker 点击事件回调会返回此id。建议为每个 marker 设置上 Number 类型 id,保证更新 marker 时有更好的性能。
latitudenumber纬度浮点数,范围 -90 ~ 90
longitudenumber经度浮点数,范围 -180 ~ 180
titlestring标注点名点击时显示,callout 存在时将被忽略
zIndexnumber显示层级
iconPathstring显示的图标项目目录下的图片路径,支持相对路径写法,以'/'开头则表示相对小程序根目录;也支持临时路径和网络图片
rotatenumber旋转角度顺时针旋转的角度,范围 0 ~ 360,默认为 0
alphanumber标注的透明度默认1,无透明,范围 0 ~ 1
widthstring or number标注图标宽度默认为图片实际宽度
heightstring or number标注图标高度默认为图片实际高度
calloutcallout标记点上方的气泡窗口支持的属性见下表,可识别换行符。
customCalloutcustomCallout自定义气泡窗口支持的属性见下表,可识别换行符。
labellabel为标记点旁边增加标签支持的属性见下表
anchor{ x: number; y: number; }经纬度在标注图标的锚点,默认底边中点{x, y},x表示横向(0-1),y表示竖向(0-1)。{x: .5, y: 1} 表示底边中点
ariaLabelstring无障碍访问,(属性)元素的额外描述

callout

marker 上的气泡 callout

参数类型说明
contentstring文本
colorstring文本颜色
fontSizenumber文字大小
anchorXnumber横向偏移量,向右为正数
anchorYnumber纵向偏移量,向下为正数
borderRadiusnumber边框圆角
borderWidthnumber边框宽度
borderColorstring边框颜色
bgColorstring背景色
paddingnumber文本边缘留白
display"BYCLICK" or "ALWAYS"'BYCLICK':点击显示; 'ALWAYS':常显
textAlign"left" or "right" or "center"文本对齐方式。有效值: left, right, center

customCallout

marker 上的自定义气泡 customCallout

customCallout 存在时将忽略 callouttitle 属性。自定义气泡采用采用 cover-view 定制,灵活度更高。

参数类型说明
displaystring'BYCLICK':点击显示; 'ALWAYS':常显
anchorXnumber横向偏移量,向右为正数
anchorYnumber纵向偏移量,向下为正数

label

marker 上的气泡 label

参数类型说明
contentstring文本
colorstring文本颜色
fontSizenumber文字大小
anchorXnumberlabel的坐标,原点是 marker 对应的经纬度
anchorYnumberlabel的坐标,原点是 marker 对应的经纬度
borderWidthnumber边框宽度
borderColorstring边框颜色
borderRadiusnumber边框圆角
bgColorstring背景色
paddingnumber文本边缘留白
textAlign"left" or "right" or "center"文本对齐方式。有效值: left, right, center

polyline

指定一系列坐标点,从数组第一项连线至最后一项

参数类型必填说明备注
pointspoint[]经纬度数组[{latitude: 0, longitude: 0}]
colorstring线的颜色十六进制
widthnumber线的宽度
dottedLineboolean是否虚线默认 false
arrowLineboolean带箭头的线默认 false,开发者工具暂不支持该属性
arrowIconPathstring更换箭头图标在 arrowLine 为 true 时生效
borderColorstring线的边框颜色
borderWidthnumber线的厚度

polygon

指定一系列坐标点,根据 points 坐标数据生成闭合多边形

参数类型默认值必填说明备注
dashArraynumber[][0,0]边线虚线默认值 [0, 0] 为实线,[10, 10]表示十个像素的实线和十个像素的空白(如此反复)组成的虚线
pointspoint[]经纬度数组[{latitude: 0, longitude: 0}]
colorstring线的颜色,用 8 位十六进制表示,后两位表示 alpha 值,如:#eeeeeeAA。当前 Android 与 iOS 上此属性默认值存在差异(分别为 transparent 与 #ff0000ff ),建议在代码中统一显式设置。
strokeWidthnumber描边的宽度
strokeColorstring描边的颜色十六进制
fillColorstring填充颜色十六进制
widthnumber线的宽度当前 Android 与 iOS 上此属性默认值存在差异(分别为 0 与 5),建议在代码中统一显式设置。
zIndexnumber设置多边形Z轴数值
levelstring压盖关系默认为 abovelabels
displayRanges[{ from: number; to: number; }]标明在特定地图缩放级别下展示。[{ from: 12, to: 17}]

API 支持度

API微信小程序支付宝小程序H5React NativeHarmony
polygon.dashArray✔️
polygon.color✔️
polygon.width✔️
polygon.level✔️
polygon.displayRanges✔️

circle

在地图上显示圆

参数类型必填说明备注
latitudenumber纬度浮点数,范围 -90 ~ 90
longitudenumber经度浮点数,范围 -180 ~ 180
colorstring描边的颜色十六进制
fillColorstring填充颜色十六进制
radiusnumber半径
strokeWidthnumber描边的宽度

control

在地图上显示控件,控件不随着地图移动。即将废弃,请使用 cover-view

参数类型必填说明备注
idnumber控件id在控件点击事件回调会返回此id
positionposition控件在地图的位置控件相对地图位置
iconPathstring显示的图标项目目录下的图片路径,支持本地路径、代码包路径
clickableboolean是否可点击默认不可点击

point

参数类型说明
longitudenumber经度
latitudenumber纬度

position

参数类型默认值说明
leftnumber0距离地图的左边界多远
topnumber0距离地图的上边界多远
widthnumber图片宽度控件宽度
heightnumber图片宽度控件高度

groundOverlays

参数类型说明
idstring刷新的时候需要变更id值
include-points[{ latitude: number; longitude: number; }, { latitude: number; longitude: number; }]右上 左下
imagestring
alphanumber
zIndexnumber

tileOverlay

参数类型
urlstring
typenumber
tileWidthnumber
tileHeightnumber
zIndexnumber

panels

参数类型
idnumber
layout{ src: string; }
positionposition

onMarkerTapEventDetail

参数类型
markerIdstring or number

onLabelTapEventDetail

参数类型
markerIdstring or number

onControlTapEventDetail

参数类型
controlIdstring or number

onCalloutTapEventDetail

参数类型
markerIdstring or number

RegionChangeDetail

type

CausedByBegin

参数说明
gesture手势触发
update接口触发

CausedByEnd

参数说明
drag拖动导致
scale缩放导致
update调用更新接口导致

onRegionEventDetail

参数类型说明备注
typeT视野变化开始、结束时触发视野变化开始为begin,结束为end
causedBykeyof (T extends "begin" ? CausedByBegin : CausedByEnd)导致视野变化的原因有效值为 gesture(手势触发)、update(接口触发或调用更新接口导致)、drag(拖动导致)、scale(缩放导致)
detailregionChangeDetail<type>视野改变详情

regionChangeDetail

参数类型说明
rotatenumber旋转角度
skewnumber倾斜角度
causedBykeyof (T extends "begin" ? CausedByBegin : CausedByEnd)
typestring or T
scalenumber
centerLocationpoint
region{ northeast: point; southeast: point; }

onPoiTapEventDetail

参数类型
namestring
longitudenumber
latitudenumber

onPolylineTapEventDetail

参数类型
polylineIdnumber
longitudenumber
latitudenumber

onAbilityEventDetail

参数类型
abilitystring
errCodenumber
errMsgstring

onInterpolatePointEventDetail

参数类型
markerIdnumber
longitudenumber
latitudenumber
animationStatus"interpolating" or "complete"