uni-halo/.agents/skills/uni-app/references/feature-location.md

name, description

name	description
Location Services	Geolocation, map operations, and location-based services

Location Services

Get Current Location

uni.getLocation

Get current geographic location.

uni.getLocation({
  type: 'wgs84', // wgs84/gcj02 (gcj02 for map display)
  altitude: false, // Include altitude
  geocode: false, // Include address info (App)
  highAccuracyExpireTime: 3000, // High accuracy timeout
  success: (res) => {
    console.log('Latitude:', res.latitude)
    console.log('Longitude:', res.longitude)
    console.log('Speed:', res.speed)
    console.log('Accuracy:', res.accuracy)
    // App only:
    console.log('Altitude:', res.altitude)
    console.log('Address:', res.address)
  },
  fail: (err) => {
    console.error('Location failed:', err)
  }
})

Response Properties:

Property	Type	Description
latitude	Number	Latitude
longitude	Number	Longitude
speed	Number	Speed (m/s)
accuracy	Number	Accuracy (meters)
altitude	Number	Altitude (meters)
verticalAccuracy	Number	Vertical accuracy
horizontalAccuracy	Number	Horizontal accuracy
address	Object	Address info (App)

uni.getFuzzyLocation (WeChat)

Get approximate location (better privacy, faster).

uni.getFuzzyLocation({
  type: 'wgs84',
  success: (res) => {
    console.log(res.latitude, res.longitude)
  }
})

Choose Location

uni.chooseLocation

Open map to select location.

uni.chooseLocation({
  latitude: 39.9,
  longitude: 116.4,
  keyword: 'restaurant',
  success: (res) => {
    console.log('Name:', res.name)
    console.log('Address:', res.address)
    console.log('Latitude:', res.latitude)
    console.log('Longitude:', res.longitude)
  }
})

Open Location

uni.openLocation

Open external map app.

uni.openLocation({
  latitude: 39.9,
  longitude: 116.4,
  name: 'Destination Name',
  address: 'Full address here',
  scale: 18
})

Location Change Monitoring

uni.startLocationUpdate

Start background location updates.

uni.startLocationUpdate({
  type: 'gcj02',
  success: () => {
    console.log('Location updates started')
  }
})

uni.startLocationUpdateBackground

Start background location (requires permission).

uni.startLocationUpdateBackground({
  type: 'gcj02',
  success: () => {
    console.log('Background location started')
  }
})

Listen for Location Changes

uni.onLocationChange((res) => {
  console.log('Location updated:', res.latitude, res.longitude)
})

// Stop listening
uni.offLocationChange(callback)

Stop Location Updates

uni.stopLocationUpdate({
  success: () => {
    console.log('Location updates stopped')
  }
})

Map Component

Basic Map

<template>
  <map
    id="myMap"
    style="width: 100%; height: 300px;"
    :latitude="latitude"
    :longitude="longitude"
    :scale="14"
    :markers="markers"
    :polyline="polyline"
    :circles="circles"
    :show-location="true"
    @markertap="onMarkerTap"
    @regionchange="onRegionChange"
  />
</template>

<script>
export default {
  data() {
    return {
      latitude: 39.909,
      longitude: 116.39742,
      markers: [{
        id: 1,
        latitude: 39.909,
        longitude: 116.39742,
        title: 'Marker 1',
        iconPath: '/static/marker.png',
        width: 30,
        height: 30,
        callout: {
          content: 'Hello',
          color: '#000',
          fontSize: 14,
          borderRadius: 5,
          padding: 10,
          display: 'BYCLICK'
        }
      }],
      polyline: [{
        points: [
          { latitude: 39.909, longitude: 116.39742 },
          { latitude: 39.91, longitude: 116.4 }
        ],
        color: '#FF0000',
        width: 2,
        dottedLine: false
      }],
      circles: [{
        latitude: 39.909,
        longitude: 116.39742,
        radius: 100,
        strokeWidth: 2,
        fillColor: '#FF000020'
      }]
    }
  }
}
</script>

Map Context Operations

export default {
  onReady() {
    this.mapContext = uni.createMapContext('myMap')
  },

  methods: {
    // Get center location
    getCenter() {
      this.mapContext.getCenterLocation({
        success: (res) => {
          console.log('Center:', res.latitude, res.longitude)
        }
      })
    },

    // Move to location
    moveToLocation() {
      this.mapContext.moveToLocation({
        latitude: 39.9,
        longitude: 116.4
      })
    },

    // Translate marker
    translateMarker() {
      this.mapContext.translateMarker({
        markerId: 1,
        destination: {
          latitude: 39.91,
          longitude: 116.41
        },
        autoRotate: true,
        rotate: 0,
        duration: 1000
      })
    },

    // Include points in view
    includePoints() {
      this.mapContext.includePoints({
        points: [
          { latitude: 39.9, longitude: 116.4 },
          { latitude: 39.91, longitude: 116.41 }
        ],
        padding: [10, 10, 10, 10]
      })
    },

    // Get region
    getRegion() {
      this.mapContext.getRegion({
        success: (res) => {
          console.log('Southwest:', res.southwest)
          console.log('Northeast:', res.northeast)
        }
      })
    },

    // Add markers
    addMarkers() {
      this.mapContext.addMarkers({
        markers: [{
          id: 2,
          latitude: 39.91,
          longitude: 116.41,
          title: 'New Marker'
        }],
        clear: false // Don't clear existing
      })
    },

    // Remove markers
    removeMarkers() {
      this.mapContext.removeMarkers({
        markerIds: [1, 2]
      })
    }
  }
}

Coordinate Systems

System	Description	Usage
WGS84	GPS coordinates	International standard
GCJ02	Mars coordinates	China national standard
BD09	Baidu coordinates	Baidu Map only

Note: For map display in China, use gcj02.

Permission Configuration

Mini-Program

Add to manifest.json:

{
  "mp-weixin": {
    "permission": {
      "scope.userLocation": {
        "desc": "Your location is needed to find nearby stores"
      }
    },
    "requiredPrivateInfos": [
      "getLocation",
      "chooseLocation"
    ]
  }
}

App (Android)

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" />"
        ]
      }
    }
  }
}

App (iOS)

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "Location is needed to find nearby stores",
          "NSLocationAlwaysUsageDescription": "Background location is needed for navigation"
        }
      }
    }
  }
}

Best Practices

Permission Handling

async function getLocationWithPermission() {
  try {
    // Check permission
    const setting = await uni.getSetting()
    if (!setting.authSetting['scope.userLocation']) {
      // Request permission
      await uni.authorize({ scope: 'scope.userLocation' })
    }

    // Get location
    const res = await uni.getLocation({ type: 'gcj02' })
    return res
  } catch (err) {
    if (err.errMsg.includes('auth deny')) {
      uni.showModal({
        title: 'Permission Required',
        content: 'Please enable location permission in settings',
        success: (res) => {
          if (res.confirm) {
            uni.openSetting()
          }
        }
      })
    }
    throw err
  }
}

Distance Calculation

function calculateDistance(lat1, lon1, lat2, lon2) {
  const R = 6371 // Earth's radius in km
  const dLat = (lat2 - lat1) * Math.PI / 180
  const dLon = (lon2 - lon1) * Math.PI / 180
  const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
            Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
            Math.sin(dLon/2) * Math.sin(dLon/2)
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
  return R * c // Distance in km
}