wx.getLocation参数有哪些？

wx.getLocation 是用于获取用户当前地理位置信息的核心方法，它有多个可选参数,可以让你更精确地控制定位行为和处理结果。

核心功能简介

wx.getLocation 会向用户发起授权请求，请求获取其地理位置，用户同意后，API 会返回一个包含经纬度、速度、精度等信息的对象。

基本用法示例：

wx.getLocation({
  type: 'gcj02',
  success: function(res) {
    const latitude = res.latitude; // 纬度
    const longitude = res.longitude; // 经度
    console.log(`当前位置：纬度 ${latitude}, 经度 ${longitude}`);
  },
  fail: function(err) {
    console.error('获取位置失败', err);
  }
});

参数详解

wx.getLocation 接收一个对象作为参数,该对象包含以下字段：

type (string)

说明：返回的坐标类型，用于指定地图服务商的坐标系。 类型：string 默认值：'wgs84' 可选值：

• 'wgs84'：返回 GPS 原始坐标，国际标准坐标系，适用于需要高精度的场景，如地图测绘、军事等。
• 'gcj02'：国测局坐标，也称为“火星坐标系”，是 Google Maps、高德地图、腾讯地图等国内地图服务商使用的坐标系。这是在小程序开发中最常用的选项,因为可以直接在这些地图上显示正确的位置。
• 'bd09'：百度坐标系，如果你的应用需要与百度地图集成,应该使用这个选项。

重要提示：type 参数只在 iOS 下生效，Android 系统会直接返回设备定位的原始坐标系，通常是 wgs84，但为了在地图上正确显示，建议统一使用 'gcj02'。

altitude (boolean)

说明：是否需要获取海拔高度。 类型：boolean 默认值：false 说明：设置为 true 时，在返回结果中会增加 altitude 字段，表示海拔高度（单位：米），注意，获取海拔需要设备硬件支持,且可能会增加定位时间和电量消耗。

isHighAccuracy (boolean)

说明：是否使用高精度定位。 类型：boolean 默认值：false 说明：

• 设置为 true 时，会使用更精确的定位方式（如 GPS、Wi-Fi、基站等综合定位），但会消耗更多电量,定位时间也可能更长。
• 设置为 false 时，可能会优先使用网络基站或 Wi-Fi 进行定位，速度更快,但精度较低。
• 在小程序中,这个参数的可用性取决于微信客户端和设备的支持情况。

success (function)

说明：接口调用成功的回调函数。 类型：function 参数：该回调函数会接收一个 res 对象，包含以下字段： | 字段 | 类型 | 说明 | | :--- | :--- | :--- | | latitude | number | 纬度，范围为 -90~90 | | longitude | number | 经度，范围为 -180~180 | | speed | number | 速度，单位 m/s | | accuracy | number | 位置的精度，单位米 | | altitude | number | 海拔高度，单位米（仅在 altitude 为 true 时返回） | | verticalAccuracy | number | 垂直精度，单位米（iOS 14.3 及以上版本支持） | | horizontalAccuracy | number | 水平精度，单位米（iOS 14.3 及以上版本支持） |

fail (function)

说明：接口调用失败的回调函数。 类型：function 参数：该回调函数会接收一个 err 对象，包含以下字段： | 字段 | 类型 | 说明 | | :--- | :--- | :--- | | errCode | number | 错误码 | | errMsg | string | 错误信息 |

常见错误码 (errCode) 及其含义：

• fail permission denied：用户拒绝授权地理位置。
• fail location service disable：设备没有打开定位服务。
• fail no valid location：无法获取有效位置信息。
• fail sdk init error：定位 SDK 初始化失败。

complete (function)

说明：接口调用结束的回调函数（无论成功或失败都会执行）。 类型：function 参数：如果成功，参数为 res 对象；如果失败，参数为 err 对象。

完整参数表示例

wx.getLocation({
  type: 'gcj02', // 使用火星坐标系，适配国内地图
  altitude: true, // 获取海拔高度
  isHighAccuracy: true, // 使用高精度定位
  success: (res) => {
    console.log('定位成功！', res);
    // res 包含：latitude, longitude, speed, accuracy, altitude 等
  },
  fail: (err) => {
    console.error('定位失败！', err);
    // err 包含：errCode, errMsg
    // 可以在这里处理用户拒绝授权等情况
  },
  complete: () => {
    console.log('定位请求结束');
  }
});

重要注意事项

1. 用户授权：首次调用 wx.getLocation 时，微信会自动弹窗向用户请求授权，如果用户拒绝，后续调用将直接失败，开发者应在 fail 回调中处理这种情况，并引导用户去“设置”中手动开启授权。

2. 配置文件 app.json：在获取位置前，必须在 app.json 文件中声明 permission 字段，向用户说明你的用途,否则将无法获取授权。

   {
     "pages": [
       "pages/index/index"
     ],
     "permission": {
       "scope.userLocation": {
         "desc": "你的位置信息将用于小程序位置接口的效果展示" // 声明用途
       }
     }
   }

   这个 desc 字段会在授权弹窗中显示给用户,清晰的描述可以提高用户授权率。

3. 坐标系选择：务必根据你使用的地图服务选择正确的 type。

   • 使用高德地图、腾讯地图、Google Maps：type: 'gcj02'
   • 使用百度地图：type: 'bd09'
   • 仅用于数据记录或需要国际标准坐标：type: 'wgs84'

4. iOS 与 Android 的差异：如前所述，type 在 iOS 下由微信转换，而在 Android 下由系统直接返回，为了最终在地图上显示一致，建议在调用地图 API 时，根据你的 wx.getLocation 的 type 选择对应的地图 SDK，如果你用 gcj02 坐标，就使用高德或腾讯地图的 SDK。