位置服务

提供和用户位置相关的能力服务。

添加依赖库

1. 将解压后的 DMKLocationKit.framework 拖拽到工程目录。
2. 在 TARGETS -> Build Phases -> Link Binary With Libraries 中添加 DMKLocationKit.framework。
3. 在 TARGETS -> Build Settings -> Other Linker Flags 中增加 -ObjC。

前置条件

在调用定位能力前，请确保：

1. 已完成隐私协议声明与授权。
2. 已完成鉴权初始化（参考上一章节）。
3. 已申请并通过 iOS 定位权限（前台/后台按业务需要配置）。

1 持续定位

根据业务配置，持续回调定位点。

#import <DMKLocationKit/DMKLocationAdapter.h>
#import <DMKLocationKit/DMKLocationConfig.h>
#import <DMKLocationKit/DMKLocationAdapterDelegate.h>

@interface DemoController () <DMKLocationAdapterDelegate>
@end

@implementation DemoController

- (void)startLocation {
    // step 1: 配置定位参数
    DMKLocationConfig *config = [[DMKLocationConfig alloc] init];
    config.needNavMode = YES;
    config.distanceFilter = 0.0;
    config.needBackgroundUpdate = YES;
    config.desiredCoordinateType = DMKLocationCoordinateTypeGCJ02;

    // step 2: 注册监听
    NSError *error = nil;
    BOOL success = [[DMKLocationAdapter sharedInstance] registerWithDelegate:self
                                                               locationConfig:config
                                                                        error:&error];
    if (!success) {
        NSLog(@"register location failed: %@", error);
    }
}

// step 3: 实现回调
- (void)locationManagerDidUpdateLocation:(DMKLocation *)newLocation {
    NSLog(@"location: %@", newLocation.location);
}

- (void)locationManagerDidFailWithError:(NSError *)error {
    NSLog(@"location failed: %@", error);
}

// step 4: 不再需要定位时反注册
- (void)stopLocation {
    [[DMKLocationAdapter sharedInstance] unregisterWithDelegate:self error:NULL];
}

@end

定位配置项（DMKLocationConfig）

配置项	默认值	说明
distanceFilter	5.0	最小更新距离（米）
locationFrequency	0	最小更新时间间隔（秒），0 表示系统有更新就回调
needLocation	YES	是否需要定位回调
needNavMode	NO	是否导航模式，开启后定位精度按导航场景配置
needHeading	NO	是否需要朝向更新
needBackgroundUpdate	NO	是否需要后台持续定位
desiredCoordinateType	DMKLocationCoordinateTypeGCJ02	期望坐标系（GCJ02 / WGS84）
needBLELocation	NO	是否需要蓝牙定位
stationId	nil	蓝牙定位对应场站 ID

2 单次定位

DMKSharedSingleClient 提供异步单次定位能力。

#import <DMKLocationKit/DMKSharedSingleClient.h>

- (void)getLocationOnce {
    DMKSharedSingleClient *singleClient = [DMKSharedSingleClient sharedInstance];
    [singleClient requestLocationWithCompletionBlock:^(DMKLocation * _Nullable location,
                                                       NSError * _Nullable error) {
        if (location) {
            NSLog(@"GCJ02 once location: %@", location.location);
        } else {
            NSLog(@"GCJ02 once location failed: %@", error);
        }
    }];
}

- (void)getWGS84LocationOnce {
    DMKSharedSingleClient *singleClient = [DMKSharedSingleClient sharedInstance];
    [singleClient requestWGS84LocationWithCompletionBlock:^(DMKLocation * _Nullable location,
                                                            NSError * _Nullable error) {
        if (location) {
            NSLog(@"WGS84 once location: %@", location.location);
        } else {
            NSLog(@"WGS84 once location failed: %@", error);
        }
    }];
}

3 获取当前位置（缓存）

同步读取最近缓存位置（建议业务侧校验时间戳有效性）。

#import <DMKLocationKit/DMKLocationAdapter.h>

- (void)getCurrentLocation {
    DMKLocationAdapter *locationAdapter = [DMKLocationAdapter sharedInstance];

    DMKLocation *gcj02Location = [locationAdapter currentLocation];
    DMKLocation *wgs84Location = [locationAdapter currentWGS84Location];

    NSArray<DMKLocation *> *latestGCJ02 = [locationAdapter latestLocationsWithCount:5];
    NSArray<DMKLocation *> *latestWGS84 = [locationAdapter latestWGS84LocationsWithCount:5];

    NSLog(@"gcj02=%@, wgs84=%@, latestGCJ02=%@, latestWGS84=%@",
          gcj02Location, wgs84Location, latestGCJ02, latestWGS84);
}

4 定位结果说明（DMKLocation）

持续定位和单次定位返回同一数据模型 DMKLocation。

字段	类型	说明
locationID	NSString *	定位数据唯一标识
providerType	DMKLocationProviderType	定位来源提供方
sourceType	DMKLocationSourceType	定位精度来源
coordinateType	DMKLocationCoordinateType	坐标系类型
sourceTypeStr	NSString *	来源字符串（如 ios_gps、ios_wifi）
location	CLLocation *	原始系统定位对象（经纬度、精度、速度等）
localTime	NSDate *	SDK 收到该点时的本地时间
headingDegrees	CGFloat	收到定位更新时设备朝向
floorID	NSString *	楼层 ID
bleModels	NSArray<DMKBleNaviModel *> *	蓝牙定位参与计算信息

DMKLocationProviderType

枚举值	说明
DMKLocationProviderOther	其他来源
DMKLocationProviderIOS	iOS 系统定位
DMKLocationProviderFLP	FLP 推算
DMKLocationProviderDIDIWIFI	定位服务网络计算
DMKLocationProviderBLE	蓝牙信标提供

DMKLocationSourceType

枚举值	说明
DMKLocationSourceTypeUnknow	未知
DMKLocationSourceTypeGPS	GPS 定位
DMKLocationSourceTypeWiFi	Wi-Fi 定位
DMKLocationSourceTypeCell	基站定位
DMKLocationSourceTypeBLE	蓝牙信标

5 智能定位（FLP）

智能定位结合系统定位点、加速度计、陀螺仪和路网信息，输出连续性更好、精度更高的定位点。

权限说明

在 App 权限说明中增加 Motion 文案：

• Privacy - Motion Usage Description

#import <DMKLocationKit/DMKFLPAdapter.h>

- (void)startFLPLocation {
    DMKFLPAdapter *adapter = [DMKFLPAdapter mainAdapter];
    [adapter startFLPUpdatingLocationWithDelegate:self];
}

- (void)flpAdapter:(DMKFLPAdapter *)adapter
 didUpdateLocation:(DMKFLPLocationModel *)flpLocationModel {
    // 智能定位点使用代码
}

- (void)stopFLPLocation {
    DMKFLPAdapter *adapter = [DMKFLPAdapter mainAdapter];
    [adapter updateNaviStop:1];
    [adapter stopFLPUpdatingLocationWithDelegate:self];
}

6 逆地理

基于用户位置获取所在城市、是否境内/境外等信息。

#import <DMKLocationKit/DMKLocationRGeoAdapter.h>

- (BOOL)isUserAbroad {
    BOOL isAbroad = [DMKLocationRGeoAdapter sharedInstance].currentCityModel.isAbroad;
    return isAbroad;
}

调用时序与注意事项

1. 推荐顺序：配置参数 -> 注册监听 -> 处理回调 -> 反注册监听。
2. registerWithDelegate:locationConfig:error: 返回 NO 时请检查错误信息。
3. currentLocation/currentWGS84Location 为缓存值，不保证实时，建议结合时间戳判断可用性。
4. 页面销毁或不再需要定位时务必反注册，避免不必要的资源开销。
5. 需要方向信息时，配置 needHeading = YES 并实现 locationManagerDidUpdateHeading: 回调。