map

花匠小妙招
2025-07-11 22:17

map component.

The map component is used to display the map, while the positioning API only obtains the coordinates, please do not confuse the two.

Platform Difference Description

App H5 微信小程序支付宝小程序百度小程序抖音小程序、飞书小程序 QQ小程序快应用 360小程序快手小程序京东小程序 √ √ √ √ √ 1.63+ 1.9.0+ √ x √ √

Instructions for Map Service Provider

Map Service Provider App H5 WeChat MiniApp 高德 √ 3.6.0+ Google 3.4+ 仅nvue页面 3.2.10+ Tencent √ √

Attribute Description

Property Name Type Default Value Description Platform Difference Description longitude Number central longitude latitude Number central latitude scale Number 16 Zoom level, the value range is 3-20 The zoom ratio of Gaode map is different from that of WeChat MiniApp theme String normal The theme (satellite or normal) is only valid during initialization and cannot be changed dynamically (only supported by Android) Jingdong MiniApp min-scale Number 3 Minimum zoom level App-nvue 3.1.0+, WeChat MiniApp 2.13+ max-scale Number 20 Maximum zoom level App-nvue 3.1.0+, WeChat MiniApp 2.13+ layer-style Number/String 1 Personalized map App-nvue 3.1.0+, WeChat MiniApp 2.13+ markers Array marker points polyline Array Route Feishu MiniApp does not support circles Array circles controls Array Controls include-points Array Zoom view to include all given coordinate points App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Alipay MiniApp, Jingdong MiniApp enable-3D Boolean false Whether to display 3D blocks App-nvue 2.1.5+, WeChat MiniApp 2.3.0 show-compass Boolean false Whether to display the compass App-nvue 2.1.5+, WeChat MiniApp 2.3.0 enable-zoom Boolean true Support zooming App-nvue 2.1.5+, Wechat MiniApp 2.3.0 enable-scroll Boolean true Whether to support dragging App-nvue 2.1.5+, WeChat MiniApp 2.3.0 enable-rotate Boolean false 是否支持旋转 App-nvue 2.1.5+、微信小程序2.3.0 rotate Number 0 旋转角度(范围0-360)地图正北和设备 y 轴角度的夹角微信小程序2.5.0、支付宝小程序、抖音小程序、QQ小程序 skew Number 0 倾斜角度，范围 0 ~ 40 , 关于 z 轴的倾角微信小程序2.5.0、支付宝小程序、抖音小程序、QQ小程序 enable-overlooking Boolean false Whether to enable overlooking App-nvue 2.1.5+, WeChat MiniApp 2.3.0 enable-satellite Boolean false Whether to enable satellite images App-nvue 2.1.5+, WeChat MiniApp 2.7.0 enable-traffic Boolean false Whether to enable real-time traffic conditions App-nvue 2.1.5+, WeChat MiniApp 2.7.0 enable-poi Boolean false Whether to display POI points App-nvue 3.1.0+ enable-building Boolean false Whether to display buildings App-nvue 3.1.0+ support (repeal the original enable-3D attribute, the building is enabled by default on Gaode map, and 3D cannot be set) show-location Boolean 显示带有方向的当前定位点微信小程序、H5、百度小程序、支付宝小程序、京东小程序 polygons（支付宝为: polygon） Array.<polygon> 多边形 App-nvue 2.1.5+、App-vue 3.4.3+、H5 3.4.3+、微信小程序、百度小程序、支付宝小程序 enable-indoorMap Boolean false Whether to display indoor map App-nvue 3.1.0+ @markertap EventHandle triggered when a marker is clicked, MiniApp = { MiniApp } @labeltap EventHandle triggered when the label is clicked, e.detail = {markerId} WeChat MiniApp 2.9.0 @callouttap EventHandle triggered when the bubble corresponding to the marker point is clicked, e.detail = {markerId} @controltap EventHandle triggered when the control is clicked, e.detail = {controlId} @regionchange EventHandle Triggered when the field of view changes WeChat MiniApp, H5, Baidu MiniApp, Alipay MiniApp, Jingdong MiniApp @tap EventHandle triggered when the map is clicked; App-nvue, WeChat MiniApp 2.9 supports returning latitude and longitude @updated EventHandle triggered when the map rendering update is completed WeChat MiniApp, H5, Baidu MiniApp @anchorpointtap EventHandle triggered when the anchor point is clicked, e.detail = {longitude, latitude} App-nvue 3.1.0+, WeChat MiniApp 2.13+ @poitap EventHandle triggered when a poi point on the map is clicked, e.detail = {name, longitude, latitude} WeChat MiniApp 2.3.0+

Notice

The width/height of the <map> component is recommended to be written directly, for example: 750rpx, do not set a percentage value. 谷歌地图使用 wgs84 坐标，其他地图使用 gcj02 坐标，用错坐标类型会显示偏移。 App平台 layer-style 属性需要在地图服务商后台创建，值设置为高德后台申请的字符串，详情。 H5 端高德地图 include-points 属性仅支持 2 个坐标点，表示显示范围的西南角和东北角。

# Recently Added Features

Support point aggregation, suitable for scenarios with too many markers. Support rainbow worm line, which is often used in route planning scenarios. Overlay supports adjusting the overlay relationship with other map elements. Support marker (car) translation animation, suitable for track playback scenarios.

markers

Marker points are used to show the marker's location on the map

Properties Description Type Required Remarks Platform Difference Description id marker id Number yes This id will be returned by marker click event callback. It is recommended to set a Number type id for each marker to ensure better performance when updating markers. The maximum limit is 9 digits latitude latitude Number yes floating point number, range -90 ~ 90 longitude longitude Number yes floating point number, range -180 ~ 180 title mark roll call String no display when clicked, and will be ignored when callout exists App-nvue 2.1.5+, WeChat MiniApp, H5, Alipay MiniApp, Baidu MiniApp, Jingdong MiniApp iconPath The displayed icon String Yes the image path in the project directory, which supports relative path writing, starting with '/' means relative to the root directory of the MiniApp; it also supports temporary paths rotate rotation angle Number No clockwise rotation angle, range 0 ~ 360, default is 0 App-nvue 2.1.5+, WeChat MiniApp, Alipay MiniApp, Baidu MiniApp, Jingdong MiniApp alpha Transparency of annotation Number No Default 1, no transparency, range 0 ~ 1 App-nvue 2.1.5+, WeChat MiniApp, Alipay MiniApp, Baidu MiniApp, Jingdong MiniApp width mark icon width Number No The MiniApp is the actual width of the picture height mark icon height Number No The default is the actual height of the picture App-nvue 2.1.5+, WeChat MiniApp, H5, Alipay MiniApp, Baidu MiniApp, Jingdong MiniApp callout Customize the bubble window above the marker Object No The supported properties are shown in the table below, and it can recognize line breaks. App-nvue 2.1.5+, WeChat MiniApp, Alipay MiniApp, Baidu MiniApp, Jingdong MiniApp label Add a label next to the mark point Object No The supported attributes are shown in the table below, and newline characters can be recognized. App-nvue 2.1.5+, WeChat MiniApp, H5, App, Baidu MiniApp, Alipay MiniApp anchor The latitude and longitude is the anchor point of the label icon, the default is the midpoint of the bottom Object No {x, y}, x means horizontal (0-1), y means vertical (0-1). {x: .5, y: 1} represents the midpoint of the bottom App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, JD MiniApp clusterId Use when customizing point aggregation cluster effects Number No App-nvue 3.1.0+, WeChat MiniApp customCallout Custom bubble window Object No App-nvue 2.1.5+, WeChat MiniApp, Alipay MiniApp aria-label Accessibility, additional description of (attribute) element String No App-nvue 3.1.0+, WeChat MiniApp joinCluster Whether to participate in point aggregation Boolean No If you specify point aggregation, this option value must be set to true to take effect App-nvue 3.1.0+, WeChat MiniApp

bubble callout on marker

Properties Description Type Platform Difference Description content Text String App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp, Alipay MiniApp color text color String App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp fontSize Text Size Number App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp borderRadius callout border fillet Number App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp borderWidth Border Width Number WeChat MiniApp, JD MiniApp, Baidu MiniApp borderColor border color String WeChat MiniApp, JD MiniApp, Baidu MiniApp bgColor Background color String App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp padding Leave blank at the edge of the text Number App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp display 'BYCLICK': Click to display; 'ALWAYS': Always display String App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp textAlign Text alignment. Valid values: left, right, center String App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Jingdong MiniApp anchorX horizontal offset, positive number to the right Number WeChat MiniApp 2.11.0 anchorY vertical offset, positive number downwards Number WeChat MiniApp 2.11.0

label on marker

Properties Description Type Platform Difference Description content text String color text color String App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Alipay MiniApp fontSize Text Size Number App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Alipay MiniApp x The coordinates of the label, the origin is the latitude and longitude corresponding to the marker Number H5, Baidu MiniApp y The coordinates of the label, the origin is the latitude and longitude corresponding to the marker Number H5, Baidu MiniApp anchorX the coordinates of the label, the origin is the latitude and longitude corresponding to the marker Number App-nvue 2.1.5+, WeChat MiniApp anchorY the coordinates of the label, the origin is the latitude and longitude corresponding to the marker Number App-nvue 2.1.5+, WeChat MiniApp borderWidth Border Width Number WeChat MiniApp, Baidu MiniApp borderColor border color String WeChat MiniApp, Baidu MiniApp borderRadius Border rounded corners Number App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Alipay MiniApp bgColor Background color String App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Alipay MiniApp padding Leave blank at the edge of the text Number App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Alipay MiniApp textAlign Text alignment. Valid values: left, right, center String App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp aria-label Accessibility, additional description of (attribute) element String App-nvue 3.1.0+, WeChat MiniApp

# point aggregation

When there are too many markers to be displayed on the map, the markers on the interface may be overlaid, incompletely displayed, and lead to poor overall performance. In response to such problems, the point aggregation capability is introduced.

The usage process is as follows:

MapContext.initMarkerCluster Initialize the configuration of the aggregation point (optional); MapContext.addMarkers specifies the markers involved in aggregation; When MapContext.on('markerClusterCreate', callback) is triggered, update the style of the cluster via MapContext.addMarkers (optional); MapContext.removeMarkers removes the markers participating in the aggregation;

polyline

Specify a series of coordinate points, connecting the line from the first item to the last item in the array

Properties Description Type Required Remarks Platform Difference Description points array of latitude and longitude Array Yes [{latitude: 0, longitude: 0}] color The color of the line String No 8-digit hexadecimal representation, the last two digits represent the alpha value, such as: #0000AA width line width Number No dottedLine Dotted Line Boolean No Default false App-nvue 2.1.5+, WeChat MiniApp, H5, Baidu MiniApp, Alipay MiniApp, Jingdong MiniApp arrowLine Arrowed line Boolean No The default is false, the WeChat MiniApp Developer Tool does not support this attribute App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Jingdong MiniApp arrowIconPath Change arrow icon String No Take effect when arrowLine is true App-nvue 2.1.5+, WeChat MiniApp, Baidu MiniApp, Jingdong MiniApp borderColor The border color of the line String No WeChat MiniApp, H5, Baidu MiniApp, Jingdong MiniApp borderWidth 线的厚度 Number 否微信小程序、H5、百度小程序、京东小程序 colorList 彩虹线 Array 否存在时忽略 color 值 App-nvue 3.1.0+、微信小程序 level 压盖关系
abovelabels 显示在所有 POI 之上（默认）
abovebuildings 显示在楼块之上 POI 之下
aboveroads 显示在所有 POI 之上 String 否微信小程序

Precautions

App-nvue When arrowLine is true, the line color value of the spliced image with arrow will be ignored, and the method of replacing the arrow image [reference document](https://ask.dcloud.net.cn/article/ 37901)

polygon
Specify a series of coordinate points and generate a closed polygon according to the points coordinate data

Attribute Description Type Required Remarks points array of latitude and longitude array yes [{latitude: 0, longitude: 0}] strokeWidth Stroke width Number No strokeColor stroke color String no hexadecimal fillColor fill color String no hex zIndex 设置多边形 Z 轴数值 Number 否 level 压盖关系
abovelabels 显示在所有 POI 之上（默认）
abovebuildings 显示在楼块之上 POI 之下
aboveroads 显示在所有 POI 之上 String false 微信小程序

circles

show circle on map

Attribute Description Type Required Remarks latitude latitude Number Yes a floating-point number, ranging from -90 to 90 longitude longitude Number yes floating point number, range -180 ~ 180 color Stroke color String No 8-digit hexadecimal representation, the last two digits represent the alpha value, such as: #000000AA; #00000 is hexadecimal fillColor Fill color String No 8-digit hexadecimal representation, the last two digits represent the alpha value, such as: #000000AA; #00000 is hexadecimal radius Radius Number Yes strokeWidth 描边的宽度 Number 否 level 压盖关系
abovelabels 显示在所有 POI 之上（默认）
abovebuildings 显示在楼块之上 POI 之下
aboveroads 显示在所有 POI 之上 String false 微信小程序

controls

Display the control on the map, the control does not move with the map

Attribute Description Type Required Remarks id Control id Number No This id will be returned in the control click event callback position the position of the control on the map Object Yes the position of the control relative to the map iconPath The displayed icon String Yes the image path in the project directory, which supports relative path writing, starting with '/' means relative to the root directory of the project; also supports temporary paths clickable Clickable or not Boolean No Not clickable by default

position

Attribute Description Type Required Remarks left How far from the left border of the map Number No Default is 0 top how far from the upper boundary of the map Number no default is 0 width Control Width Number No The default is the image width height Control height Number No The default is the picture height

The latitude and longitude of the map component are required. If the latitude and longitude are not filled, the default value is the latitude and longitude of Beijing.

Example View Example

# App平台地图服务商差异

# Map 地图组件 Properties Description Whether AutoNavi supports Whether Google Maps supports subkey The key used by the personalized map Not supported Not supported show-scale show scale supported not supported enable-poi Whether to display POI points Supported Not supported labeltap Triggered when the label is clicked Supported Android supported, iOS not supported poitap Triggered when a poi point on the map is clicked Supported Android does not support iOS support # marker Properties Description Whether AutoNavi supports Whether Google Maps supports label Add a label next to the marker point Supported Supported by Android Not supported by iOS # marker 上的气泡 callout Properties Description Whether AutoNavi supports Whether Google Maps supports display 'BYCLICK': Click to display; 'ALWAYS':Always display Supported Android supports iOS only supports 'BYCLICK' # marker 上的自定义气泡 customCallout Properties Description Whether AutoNavi supports Whether Google Maps supports display 'BYCLICK': Click to display; 'ALWAYS': Always display Supported Android supports iOS only supports 'BYCLICK' # polyline Properties Description Whether AutoNavi supports Whether Google Maps supports colorList Rainbow Line Supported Android Not Supported iOS Supported dottedLine Dotted line or not Supported Android supported, iOS not supported arrowLine Arrowed Line Supported Android Not Supported iOS Supported arrowIconPath Replace the arrow icon Supported Android does not support iOS support

map 组件相关操作的 JS API：uni.createMapContext

Nvue map replacement arrow icon format reference: https://ask.dcloud.net.cn/article/37901

Precautions

-In MiniApp and app-vue, the <map> component is a native component created by the engine. It has the highest level and cannot be controlled by z-index. To draw content on <map>, you can use the marker, controls and other attributes that come with the component, or you can use the <cover-view> component. App side can also use plus.nativeObj.view or subNVue to draw native content, Reference. In addition, there is no hierarchical problem with the nvue file on the App side. Starting from WeChat Basic Library 2.8.3, it supports the same layer rendering of map components, and there is no layer problem anymore.

The controls property of the WeChat MiniApp will be deprecated, Details.If the base library used supports same-layer rendering, you can use the <view> component directly, otherwise use the <cover-view> component The map of the nvue file on the App side is more aligned with the MiniApp. The map in vue has the same function as plus.map, and is slightly different from the map of the MiniApp. **It is recommended to use nvue when using map on the App side. ** If local images are used on the app side, the resources need to be set to release mode before packaging. Add a new runmode node to app-plus in the manifest file, and set the value to liberate. Do not use <map> components in scroll-view, swiper, picker-view, and movable-view in MiniApp involving hierarchical issues and in app-vue. -In MiniApp and app-vue, css animations are invalid for <map> components. The latitude and longitude used by the map component are the coordinates of the National Bureau of Surveying. To call the uni.getLocation interface, you need to specify the type as gcj02. The underlying engines of <map> components are different on different platforms: WeChat MiniApp are Tencent Maps; H5 is Tencent Maps or Google Maps or Gaode Maps; App, Alipay (Chinese mainland version) MiniApp are Gaode Maps; Baidu MiniApp and QuickApp are Baidu Maps. app-vue can also use Baidu map, configure it in the manifest, and take effect after packaging, but app-nvue only supports Gaode map. In addition, the APIs for selecting maps and viewing map locations only support Amap. If there is no special need on the App side, it is recommended to use Amap. The default api of the map component refers to the WeChat MiniApp. If you need to use plus.map, you can get the native map object through $getAppMap, see details. Note that the map component of nvue is not a plus.map object, and $getAppMap cannot be used The H5 terminal needs to be deployed on the https service to obtain location information, and the local preview (localhost) can still use the http protocol. When using the Chrome browser on a PC device without a GPS module or without a GPS signal, the location information is obtained by connecting to the Google server, and domestic users may fail to obtain the location information. To use the map component on the app side, you need to apply for SDK qualification from a third-party service provider such as AutoNavi or Baidu, and obtain an AppKey. When packaging, you need to check the corresponding module in the manifest file and fill in the Appkey in the SDK configuration. Note that the application package name must match the package name when packaging, and the certificate information must match**. There are detailed application guidelines on the manifest visualization interface. The use of maps on the H5 side is related to positioning. It is necessary to configure the secret key (key) applied by third-party map service providers such as Tencent or Google in manifest.json. Amap requires additional configuration of securityJsCode or serviceHost, for details, refer to Amap Documentation. ios nvue Color does not support ARGB hexadecimal, use rgba(r,g,b,a) instead Pay attention to the conversion of the position coordinate system. There are global GPS standards, national standards, and Baidu private standards. If one standard is used for positioning and the map is another standard, there will be displacement deviations when displayed on the map. It is generally recommended to use the national standard gcj02 uniformly. # FAQ

Q：应用中使用了 <map> 组件，打包为App时，提示缺少权限模块怎么办？

A：App端原生地图，依赖第三方的 SDK，因此打包移动应用时，需要在manifest中勾选相关的权限并填写 key 信息，详见。

Q：国外应用想使用谷歌地图/google地图怎么办？

A: App 3.4+ 已支持 Google 地图， App 3.4 以下版本使用下面的方案

在web-view下调用谷歌的web地图写一个原生插件封装谷歌原生地图，具体参考uni-app插件市场的原生插件开发教程。插件市场已有三方写好的地图插件。

# Three-party positioning and map service fee description

使用三方定位或者地图服务，需向服务提供商（如：高德地图、百度地图、腾讯地图、谷歌地图）申请商业授权和缴纳费用（5万/年）。

DCloud为开发者争取了福利，可优惠获取商业授权。如有需求请发邮件到bd@dcloud.io（注明你的公司名称、应用介绍、HBuilder账户）；你也可以通过uni-im发起在线咨询，地址：地图商业授权咨询。

详见：https://uniapp.dcloud.net.cn/tutorial/app-geolocation.html#lic

# unicloud-map 云端一体组件

若想要在地图上展示自定义的POI信息，试试 unicloud-map 云端一体组件，该组件将前端地图组件与云端数据库无缝连接，只需写一个<unicloud-map>组件，即可从数据库中获取附近的POI信息并在地图上呈现。无论是静态还是动态的POI，甚至更多自定义功能，都轻松实现。让地图开发变得愉快又高效。

下载地址：https://ext.dcloud.net.cn/plugin?name=unicloud-map

文档地址：https://doc.dcloud.net.cn/uniCloud/unicloud-map.html

渲染静态POI运行效果图

通过从数据库获取POI数据，渲染到地图上