最后更新时间:2025-03-26

---

基本定位功能

一、使用准备

腾讯地图SDK（iOS）封装了系统定位，方便用户使用，在使用定位功能前，需要向info.plist文件中添加定位权限：(以下二选一，两个都添加默认使用NSLocationWhenInUseUsageDescription）：

NSLocationWhenInUseUsageDescription：允许在前台使用时获取GPS的描述
NSLocationAlwaysUsageDescription：允许永久使用GPS的描述

二、开启定位

在创建mapView之后，可以通过setShowsUserLocation:方法来打开定位功能：

self.mapView.delegate = self;

// 开启定位
[self.mapView setShowsUserLocation:YES];

效果示例图如下：

三、定位模式

定位一共有地图跟踪三种模式，可以通过mapView的setUserTrackingMode:(QUserTrackingMode)mode方法来设置，支持的模式如下：

模式	说明
QUserTrackingModeNone	不追踪用户的location更新
QUserTrackingModeFollow	追踪用户的location更新
QUserTrackingModeFollowWithHeading	追踪用户的location与heading更新

注意：如果在QUserTrackingModeFollow和QUserTrackingModeFollowWithHeading模式下改变地图视野时，跟踪模式会转变为QUserTrackingModeNone，如果需要跟踪功能，则需要再次设置。

四、定位代理方法

开启定位功能之后，实现<QMapViewDelegate>协议中的方法来监听定位的回调，当定位成功时将获取到 QUserLocation 对象，该对象包含的属性如下表所示：

属性	说明
CLLocation *location	定位的位置信息
CLHeading *heading	指向信息

代理方法示例如下：

// <QMapViewDelegate>中的定位回调函数
- (void)mapViewWillStartLocatingUser:(QMapView *)mapView
{
    NSLog(@"%s", __FUNCTION__);
}

- (void)mapViewDidStopLocatingUser:(QMapView *)mapView
{
    NSLog(@"%s", __FUNCTION__);
}

/**
 * @brief 用户位置更新后，会调用此函数
 * @param mapView 地图View
 * @param userLocation 新的用户位置
 * @param fromHeading 是否为heading 变化触发，如果为location变化触发,则为NO
 */
- (void)mapView:(QMapView *)mapView didUpdateUserLocation:(QUserLocation *)userLocation fromHeading:(BOOL)fromHeading
{
    NSLog(@"%s fromHeading = %d, location = %@, heading = %@", __FUNCTION__, fromHeading, userLocation.location, userLocation.heading);
}

/**
 * @brief  定位失败后，会调用此函数
 * @param mapView 地图View
 * @param error 错误号，参考CLError.h中定义的错误号
 */
- (void)mapView:(QMapView *)mapView didFailToLocateUserWithError:(NSError *)error
{
    NSLog(@"%s error = %@", __FUNCTION__, error);
}

/**
 * @brief 定位时的userTrackingMode 改变时delegate调用此函数
 * @param mapView 地图View
 * @param mode QMUserTrackingMode
 * @param animated 是否有动画
 */
- (void)mapView:(QMapView *)mapView didChangeUserTrackingMode:(QUserTrackingMode)mode animated:(BOOL)animated
{
    NSLog(@"%s mode = %d, animated = %d", __FUNCTION__, mode, animated);
}

五、自定义定位蓝点样式

iOS地图SDK的定位功能除了默认样式的定位蓝点图标外，还支持通过 QUserLocationPresentation 来自定义样式的定位图标和定位圈的填充颜色。

QUserLocationPresentation 属性说明：

属性	说明
UIImage *icon	定位图标
UIColor *circleFillColor	定位圈的填充色
QUserLocationCompassPresentation *compass	定位圈罗盘
QNavigationGravityLine *gravityLine	定位圈红线

自定义蓝点样式示例代码如下：

// 创建定位样式对象
QUserLocationPresentation *presentation = [[QUserLocationPresentation alloc] init];
    
// 定位图标
presentation.icon = [UIImage imageNamed:@"test_location_1"];
// 精度圈颜色
presentation.circleFillColor = [[UIColor grayColor] colorWithAlphaComponent:0.3];
    
// 配置定位样式
[self.mapView configureUserLocationPresentation:presentation];

示例图如下：

六、定位图标回调

地图SDK在4.3.5版本增加了点击定位图标调用回调方法的功能，基本使用步骤如下：

1. 设置mapView的代理对象:

   self.mapView.delegate = self;
   

2. 实现点击定位图标的代理方法:

   - (void)mapView:(QMapView *)mapView didTapMyLocation:(CLLocationCoordinate2D)location {
       NSLog(@"my location is: (%f, %f)", location.latitude, location.longitude);
   }
   

当点击定位图标时，会调用上述方法，并将当前用户定位的坐标传入该方法中。

七、iOS14适配

地图SDK在4.4.0版本适配了iOS14系统，加入了模糊定位和精确定位的设置。

1、精确定位

i. 在Info.plist文件中添加NSLocationTemporaryUsageDescriptionDictionary，并配置键值对，如下图所示：

ii. 通过代码申请精确定位权限，注意代码需要判断系统是否为iOS14版本：

// iOS 14适配
if (@available(iOS 14.0, *)) {
    if (self.mapView.accuracyAuthorization == CLAccuracyAuthorizationReducedAccuracy) {
        // 精细定位权限申请
        [self.mapView requestTempPrecisedLocation:self.mapView purposeKey:@"purposeKey" completion:^(NSError *error) {
            if (error) {
                NSLog(@"%@", error);
            }
        }];
    }
}

iii. 精确定位效果如图所示：

2、模糊定位

如果用户没有授权精确定位的话，默认定位效果为模糊定位，效果如图所示：

3、定位权限更改回调

当定位权限、定位精度权限发生变化时，将调用如下代理方法：

/**
 * @brief 用户定位权限变更时会调用此接口
 * @param mapView 	地图View
 */
- (void)locationManagerDidChangeAuthorization:(QMapView *)mapView;