UniApp 小程序中使用地图组件

原创于 2025-11-13 10:18:43 发布 · 279 阅读

CC 4.0 BY-SA版权

文章标签：

在 UniApp 小程序中使用地图组件，主要是通过内置的 <map> 组件和相关的 API 来实现的。为了帮助您快速了解，下面这个表格汇总了 UniApp 中地图功能的核心信息：

功能方向	实现方式	核心特点/注意事项
🗺️ 地图展示	`<map>` 组件	不同平台底层引擎不同（App/支付宝小程序为高德地图，微信小程序为腾讯地图，百度小程序为百度地图）需使用 GCJ-02 坐标系（国测局坐标）
📍 地图定位	`uni.getLocation()`	获取位置时需指定 `type: 'gcj02'` 以匹配地图组件
🚀 打开地图App	`uni.openLocation()`	使用应用内置地图查看位置，或拉起手机上的地图App进行导航

🗺️ 使用 `<map>` 组件展示地图

<map> 组件是 UniApp 中用于展示地图的核心标签。

基本用法

在 vue 文件中，你可以这样使用：

<template>
  <view class="content">
    <map 
      :latitude="latitude" 
      :longitude="longitude" 
      :markers="markers"
      :scale="scale"
      @markertap="onMarkerTap"
      style="width: 100%; height: 100vh;">
    </map>
  </view>
</template>

<script setup>
import { ref } from 'vue';

// 地图中心坐标
const latitude = ref(39.90923);
const longitude = ref(116.397428);
// 地图缩放级别
const scale = ref(16);
// 标记点
const markers = ref([
  {
    id: 1,
    latitude: 39.90923,
    longitude: 116.397428,
    title: '北京市',
    iconPath: '/static/location.png'
  }
]);

// 标记点点击事件
const onMarkerTap = (e) => {
  console.log('点击了标记点', e.detail.markerId);
};
</script>

核心属性说明

latitude / longitude：地图中心点的经纬度，必须使用 GCJ-02 坐标系。
scale：缩放级别，范围一般 5-18 。
markers：标记点数组，用于在地图上标注位置。
@markertap：点击标记点时触发的事件。

平台差异与配置

这是一个非常关键的点，不同平台的地图底层引擎不同，配置方式也有差异：

App 端：默认使用高德地图。你需要在高德地图开放平台申请 AppKey，并在 manifest.json 的 SDK 配置中填写。
微信小程序端：底层是腾讯地图。需要在微信小程序后台开通“位置接口”权限，通常无需额外配置地图 Key，除非使用高级服务。
H5 端：需要在 manifest.json 中配置腾讯地图或谷歌地图的密钥（Key）。同时，H5 端获取定位信息要求部署在 HTTPS 服务上。

📍 获取用户位置

要获取用户的当前位置，可以使用 uni.getLocation：

uni.getLocation({
  type: 'gcj02', // 重要：指定返回 GCJ-02 坐标系，以兼容地图组件
  success: (res) => {
    console.log('当前位置：', res.latitude, res.longitude);
    // 可以将获取到的坐标设置为地图的中心点
    latitude.value = res.latitude;
    longitude.value = res.longitude;
  },
  fail: (err) => {
    console.error('获取位置失败：', err);
    uni.showToast({
      title: '获取位置失败',
      icon: 'none'
    });
  }
});

🚀 使用地图功能

查看位置与导航

uni.openLocation 可以打开手机内置的地图应用（如高德地图、百度地图等），并显示指定位置，通常用于导航。

// 先获取当前位置
uni.getLocation({
  type: 'gcj02',
  success: (res) => {
    const latitude = res.latitude;
    const longitude = res.longitude;
    
    // 打开地图查看位置
    uni.openLocation({
      latitude: latitude,
      longitude: longitude,
      name: '目标位置名称', // 支付宝小程序必填
      address: '详细的地址说明', // 支付宝小程序必填
      success: function () {
        console.log('打开地图成功');
      }
    });
  }
});

添加复杂标记与图形

除了基础标记点，你还可以在地图上绘制多边形区域（polygons）。

// 在之前的 markers 数据基础上，添加 polygons 数据
const polygons = ref([
  {
    points: [ // 多边形顶点坐标数组
      {latitude: 39.90923, longitude: 116.397428},
      {latitude: 39.90920, longitude: 116.400428},
      {latitude: 39.90720, longitude: 116.400428},
      {latitude: 39.90720, longitude: 116.397428}
    ],
    strokeWidth: 2, // 描边宽度
    strokeColor: "#FF0000", // 描边颜色
    fillColor: "#FF000040" // 填充颜色
  }
]);

在 map 组件中绑定 :polygons="polygons" 即可显示。

💡 实战技巧与常见问题

坐标系是核心关键：务必牢记，<map> 组件和 uni.openLocation 使用的都是 GCJ-02 坐标系（国测局坐标）。在调用 uni.getLocation 获取用户位置时，必须指定 type: 'gcj02'，否则会出现位置偏移。
权限配置不可少：
- 在项目的 manifest.json → App模块配置 中，需要勾选 Maps(地图) 和 Geolocation(定位) 模块（App端）。
- 在微信小程序等平台的项目配置文件中，需要声明 requiredPrivateInfos 或 permissions 字段，包含 "getLocation"。
组件层级与样式限制：
- 请避免在 scroll-view、swiper、picker-view 中使用 <map> 组件，这可能会导致层级问题，地图组件会覆盖在其他视图之上。
- 在小程序和 App-vue 中，CSS 动画对 <map> 组件无效。
性能优化：
- 控制 markers 和 polygons 的数据量，过多的点会导致渲染性能下降。可以结合地图的视野变化事件，动态加载当前视野内的标记点。
- 对于静态路线，使用 polyline 替代密集的点标记，可以减轻 GPU 压力。