【愚公系列】《微信小程序与云开发从入门到实践》021-map(地图)组件及应用

原创

愚公搬代码

发布于 2025-01-17 21:02:13

12500

代码可运行

文章被收录于专栏：愚公系列-书籍专栏愚公系列-书籍专栏

运行总次数：0

代码可运行

标题	详情
作者简介	愚公搬代码
头衔	华为云特约编辑，华为云云享专家，华为开发者专家，华为产品云测专家，CSDN博客专家，CSDN商业化专家，阿里云专家博主，阿里云签约作者，腾讯云优秀博主，腾讯云内容共创官，掘金优秀博主，亚马逊技领云博主，51CTO博客专家等。
近期荣誉	2022年度博客之星TOP2，2023年度博客之星TOP2，2022年华为云十佳博主，2023年华为云十佳博主等。
博客内容	.NET、Java、Python、Go、Node、前端、IOS、Android、鸿蒙、Linux、物联网、网络安全、大数据、人工智能、U3D游戏、小程序等相关领域知识。
欢迎	👍点赞、✍评论、⭐收藏

🚀前言

在现代应用开发中，地图功能的实现已成为提升用户体验的重要一环。作为一款流行的应用框架，微信小程序提供了强大的地图组件（map），使开发者能够轻松地集成地图功能，展示地理位置信息，并实现丰富的交互体验。无论是定位用户位置、搜索附近商家，还是规划行程路线，地图组件都能为用户提供更直观的服务。

本篇文章将深入解析微信小程序的地图组件，包括其基本用法、配置项、以及如何在实际项目中灵活应用。我们将通过实例演示，帮助你理解地图组件的各种功能，如标记点、绘制路线、获取用户当前位置等，确保你能够掌握地图组件的使用技巧。

无论你是刚接触小程序开发的新手，还是希望提升项目功能的资深开发者，这篇文章都将为你提供实用的见解和代码示例。让我们一起探索微信小程序的地图组件，发掘其无限可能，打造出更具吸引力和实用性的应用吧！

🚀一、map(地图)组件及应用

🔎1.`map` 组件及应用

map 组件提供了强大的地图功能，除了基础的地图展示外，还支持添加导航路径、标记点等覆盖物。可以通过 markers 属性向地图中添加标记点。

🦋1.1 示例：基础地图展示

在示例工程的 pages 文件夹下，新建一组命名为 mapDemo 的页面文件，编写如下代码：

<!-- pages/mapDemo/mapDemo.wxml -->
<map style="width: 100%; height: 400px;"
     longitude="121.5" latitude="31.2" scale="10"></map>

longitude：设置地图中心位置的经度。
latitude：设置地图中心位置的纬度。
scale：设置地图缩放级别。

运行代码后，效果是地图的中心点会显示在经纬度（121.5, 31.2）的位置，初始缩放级别为 10。

🦋1.2 示例：添加标记点

通过 map 组件的 markers 属性，可以向地图中添加标记点。在 mapDemo.wxml 文件中添加以下代码：

<!-- pages/mapDemo/mapDemo.wxml -->
<map style="width: 100%; height: 400px;"
     longitude="121.5" latitude="31.2" scale="10"
     markers="{{markers}}"></map>

在 mapDemo.js 文件中，添加如下测试数据：

// pages/mapDemo/mapDemo.js
Page({
  data: {
    markers: [{
      id: 1,        // 标记点 id
      latitude: 31.2, // 纬度
      longitude: 121.5, // 经度
      title: "标记点标题", // 标题
      label: {      // 选中后的弹窗配置
        content: "中心位置", 
        color: "#ff0000", 
        bgColor: "#0000ff55", 
        fontSize: 22
      }
    }]
  }
});

id：标记点的唯一标识。
latitude 和 longitude：标记点的经纬度。
title：标记点的标题。
label：选中标记点后弹窗的配置，包括 content（内容）、color（字体颜色）、bgColor（背景色）、fontSize（字体大小）。

运行代码后，地图中将显示一个标记点，并且当用户点击标记点时，会弹出显示配置的内容与样式。

marker 标记物实际上有 3 部分组成：图标、标记物的描述和标记物内容视图。点击标记物后，会弹出标记物的内容视图，此内容视图也支持完全自定义。

map 组件的属性

属性名	类型	意义
longitude	数值	设置中心位置的经度
latitude	数值	设置中心位置的纬度
scale	数值	设置缩放级别，范围为 3-20
min-scale	数值	设置用户可调节的最小缩放级别
max-scale	数值	设置用户可调节的最大缩放级别
markers	对象数组	设置标记点数组，其中为 `Marker` 对象
polyline	对象数组	设置折线标记物数组，其中为 `Polyline` 对象
circles	对象数组	设置圆形标记物数组，其中为 `Circle` 对象
include-points	对象数组	缩放视图，使其包含数组中的所有位置，其中为 `Point` 坐标对象
show-location	布尔值	设置是否显示当前定位点
polygons	对象数组	设置多边形覆盖物数组，其中为 `Polygon` 对象
subkey	字符串	个性化地图使用的 `key` 值
layer-style	数值	个性化地图配置的 `style`
rotate	数值	地图的旋转角度
skew	数值	地图的倾斜角度
enable-3D	布尔值	设置是否展示 3D 效果的楼块
show-compass	布尔值	设置是否显示指南针
show-scale	布尔值	设置是否显示比例尺
enable-overlooking	布尔值	设置是否支持俯视视角
enable-zoom	布尔值	设置是否支持缩放
enable-scroll	布尔值	设置地图是否可拖动
enable-rotate	布尔值	设置地图是否支持旋转
enable-satellite	布尔值	设置是否开启卫星图
enable-traffic	布尔值	设置是否开启实时路况
enable-poi	布尔值	设置是否展示 POI 点
enable-building	布尔值	设置是否展示建筑物
setting	对象	配置项，后面会介绍
bindtap	函数	绑定点击地图时的回调
bindmarkertap	函数	绑定点击标记点时的回调
bindlabeltap	函数	绑定点击标记点上的 `label` 的回调
bindcontroltap	函数	绑定点击地图控件的回调
bindcallouttap	函数	绑定点击标记点对应内容区域的回调
bindupdated	函数	绑定地图渲染更新完成后的回调
bindregionchange	函数	绑定地图视野发生变化的回调
bindpoitap	函数	绑定点击地图中 POI 点的回调
bindanchorpointtap	函数	绑定点击定位标记时的回调

可以看到，map 组件本身比较复杂，且提供了非常强的扩展能力。其中 setting 属性需要提供的对象可以理解为将 map 本身的属性进行了一层包装，方便开发者进行统一设置。

如下是一个示例：

在 mapDemo.wxml 文件中编写以下代码：

<!-- pages/mapDemo/mapDemo.wxml -->
<map style="width: 100%; height: 400px;"
     setting="{{setting}}"
     markers="{{markers}}"></map>

在 mapDemo.js 文件中提供配置数据如下：

// pages/mapDemo/mapDemo.js
Page({
  data: {
    setting: {
      longitude: 121.5,  // 经度
      latitude: 31.2,   // 纬度
      scale: 10         // 初始缩放级别
    },
    markers: [{
      id: 1,            // 标记点 id
      latitude: 31.2,   // 纬度
      longitude: 121.5, // 经度
      title: "标记点标题", // 标题
      label: {          // 选中后的弹窗配置
        content: "中心位置",
        color: "#ff0000",
        bgColor: "#0000ff55",
        fontSize: 22
      }
    }]
  }
});

修改后的代码运行效果和之前一致。map 组件的 polyline 属性需要配置为一个列表，列表中的 Polyline 对象用来描述需要添加的线段。Polyline 对象的属性如表所示：

属性名	类型	意义
points	列表，列表中的对象为： { latitude: 纬度 longitude: 经度 }	通过经纬度确定线段中的每个点
color	字符串	设置线条颜色
colorList	字符串列表	设置线段的颜色为彩虹线
width	数值	设置线段的宽度
dottedLine	布尔值	设置是否使用虚线
arrowLine	布尔值	设置是否带有箭头
arrowIconPath	字符串	设置线段箭头部分的图标
borderColor	字符串	设置线段边框的颜色
borderWidth	数值	设置边框宽度
level	字符串	设置线条的压盖关系，可选值为： - `abovelabels`: 显示在所有 POI 之上 - `abovebuildings`: 显示在所有的楼块之上，POI 之下 - `aboveroads`: 显示在道路之上，楼块之下

用来指定多边形的 Polygon 对象可配置的属性如下表所示：

属性名	类型	意义
points	列表，列表中的对象为： { latitude: 纬度 longitude: 经度 }	通过经纬度确定多边形中的每个顶点
strokeWidth	数值	设置线条宽度
strokeColor	字符串	设置线条颜色
fillColor	字符串	设置填充颜色
zIndex	数值	设置 Z 轴层级
level	字符串	同 `Polyline` 的 level 属性

用来指定圆形的 Circle 对象可配置的属性如下表所示：

属性名	类型	意义
latitude	数值	设置圆心所在点纬度
longitude	数值	设置圆心所在点经度
color	字符串	设置线条颜色
fillColor	字符串	设置填充颜色
radius	数值	设置圆半径
strokeWidth	数值	设置线条宽度
level	字符串	同 `Polyline` 的 level 属性

向地图中添加标记物需要使用 markers 属性，每个 Marker 对象可配置的属性如下表所示：

属性名	类型	意义
id	数值	标记物的 id，点击事件会返回此 id
clusterId	数值	聚合 id
joinCluster	布尔值	设置是否参与聚合
latitude	数值	设置标记物位置纬度
longitude	数值	设置标记物位置经度
title	字符串	设置标记物标题
zIndex	数值	设置 Z 轴层级
iconPath	字符串	设置自定义标记物图标的资源路径
rotate	数值	设置旋转角度
alpha	数值	设置标记物的透明度
width	数值	设置宽度
height	数值	设置高度
callout	对象	点击标记物后，弹出的内容窗口
customCallout	对象	点击标记物后，自定义弹出的内容窗口
label	对象	标记物旁边的标签
anchor	对象	标记物布局时的锚点

Marker 对象中的 callout 属性可以设置点击标记物后弹出的窗口，此可配置的属性如下：

属性名	类型	意义
content	字符串	设置内容文本
color	字符串	设置文本颜色
fontSize	数值	设置文字大小
borderRadius	数值	设置边框圆角
borderWidth	数值	设置边框宽度
borderColor	字符串	设置边框颜色
bgColor	字符串	设置背景色
padding	数值	设置文本边缘间距
display	字符串	设置显示模式，可选值为： - `BYCLICK`: 点击显示 - `ALWAYS`: 常显
textAlign	字符串	设置对齐模式，可选值为： - `left`: 左对齐 - `right`: 右对齐 - `center`: 居中对齐
anchorX	数值	设置横向偏移量
anchorY	数值	设置纵向偏移量

Marker 对象中的 label 属性设置标记点下方的标签样式，此可配置的属性如下：

属性名	类型	意义
content	字符串	设置文本内容
color	字符串	设置文本颜色
fontSize	数值	设置文字大小
anchorX	数值	设置标签的 X 轴标
anchorY	数值	设置标签的 Y 轴标
borderWidth	数值	设置边框宽度
borderColor	字符串	设置边框颜色
borderRadius	数值	设置圆角半径
bgColor	字符串	设置背景色
padding	数值	设置文本边距
textAlign	字符串	设置对齐样式

map 组件中标记物的内容视图支持完全的自定义，首先需要为 Marker 对象添加 customCallout 属性，此属性对应的可选项只有 3 个，如下所示：

属性名	类型	意义
display	字符串	设置显示模式，可选值为： - `BYCLICK`: 点击显示 - `ALWAYS`: 常显
anchorX	数值	设置横向偏移量
anchorY	数值	设置纵向偏移量

自定义标记物的内容视图采用的便是组件的插槽技术，可以修改 mapDemo.wxml 代码如下：

<!-- pages/mapDemo/mapDemo.wxml -->
<map style="width: 100%; height: 400px;"
     setting="{{setting}}"
     markers="{{markers}}">
  <cover-view slot="callout">
    <cover-view marker-id="1">
      <text style="background-color: red; color: white;">自定义的内容视图</text>
    </cover-view>
  </cover-view>
</map>

其中，将 slot 属性设置为 callout 即表示要使用标记物内容视图插槽，其内可以添加任意 cover-view 组件，将组件 marker-id 属性与 Marker 对象的 id 属性相对应即可。

该页面介绍了如何使用 map 组件的 JavaScript 上下文对象进行操作，并给出了 MapContext 对象的一些常用方法。以下是页面的详细信息：

对于 map 组件，可以使用以下方法获取到 JavaScript 上下文对象：

wx.createMapContext(id)

MapContext 对象提供了操作 map 组件的方法，如表所示。

方法名	参数	意义
getCenterLocation	Object - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	获取地图当前中心位置的经纬度
setLocalMarkerIcon	Object - String iconPath: 图标资源路径 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	设置当前定位点的图标
moveToLocation	Object - Number longitude: 经度 - Number latitude: 纬度 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	将地图的中心位置移动到某个坐标
translateMarker	Object - Number markerId: 所移动的标记物 ID - Object destination: { Number longitude: 经度 Number latitude: 纬度 } - Boolean autoRotate: 移动过程中是否自动旋转标记物 - Number rotate: 标记物的旋转角度 - Boolean moveWithRotate: 移动和旋转动作同时进行 - Number duration: 动画执行时长 - Function animationEnd: 动画结束的回调 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	对标记物进行移动，可以到动画
moveAlong	Object - Number markerId: 所移动的标记物 ID - Array path: 路径坐标列表，其中每个对象为包含经纬度信息 - Boolean autoRotate: 移动过程中是否自动旋转标记物 - Number duration: 动画时长 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	根据设置的路径移动标记物
includePoints	Object - Array points: 要显示在可视区域内的所有坐标点，其中每个对象为包含经纬度信息 - Array padding: 包含所有坐标点的矩形距离地图视野边缘的间距，列表中需要设置 4 个数值，表示上、右、下、左间距 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	缩放地图视野，使设置的所有坐标点显示在可视范围内
getRegion	Object - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	获取当前地图的视野范围
getRotate	Object - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	获取当前地图的旋转角度
getScale	Object - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	获取当前地图的缩放级别
setCenterOffset	Object - Array offset: 偏移量数组，其中需要两个数值，分别表示中心点向右和向下的偏移量 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	设置地图中心点的位置偏移量
removeCustomLayer	Object - String layerId: 个性化图层的 `id` - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	移除个性化图层
addCustomLayer	Object - String layerId: 个性化图层的 `id` - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	添加个性化图层
addGroundOverlay	Object - String id: 图片图层的 id - String src: 图片资源路径 - Object bounds: 图片覆盖物的经纬度范围 - Boolean visible: 是否可见 - Number zIndex: 设置图层层级 - Number opacity: 设置图层透明度 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	添加自定义图片图层
addVisualLayer	Object - String layerId: 可视化图层的 id - Number interval: 刷新频率，单位秒 - Number zIndex: 设置图层层级 - Number opacity: 设置图层透明度 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	添加可视化图层
removeVisualLayer	Object - String layerId: 可视化图层的 id - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	移除可视化图层
updateGroundOverlay	（参数同 `addGroundOverlay` 方法）	更新自定义图片图层
removeGroundOverlay	Object - String id: 图片图层的 id - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	移除自定义图片图层
toScreenLocation	Object - Number latitude: 纬度 - Number longitude: 经度 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	将经纬度坐标转换成对应屏幕上的位置
openMapApp	Object - Number latitude: 目的地纬度 - Number longitude: 目的地经度 - String destination: 目的地名称 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	拉取设备中的地图应用进行导航
addMarkers	Object - Array markers: 标记物对象数组 - Boolean clear: 是否先清空已有的标记物 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	动态向地图上添加标记物
removeMarkers	Object - Array markerIds: 标记物 id 数组 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	移除一组地图上的标记物
initMarkerCluster	Object - Boolean enableDefaultStyle: 是否启用默认聚合样式 - Boolean zoomOnClick: 点击已聚合的点时是否自动聚合分离 - Boolean gridSize: 设置聚合距离 - Function success: 成功回调 - Function fail: 失败回调 - Function complete: 完成回调	初始化标记点的聚合配置

通过 MapContext 对象，可以更容易地控制 map 组件的逻辑，实现业务需求。例如，可以拉起设备中的地图应用进行导航、动态添加和移除标记物，以及初始化标记点的聚合配置。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

腾讯技术创作特训营S11#重启人生

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

腾讯技术创作特训营S11#重启人生