# map

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信 鸿蒙 OS 版：支持

相关文档: wx.createMapContext

渲染框架支持情况：Skyline （使用最新 Nighly 工具调试）、WebView

# 功能描述

地图 v2.7.0 起支持同层渲染。

map组件提供了地图展示、交互、叠加点线面及文字等功能，同时支持个性化地图样式，可结合地图服务 API 实现更丰富功能。

为了更好的提供地图服务，请在调用 map 组件之前，先前往腾讯位置服务官网注册一个专属 KEY,在地图开发过程中，可以将这个专属 KEY 通过 subkey 参数传入；后续如遇到地图开发问题也可以在腾讯位置服务官网工单系统提交工单反馈解决；

# 地图个性化样式组件

地图个性化样式组件是腾讯位置服务为开发者提供的地图高级能力，开发者可以在法律允许的范围内定制地图风格，支持定制背景面、背景线、道路、POI等地图元素颜色、显示层级等内容；支持按照类型精细化管理POI的显示、隐藏；灵活地设计贴合业务场景的心仪地图。

购买该能力后，您可以在 MP平台「管理->付费管理->概览->地图个性化样式->去使用」中创建配置您的地图个性化样式，您可以选择我们提供的基础及高级模版，也可以通过在线编辑平台，对多种地图元素的样式进行自定义设置，以满足在不同场景下的个性化需求。

注意：

1. 自2023年6月29日0点起，该能力需要先购买再使用。若未购买，届时将无法使用该能力。具体购买方式见 付费管理。
2. 自2023年6月29日0时起，个性化地图配置界面的入口统一为微信公众平台-付费管理，请从此入口进入，腾讯位置服务官网入口不再使用。已经在小程序生效的个性化样式配置，将于2023年6月29日0时变更为默认样式，如有个性化样式配置需求，请于6月29日0时前，前往微信公众平台-付费管理进行相关能力的开通和配置。

# 地图服务API

地图服务API 与map组件基于同一套数据体系，无缝贴合，叠加使用可实现更丰富的功能。 提供：地点搜索、关键词输入提示、正/逆地址解析（经纬度与地址互转）驾车与步行路线规划等功能。

详情见：地图服务API在小程序中的使用方法

若开发者使用通过LBS开放平台自行申请的服务账号，在小程序连接并调用位置服务产品用于商业行为（政府公共事务及公益组织事务除外），腾讯位置服务有权收取商业授权费，详细内容可以查看或咨询腾讯微位置服务官网

# 深入控制地图

通过微信小程序API中wx.createMapContext方法，创建 map 上下文 MapContext 对象，通过其实现更细粒度的地图交互和功能，包括：控制地图视野、获取地图位置与视角等信息、marker移动（轨迹回放）、动态创建个性化图层、拉起地图APP选择导航等

# 小程序插件

现成插件简单接入，提供：路线规划、地图选点、城市选择器、地铁图 常用功能。

详情见：小程序地图插件使用指南

# 开源示例中心

包含Map组件、服务API、插件等功能使用方法，全面了解小程序下的所有地图能力。示例内容源码开放，降低各位开发者接入成本。

# 地图基础属性

# 属性说明

# regionchange 返回值

视野改变时，regionchange 会触发两次，返回的 type 值分别为 begin 和 end。

2.8.0 起 begin 阶段返回 causedBy，有效值为 gesture（手势触发） & update（接口触发）

2.3.0 起 end 阶段返回 causedBy，有效值为 drag（拖动导致）、scale（缩放导致）、update（调用更新接口导致）。

e = {causedBy, type, detail: {rotate, skew, scale, centerLocation, region}}

# setting

提供 setting 对象统一设置地图配置。同时对于一些动画属性如 rotate 和 skew，通过 setData 分开设置时无法同时生效，需通过 settting 统一修改。

// 默认值
const setting = {
  skew: 0,
  rotate: 0,
  showLocation: false,
  showScale: false,
  subKey: '',
  layerStyle: 1,
  enableZoom: true,
  enableScroll: true,
  enableRotate: false,
  showCompass: false,
  enable3D: false,
  enableOverlooking: false,
  enableSatellite: false,
  enableTraffic: false,
}

this.setData({
  // 仅设置的属性会生效，其它的不受影响
  setting: {
    enable3D: true,
    enableTraffic: true
  }
})

# marker

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

注：可结合地图服务API - 地点搜索 实现地图搜索功能。

# marker 碰撞关系

在一定范围内绘制多个 Marker 时，常会出现 Marker 压盖的情况，3.4.3 起支持设置碰撞关系。

# 碰撞目标

默认 Marker 不参与碰撞，collision 用于设置是否参与碰撞，支持枚举值 poi、marker，多类型时按 "," 分割。 poi: 和 poi 点碰撞后隐藏 poi marker: 和 marker 碰撞后隐藏自己或被碰的 marker

发送碰撞时，按 zIndex 区分优先级，优先级低的将会被隐藏。

例如 collision 设置为 poi,marker，表示与 poi 和 marker 均会参与碰撞。

# 整体碰撞或区域碰撞

Marker 的各个部分，包括 iconPath、callout、label 等，可以作为一个整体参与碰撞，也可独立开来。

collision-relation 属性支持 alone 和 together 两种值。 together: 作为整体参与碰撞后隐藏，此时忽略各部件 callout 和 label 的 collision 属性。 alone：独立参与碰撞后隐藏，此时各部件 callout 和 label 可单独设置 collision 属性，未填写时则与主 Marker 保持一致。

# marker 上的气泡 callout

# marker 上的自定义气泡 customCallout

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

使用方式如下，map 组件下添加名为 callout 的 slot 节点，其内部的 cover-view 通过 marker-id 属性与 marker 绑定。当 marker 创建时，该 cover-view 显示的内容将作为 callout 显示在标记点上方。

<map>
  <cover-view slot="callout">
    <cover-view marker-id="1"></cover-view>
    <cover-view marker-id="2"></cover-view>
  </cover-view>
</map>

示例DEMO： https://developers.weixin.qq.com/s/cZWIojm47pjN

# marker 上的气泡 label

# 点聚合

当地图上需要展示的标记点 marker 过多时，可能会导致界面上 marker 出现压盖，展示不全，并导致整体性能变差。针对此类问题，推出点聚合能力。

使用流程如下：

1. MapContext.initMarkerCluster 对聚合点进行初始化配置（可选）；
2. MapContext.addMarkers 指定参与聚合的 marker；
3. MapContext.on('markerClusterCreate', callback) 触发时，通过 MapContext.addMarkers 更新聚合簇的样式 （可选）；
4. MapContext.removeMarkers 移除参与聚合的 marker；

# 示例代码

在开发者工具中预览效果

需注意的是：

1. 地图上的 marker 分为普通的 marker 与参与聚合的 marker，参与聚合时需指定属性 joinCluster 为 true；
2. 自定义聚合簇样式时，同样通过 MapContext.addMarkers 进行绘制，此时需携带 clusterId。

# polyline

指定一系列坐标点，从数组第一项连线至最后一项。绘制彩虹线时，需指定不同分段的颜色，如 points 包含 5 个点，则 colorList 应传入 4 个颜色值；若 colorList 长度小于 points.length - 1，则剩下的分段颜色与最后一项保持一致。

注：可结合 地图服务API - 驾车路线规划，实现路线计算与展示。

注：textStyle 与 segmentTexts 结合可在折线线段上面绘制文字，用来显示路名。

# SegmentText

# TextStyle

level 字段表示与其它地图元素的压盖关系，可选值如下：

# polygon

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

# circle

在地图上显示圆

# control

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

# position

# bindregionchange 返回值

# 比例尺

# bindabilitysuccess、bindabilityfail 和 binderror 的返回值

bindabilitysuccess 和 bindabilityfail 事件具有额外的参数 ability 来指示是何种地图能力，可能的取值有: layer-style。

共同参数如下 errCode 的定义如下：

# 示例代码

在开发者工具中预览效果

# Bug & Tip

1. tip：个性化地图暂不支持工具中调试。请先使用微信客户端进行测试。
2. tip：地图中的颜色值color/borderColor/bgColor等需使用6位（8位）十六进制表示，8位时后两位表示alpha值，如：#000000AA
3. tip：地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。
4. tip: map 组件使用的经纬度是火星坐标系，调用 wx.getLocation 接口需要指定 type 为 gcj02
5. tip：从 2.8.0 起 map 支持同层渲染，更多请参考原生组件使用限制
6. tip：请注意原生组件使用限制。
7. tip: 若当前组件所在的页面或全局开启了 enablePassiveEvent 配置项，该内置组件可能会出现非预期表现（详情参考 enablePassiveEvent 文档）