设备朝向

设备朝向用于在你的应用中获取手机当前正对的方向（真北方向角），常见用途包括地图箭头方向跟随、AR 指引、行进方向标识等。

本文档介绍设备朝向相关接口的使用方式与平台差异。

---

接口签名

class TencentLocationManager {
  Stream<TencentDeviceOrientation> get onOrientationChanged;
  Future<void> dismissIosHeadingCalibrationDisplay();
}

onOrientationChanged 是一个广播流，可被多次 listen。订阅后即可开始收到朝向变化事件，所有订阅者均取消订阅后不再产生事件，无需手动调用 start / stop 接口。

平台支持

平台	支持情况
Android	不支持，订阅 onOrientationChanged 不会抛异常但也不会收到事件
iOS	支持

如果你的应用只面向 Android，建议改用 Android 系统传感器 API 直接获取设备方向。

订阅朝向变化

final manager = TencentLocationManager();

final subscription = manager.onOrientationChanged.listen((orientation) {
  print('真北方向：${orientation.trueHeading}°');
});

// 不再需要时取消订阅，原生监听会自动停止：
// await subscription.cancel();

TencentDeviceOrientation 字段说明：

字段	类型	说明
trueHeading	double	真北方向角，范围 [0, 360)
magneticHeading	double?	磁北方向角（仅 iOS 提供）
accuracy	double?	精度（最大偏差度数，负数表示无效，仅 iOS 提供）
x / y / z	double?	地磁三轴原始值（仅 iOS 提供）
timestamp	int?	朝向数据的 Unix 毫秒时间戳

配置朝向相关参数

iOS 端可以通过定位请求的 iOS 扩展字段配置朝向更新过滤器：

final request = TencentLocationRequest.create()
  ..ios((ios) {
    // 朝向变化超过该值（度）时才回调，默认 1 度
    ios.headingFilter = 5;
    // 设备朝向参考方向，对应 CLDeviceOrientation 整数
    ios.headingOrientation = 1;
  });
await manager.startContinuousLocation(request);

headingFilter 只在 iOS 生效，Android 上配置后会被忽略。

关闭系统校准提示

iOS 在磁力计精度不足时，系统会自动弹出朝向校准提示面板。如果你不希望应用中出现这个面板，可以调用：

await manager.dismissIosHeadingCalibrationDisplay();

平台支持：

• Android：不支持，调用会抛出 TencentLocationError，错误码为 unsupportedOnThisPlatform

• iOS：支持

完整示例

import 'dart:async';

import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';

class HeadingService {
  final TencentLocationManager _manager = TencentLocationManager();
  StreamSubscription<TencentDeviceOrientation>? _subscription;

  void start() {
    _subscription = _manager.onOrientationChanged.listen((orientation) {
      // 用真北方向角更新地图箭头方向
      print('当前朝向：${orientation.trueHeading}°');
    });
  }

  Future<void> stop() async {
    await _subscription?.cancel();
    await _manager.dispose();
  }
}