map | uni-app-x

展示全部

# map

地图

地图由三方专业地图厂商提供SDK。在App和Web中，使用三方SDK需在manifest中进行配置。

# 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	4.31	4.31	4.61

不同图商在不同平台的兼容性

图商	Web	Android	iOS	harmony
腾讯	√	4.31+	4.31+	4.61+
高德	√	x	x	x
Google	√	x	x	x

除了内置支持的图商，还可以在插件市场寻找更多地图解决方案：

插件市场的三方地图插件
使用web-view中的地图

# 属性

名称类型默认值兼容性描述

longitude

number

中心经度

latitude

number

中心纬度

scale

number

缩放级别，web端取值范围为5-18 , app端取值范围为3-20

min-scale

number

最小缩放级别

max-scale

number

最大缩放级别

layer-style

string

"1"

个性化地图（如实现地图暗黑模式）

markers

Array<Marker>

标记点

名称

类型

必备

默认值

兼容性

描述

number

是

标记点id，marker点击事件回调会返回此id。建议为每个marker设置上Number类型id，保证更新marker时有更好的性能。最大限制9位数

latitude

number

是

纬度，浮点数，范围 -90 ~ 90

longitude

number

是

经度，浮点数，范围 -180 ~ 180

iconPath

string

是

显示的图标，项目目录下的图片路径，支持相对路径写法，以'/'开头则表示相对小程序根目录；也支持临时路径

title

string

否

null

标注点名，点击时显示，callout存在时将被忽略

rotate

number

否

旋转角度，顺时针旋转的角度，范围 0 ~ 360

alpha

number

否

标注的透明度，范围 0 ~ 1

width

number

否

默认为图片实际宽度

标注图标宽度

height

number

否

默认为图片实际高度

标注图标高度

ariaLabel

string

否

null

无障碍访问，（属性）元素的额外描述

anchor

Anchor

否

[0.5, 1]

经纬度在标注图标的锚点，默认底边中点 {x, y}，x表示横向(0-1)，y表示竖向(0-1)。{x: .5, y: 1} 表示底边中点

名称	类型	必备	默认值	兼容性	描述
x	number	是	-	-	-
y	number	是	-	-	-

callout

MapMarkerCallout

否

null

自定义标记点上方的气泡窗口

名称

类型

必备

默认值

兼容性

描述

content

string

否

文本

color

string.ColorString

否

"black"

文本颜色

fontSize

number

否

null

文字大小

borderRadius

number

否

边框圆角

borderWidth

number

否

边框宽度

borderColor

string.ColorString

否

"transparent"

边框颜色

bgColor

string.ColorString

否

"#fff"

背景色

padding

number

否

文本边缘留白

display

string

否

"BYCLICK"

'BYCLICK':点击显示; 'ALWAYS':常显

合法值	兼容性	描述
BYCLICK	-	-
ALWAYS	-	-

textAlign

string

否

"left"

文本对齐方式。

合法值	兼容性	描述
left	-	-
center	-	-
right	-	-

anchorX

number

否

0.5

横向偏移量，向右为正数

anchorY

number

否

纵向偏移量，向下为正数

label

MapMarkerLabel

否

null

为标记点旁边增加标签

名称

类型

必备

默认值

兼容性

描述

content

string

否

文本

color

string

否

文本颜色

fontSize

number

否

文字大小

number

否

label的坐标，原点是 marker 对应的经纬度

number

否

label的坐标，原点是 marker 对应的经纬度

anchorX

number

否

label的坐标，原点是 marker 对应的经纬度

anchorY

number

否

label的坐标，原点是 marker 对应的经纬度

borderWidth

number

否

边框宽度

borderColor

string

否

边框颜色

borderRadius

number

否

边框圆角

bgColor

string

否

背景色

padding

number

否

文本边缘留白

textAlign

string

否

文本对齐方式。

合法值	兼容性	描述
left	-	-
center	-	-
right	-	-

ariaLabel

string

否

无障碍访问，（属性）元素的额外描述

clusterId

number

否

null

自定义点聚合簇效果时使用

customCallout

MapMarkerCallout

否

null

自定义气泡窗口

名称

类型

必备

默认值

兼容性

描述

content

string

否

文本

color

string.ColorString

否

"black"

文本颜色

fontSize

number

否

null

文字大小

borderRadius

number

否

边框圆角

borderWidth

number

否

边框宽度

borderColor

string.ColorString

否

"transparent"

边框颜色

bgColor

string.ColorString

否

"#fff"

背景色

padding

number

否

文本边缘留白

display

string

否

"BYCLICK"

'BYCLICK':点击显示; 'ALWAYS':常显

合法值	兼容性	描述
BYCLICK	-	-
ALWAYS	-	-

textAlign

string

否

"left"

文本对齐方式。

合法值	兼容性	描述
left	-	-
center	-	-
right	-	-

anchorX

number

否

0.5

横向偏移量，向右为正数

anchorY

number

否

纵向偏移量，向下为正数

joinCluster

boolean

否

null

是否参与点聚合

covers

array

即将移除，请使用 markers

polyline

Array<Polyline>

路线

名称

类型

必备

默认值

兼容性

描述

points

Array<LocationObject>

是

经纬度数组

名称

类型

必备

默认值

兼容性

描述

latitude

number

是

纬度，浮点数，范围为-90~90，负数表示南纬

longitude

number

是

经度，范围为-180~180，负数表示西经

color

string.ColorString

否

null

线的颜色

width

number

否

线的宽度

dottedLine

boolean

否

false

是否虚线

arrowLine

boolean

否

false

带箭头的线

arrowIconPath

string

否

null

更换箭头图标

borderColor

string.ColorString

否

null

线的边框颜色

borderWidth

number

否

null

线的厚度

colorList

Array<string>

否

null

彩虹线

polygons

Array<Polygon>

多边形

名称

类型

必备

默认值

兼容性

描述

points

Array<LocationObject>

是

经纬度数组

名称

类型

必备

默认值

兼容性

描述

latitude

number

是

纬度，浮点数，范围为-90~90，负数表示南纬

longitude

number

是

经度，范围为-180~180，负数表示西经

strokeWidth

number

否

描边的宽度

strokeColor

string.ColorString

否

null

描边的颜色

fillColor

string.ColorString

否

null

填充颜色

zIndex

number

否

设置多边形 Z 轴数值

circles

Array<Circle>

圆

名称

类型

必备

默认值

兼容性

描述

latitude

number

是

纬度

longitude

number

是

经度

radius

number

是

半径

color

string.ColorString

否

null

描边的颜色

fillColor

string.ColorString

否

null

填充颜色

strokeWidth

number

否

描边的宽度

controls

Array<Control>

控件

名称

类型

必备

默认值

兼容性

描述

position

ControlPosition

是

控件相对地图位置

名称

类型

必备

默认值

兼容性

描述

left

number

否

距离地图的左边界多远

top

number

否

距离地图的上边界多远

width

number

否

控件宽度

height

number

否

控件高度

iconPath

string

是

项目目录下的图片路径，支持相对路径写法，以'/'开头则表示相对项目根目录；也支持临时路径

number

否

null

在控件点击事件回调会返回此id

clickable

boolean

否

false

默认不可点击

include-points

Array<LocationObject>

缩放视野以包含所有给定的坐标点

名称

类型

必备

默认值

兼容性

描述

latitude

number

是

纬度，浮点数，范围为-90~90，负数表示南纬

longitude

number

是

经度，范围为-180~180，负数表示西经

show-location

boolean

显示带有方向的当前定位点

enable-3D

boolean

false

是否显示3D楼块

show-compass

boolean

false

是否显示指南针

enable-zoom

boolean

true

是否支持缩放

enable-scroll

boolean

true

是否支持拖动

enable-rotate

boolean

false

是否支持旋转

rotate

number

旋转角度(范围0-360)地图正北和设备 y 轴角度的夹角

skew

number

倾斜角度，范围 0 ~ 40 , 关于 z 轴的倾角

enable-overlooking

boolean

false

是否开启俯视（是否开启手势修改倾斜角度）

enable-satellite

boolean

false

是否开启卫星图

enable-traffic

boolean

false

是否开启实时路况

enable-poi

boolean

false

是否展示 POI 点

enable-building

boolean

false

是否展示建筑物

enable-indoorMap

boolean

false

是否展示室内地图

@markertap

(event: UniMapMarkerTapEvent) => void

点击标记点时触发

@callouttap

(event: UniEvent) => void

点击标记点对应的气泡时触发

@controltap

(event: UniMapControlTapEvent) => void

点击控件时触发

@regionchange

(event: UniMapRegionChangeEvent) => void

视野发生变化时触发

@updated

(event: UniMapUpdatedEvent) => void

在地图渲染更新完成时触发

@tap

(event: UniMapTapEvent) => void

点击地图时触发

@anchorpointtap

(event: UniMapAnchorPointTapEvent) => void

点击定位标时触发

@poitap

(event: UniMapPoiTapEvent) => void

点击地图poi点时触发

subkey

string

(string)
地图能力【个性化地图】使用的key，不支持动态修改

show-scale

boolean

(boolean)
显示比例尺，工具暂不支持

enable-auto-max-overlooking

boolean

(boolean)
开启最大俯视角，俯视角度从 45 度拓展到 75 度

setting

object

(object)
配置项

@labeltap

eventhandle

(eventhandle)
点击label时触发，e.detail = {markerId}

@polylinetap

eventhandle

(eventhandle)
点击地图路线时触发，e.detail = {longitude, latitude}

@abilitysuccess

eventhandle

(eventhandle)
地图能力生效时触发，e.detail = {ability, errCode, errMsg}

@abilityfail

eventhandle

(eventhandle)
地图能力失败时触发，e.detail = {ability, errCode, errMsg}

@authsuccess

eventhandle

(eventhandle)
地图鉴权结果成功时触发，e.detail = {errCode, errMsg}

@interpolatepoint

eventhandle

(eventhandle)
MapContext.moveAlong 插值动画时触发。`e.detail = {markerId, longitude, latitude, animationStatus: "interpolating"

@error

eventhandle

(eventhandle)
组件错误时触发，例如创建或鉴权失败，e.detail = {longitude, latitude}

~~theme~~

string

"normal"

主题（satellite 或 normal）

# 事件

# UniMapMarkerTapEvent

# UniMapMarkerTapEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniMapMarkerTapEventDetail

否

名称	类型	必备	默认值	兼容性	描述
markerId	number	否	-	-

# UniMapControlTapEvent

# UniMapControlTapEventDetail

# UniMapControlTapEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
controlId	number	否	-	-

# UniMapRegionChangeEvent

# UniMapRegionChangeEvent 的属性值

名称	类型	必填	默认值	兼容性	描述
causedBy	string	否	-	-

# UniMapUpdatedEvent

# UniMapTapEvent

# UniMapTapEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniMapTapEventDetail

否

名称	类型	必备	默认值	兼容性	描述
latitude	number	否	-	-
longitude	number	否	-	-

# UniMapAnchorPointTapEvent

# UniMapAnchorPointTapEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniMapAnchorPointTapEventDetail

否

名称	类型	必备	默认值	兼容性	描述
latitude	number	否	-	-
longitude	number	否	-	-

# UniMapPoiTapEvent

# UniMapPoiTapEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniMapPoiTapEventDetail

否

名称	类型	必备	默认值	兼容性
latitude	number	否	-	-
longitude	number	否	-	-
name	string	否	-	-

# 子组件

不可以嵌套组件

注意事项

App平台 layer-style 属性用于设置个性化地图样式，可用于适配实现地图的暗黑模式。使用前需在腾讯位置服务后台 “个性化样式” 的 “我的样式” 中创建，并在 “样式应用” 中将相应的Key绑定样式，layer-style 的值为绑定样式的序号。更多信息可参考腾讯地图官方文档Android平台个性化地图、iOS平台个性化地图。

# 上下文对象API

map组件的操作api为uni.createMapContext()。

给map组件设一个id属性，将id的值传入uni.createMapContext()，即可得到map组件的上下文对象，进一步可使用.addMarkers()等方法。

# 示例

hello uni-app x

Template

Script

<template>
  <view class="content">
    <map class="map" id="map1" ref="map1" :longitude="location.longitude" :latitude="location.latitude" :scale="scale"
      :markers="markers" :include-points="includePoints" :polyline="polyline" :polygons="polygons" :circles="circles"
      :controls="controls" :show-location="showLocation" :enable-3D="enable3D" :rotate="rotate" :skew="skew"
      :show-compass="showCompass" :enable-overlooking="enableOverlooking" :enable-zoom="enableZoom"
      :enable-scroll="enableScroll" :enable-rotate="enableRotate" :enable-satellite="enableSatellite"
      :enable-traffic="enableTraffic" @markertap="onmarkertap" @callouttap="oncallouttap" @controltap="oncontroltap"
      @regionchange="onregionchange" @tap="maptap" @updated="onupdated" @poitap="onpoitap"></map>
    <scroll-view class="scrollview" scroll-y="true">
      <view class="tips">注意：App和Web需要正确配置地图服务商的Key才能显示地图组件</view>
      <view class="uni-title">
        <text class="uni-title-text">属性示例</text>
      </View>
      <input-data defaultValue="13" title="scale: 缩放级别，取值范围为5-18" type="number"
        @confirm="confirm_scale_input"></input-data>
      <boolean-data :defaultValue="showLocation" title="开启显示带有方向的当前定位点" @change="change_show_location"></boolean-data>
      <boolean-data :default-value="enable3D" :disabled="enableSatellite" title="3D效果(放大缩放级别才能看到建筑物3D效果)" @change="change_enable_3d"></boolean-data>
      <boolean-data :default-value="showCompass" title="显示指南针" @change="change_show_campass"></boolean-data>
      <boolean-data :default-value="enableOverlooking" title="俯视支持" @change="change_enable_overlooking"></boolean-data>
      <boolean-data :default-value="enableRotate" title="旋转支持" @change="change_enable_rotate"></boolean-data>
      <boolean-data :default-value="enableZoom" title="缩放支持" @change="change_enable_zoom"></boolean-data>
      <boolean-data :default-value="enableScroll" title="拖动支持" @change="change_enable_scroll"></boolean-data>
      <boolean-data :default-value="enableSatellite" title="卫星图" @change="change_enable_satellite"></boolean-data>
      <boolean-data :default-value="enableTraffic" title="实时路况" @change="change_enable_traffic"></boolean-data>

      <button class="button" @click="addControls">控件</button>
      <button class="button" @click="addMarkers">添加标记点</button>
      <!-- #ifdef WEB || MP -->
      <button class="button" @click="addMarkersLabel">为标记点旁边增加标签</button>
      <!-- #endif -->
      <button class="button" @click="removeMarker">移除ID为4的标记点和标签</button>
      <button class="button" @click="addPolyline">添加路线</button>
      <button class="button" @click="removePolyline">移除一条路线</button>
      <button class="button" @click="addPolygons">添加多边形</button>
      <button class="button" @click="removePolygon">移除一个多边形</button>
      <button class="button" @click="addCircles">添加圆</button>
      <button class="button" @click="removeCircle">移除一个圆</button>
      <button class="button" @click="includePoint">缩放视野以包含所有给定的坐标点</button>
      <view class="uni-title">
        <text class="uni-title-text">方法示例</text>
      </View>
      <button class="button" @click="handleGetCenterLocation">获取当前地图中心的经纬度</button>
      <button class="button" @click="handleGetRegion">获取当前地图的视野范围</button>
      <button class="button" @click="handleTranslateMarker">平移marker</button>
      <button class="button" @click="handleMoveToLocation">将地图中心移动到指定坐标</button>
      <button class="button" @click="handleMoveToMyLocation">将地图中心移动到当前位置</button>
      <button class="button" @click="handleGetScale">获取当前地图的缩放级别</button>

    </scroll-view>
  </view>
</template>



<style>
  .content {
    flex: 1;
  }

  .map {
    width: 100%;
    height: 300px;
    background-color: #f0f0f0;
  }

  .scrollview {
    flex: 1;
    padding: 10px;
  }

  .button {
    margin-top: 5px;
    margin-bottom: 5px;
  }

  .tips {
    font-size: 12px;
    margin-top: 15px;
    opacity: .8;
  }
</style>

# 三方地图SDK

# 腾讯地图

# app-android平台仓储依赖

com.tencent.map:tencent-map-vector-sdk:5.6.0
com.tencent.map:sdk-utilities:1.0.9
com.tencent.map.geolocation:TencentLocationSdk-openplatform:7.5.4.3
com.github.bumptech.glide:glide:4.16.0

# app-ios平台Cocoapods依赖

{"name":"Tencent-MapSDK", "version": "5.1.0"}
{"name": "Tencent-MapVisualPlugin", "version": "3.1.0"}
{"name": "Tencent-MapFoundation", "version": ">=3.3.0"}
{"name": "Tencent-MapUtils", "version": "1.2.3"}

# 审图号

GS粤（2023）1171号

# Map Key配置

app平台目前还没有可视化界面，采用摇树机制，即调用地图相关api才会把地图组件编译到基座中，Map Key配置方式如下：

iOS平台：需要在info.plist中配置对应的Key，参考iOS平台配置腾讯地图Key
Android平台：需要在AndroidManifest.xml配置Key，参考Andoird平台配置腾讯地图Key
Harmony平台：需要在/harmony-configs/entry/src/main/module.json5的metadata属性内配置Key，同时 manifest.json 内还需要配置 app.distribute.modules.uni-map 参考Harmony平台配置腾讯地图Key

# 地图扩展

所谓地图扩展就是可以通过获取map组件的形式扩展地图功能，暂时只有Android支持，步骤如下：

新建一个uts插件，配置依赖腾讯地图SDK
在uvue页面调用uni.getElementById()获取组件对象UniElement，将UniElement对象传入uts插件
在uts插件中通过UniElement的getAndroidView获取原生地图View，使用原生地图view与地图SDK提供的API开发扩展功能,例：

import { CameraUpdateFactory } from "com.tencent.tencentmap.mapsdk.maps"
import { MapView } from "com.tencent.tencentmap.mapsdk.maps"
export function setScale(element : UniElement, scale : number) : void {
	(element?.getAndroidView() as MapView)?.map?.moveCamera(CameraUpdateFactory.zoomTo(scale.toFloat()));
}

# Tips

在App和Web平台，没有在manifest中配置好图商的sdk key信息，将无法使用地图。某些图商的sdk key，区分Web、Android、iOS，注意别配混了。有些sdk key，会绑定校验web的域名或app的包名和签名证书摘要，都要匹配准确才能使用地图。
谷歌地图仅支持 wgs84 坐标，中国的各个地图仅支持 gcj02 坐标，注意使用定位API获取的位置，需与map组件的图商需求一致，把 wgs84 的坐标显示在中国地图上会导致偏移。
地图是商业服务，需购买商业地图授权（5万/年）。如果没有授权，不但使用会被限频，还会被某些应用商店拒绝上架。DCloud与地图厂商谈判，给开发者提供了优惠，点此详询地图商业授权咨询。