HarmonyOS开发：传感器框架与@ohos.sensor全解析

核心要点：本文系统解析HarmonyOS传感器框架架构、@ohos.sensor模块API体系、传感器类型与能力查询、权限模型及生命周期管理，为后续加速度计、陀螺仪、磁力计等专项开发奠定基础。

一、背景与动机

移动设备的传感器是连接物理世界与数字世界的桥梁。从计步器到导航，从游戏操控到健康监测，传感器数据驱动着无数核心应用场景。HarmonyOS作为全场景分布式操作系统，对传感器能力进行了统一抽象与框架化封装，通过@ohos.sensor模块提供标准化的传感器访问接口。

然而，传感器开发并非简单的"调用API→获取数据"。开发者需要理解：

• 硬件差异：不同设备搭载的传感器种类、精度、采样率各不相同
• 权限管控：传感器涉及用户隐私，需严格遵循权限申请规范
• 功耗优化：不当的订阅策略会导致设备发热、电量骤降
• 数据质量：原始传感器数据包含噪声，需要滤波与校准

本文将从框架架构出发，全面解析@ohos.sensor模块的设计哲学与使用方法。

二、核心原理

2.1 HarmonyOS传感器框架架构

HarmonyOS传感器框架采用分层架构设计，从底层硬件到上层应用形成完整的数据通路：

flowchart TB
    subgraph APP["应用层"]
        A1["ArkTS应用"]
        A2["@ohos.sensor API"]
    end

    subgraph FWK["框架层"]
        B1["Sensor Service<br/>传感器服务"]
        B2["Sensor Manager<br/>传感器管理器"]
        B3["Sensor Client<br/>客户端代理"]
    end

    subgraph HAL["硬件抽象层"]
        C1["Sensor HAL"]
        C2["传感器驱动"]
    end

    subgraph HW["硬件层"]
        D1["加速度计"]
        D2["陀螺仪"]
        D3["磁力计"]
        D4["气压计"]
        D5["..."]
    end

    A1 --> A2
    A2 --> B3
    B3 --> B2
    B2 --> B1
    B1 --> C1
    C1 --> C2
    C2 --> D1 & D2 & D3 & D4 & D5

    classDef appStyle fill:#4A90D9,stroke:#2C5F8A,color:#fff,font-weight:bold
    classDef fwkStyle fill:#50C878,stroke:#2E8B57,color:#fff,font-weight:bold
    classDef halStyle fill:#FF8C42,stroke:#CC6B30,color:#fff,font-weight:bold
    classDef hwStyle fill:#9B59B6,stroke:#7D3C98,color:#fff,font-weight:bold

    class A1,A2 appStyle
    class B1,B2,B3 fwkStyle
    class C1,C2 halStyle
    class D1,D2,D3,D4,D5 hwStyle

架构分层解读：

2.2 传感器类型体系

HarmonyOS定义了完整的传感器类型枚举（SensorType），覆盖运动、环境、位置三大类别：

mindmap
  root((传感器类型))
    运动传感器
      ACCELEROMETER 加速度计
      GYROSCOPE 陀螺仪
      GRAVITY 重力传感器
      LINEAR_ACCELERATION 线性加速度
      ROTATION_VECTOR 旋转矢量
      SIGNIFICANT_MOTION 显著运动
    环境传感器
      AMBIENT_TEMP 环境温度
      HUMIDITY 湿度
      BAROMETER 气压计
      LIGHT 环境光
    位置传感器
      MAGNETOMETER 磁力计
      MAGNETOMETER_UNCALIBRATED 未校准磁力计
      PROXIMITY 接近光
      ORIENTATION 方向传感器
      HEART_RATE 心率
      PEDOMETER 计步器

2.3 @ohos.sensor模块API总览

@ohos.sensor模块提供了以下核心API族：

三、代码实战

3.1 查询设备传感器能力

在开发传感器功能前，首要任务是查询当前设备支持哪些传感器：

// sensor_capability.ets
// 功能：查询设备传感器能力列表
import sensor from '@ohos.sensor';
import { BusinessError } from '@ohos.base';

interface SensorInfo {
  sensorTypeId: number;    // 传感器类型ID
  sensorName: string;      // 传感器名称
  vendorName: string;      // 厂商名称
  firmwareVersion: string; // 固件版本
  hardwareVersion: string; // 硬件版本
  maxRange: number;        // 最大量程
  resolution: number;      // 分辨率
  power: number;           // 功耗(mA)
}

@Entry
@Component
struct SensorCapabilityPage {
  @State sensorList: SensorInfo[] = [];
  @State statusMsg: string = '正在查询...';

  aboutToAppear() {
    this.querySensorList();
  }

  // 功能：获取设备支持的传感器列表
  querySensorList() {
    try {
      const sensors = sensor.getSensorList();
      this.sensorList = sensors.map(s => ({
        sensorTypeId: s.sensorTypeId,
        sensorName: s.sensorName || '未知',
        vendorName: s.vendorName || '未知',
        firmwareVersion: s.firmwareVersion || '-',
        hardwareVersion: s.hardwareVersion || '-',
        maxRange: s.maxRange ?? 0,
        resolution: s.resolution ?? 0,
        power: s.power ?? 0
      }));
      this.statusMsg = `共发现 ${this.sensorList.length} 个传感器`;
    } catch (error) {
      const err = error as BusinessError;
      this.statusMsg = `查询失败: ${err.code} - ${err.message}`;
    }
  }

  build() {
    Column() {
      Text('设备传感器能力查询')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 16 })

      Text(this.statusMsg)
        .fontSize(16)
        .fontColor('#50C878')
        .margin({ bottom: 12 })

      List() {
        ForEach(this.sensorList, (item: SensorInfo, index: number) => {
          ListItem() {
            this.SensorCard(item, index)
          }
        }, (item: SensorInfo, index: number) => `${index}`)
      }
      .width('100%')
      .layoutWeight(1)
    }
    .width('100%')
    .height('100%')
    .padding(16)
  }

  @Builder
  SensorCard(info: SensorInfo, index: number) {
    Column() {
      Row() {
        Text(`传感器 #${index + 1}`)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
        Text(this.getSensorTypeName(info.sensorTypeId))
          .fontSize(14)
          .fontColor('#4A90D9')
          .margin({ left: 8 })
      }

      Grid() {
        GridItem() { this.InfoItem('名称', info.sensorName) }
        GridItem() { this.InfoItem('厂商', info.vendorName) }
        GridItem() { this.InfoItem('量程', `${info.maxRange}`) }
        GridItem() { this.InfoItem('分辨率', `${info.resolution}`) }
        GridItem() { this.InfoItem('功耗', `${info.power} mA`) }
        GridItem() { this.InfoItem('固件', info.firmwareVersion) }
      }
      .columnsTemplate('1fr 1fr')
      .rowsGap(8)
      .columnsGap(8)
      .margin({ top: 8 })
    }
    .width('100%')
    .padding(16)
    .borderRadius(12)
    .backgroundColor('#1a1a2e')
    .margin({ bottom: 12 })
  }

  @Builder
  InfoItem(label: string, value: string) {
    Column() {
      Text(label)
        .fontSize(12)
        .fontColor('#888888')
      Text(value)
        .fontSize(14)
        .fontColor('#ffffff')
        .maxLines(1)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .alignItems(HorizontalAlign.Start)
  }

  // 功能：将传感器类型ID映射为可读名称
  getSensorTypeName(typeId: number): string {
    const typeMap: Record<number, string> = {
      1: '加速度计', 2: '陀螺仪', 5: '磁力计',
      6: '气压计', 7: '环境光', 8: '接近光',
      9: '湿度', 10: '环境温度', 15: '重力',
      16: '线性加速度', 17: '旋转矢量', 18: '方向',
      20: '心率', 23: '计步器', 24: '显著运动'
    };
    return typeMap[typeId] || `未知类型(${typeId})`;
  }
}

3.2 传感器权限声明与动态申请

传感器涉及用户隐私数据，必须在module.json5中声明权限，并在运行时动态申请：

// sensor_permission.ets
// 功能：传感器权限声明与动态申请工具类
import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
import { BusinessError } from '@ohos.base';
import common from '@ohos.app.ability.common';

// 需要在 module.json5 中声明的权限：
// {
//   "name": "ohos.permission.ACCELEROMETER",
//   "reason": "$string:accelerometer_reason",
//   "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
// }
// {
//   "name": "ohos.permission.GYROSCOPE",
//   "reason": "$string:gyroscope_reason",
//   "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
// }
// {
//   "name": "ohos.permission.ACTIVITY_MOTION",
//   "reason": "$string:activity_motion_reason",
//   "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
// }

export class SensorPermissionManager {
  private context: common.UIAbilityContext;

  constructor(context: common.UIAbilityContext) {
    this.context = context;
  }

  // 功能：检查权限是否已授予
  async checkPermission(permission: Permissions): Promise<boolean> {
    try {
      const atManager = abilityAccessCtrl.createAtManager();
      const grantStatus = await atManager.checkAccessToken(
        this.context.applicationInfo.accessTokenId,
        permission
      );
      return grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[SensorPerm] 检查权限失败: ${err.code} - ${err.message}`);
      return false;
    }
  }

  // 功能：请求传感器权限
  async requestPermissions(permissions: Permissions[]): Promise<Map<Permissions, boolean>> {
    const result = new Map<Permissions, boolean>();

    // 先检查哪些权限尚未授予
    const ungranted: Permissions[] = [];
    for (const perm of permissions) {
      const granted = await this.checkPermission(perm);
      result.set(perm, granted);
      if (!granted) {
        ungranted.push(perm);
      }
    }

    // 对未授予的权限发起动态申请
    if (ungranted.length > 0) {
      try {
        const atManager = abilityAccessCtrl.createAtManager();
        const response = await atManager.requestPermissionsFromUser(
          this.context,
          ungranted
        );

        // 处理申请结果
        for (let i = 0; i < response.authResults.length; i++) {
          const perm = ungranted[i];
          const granted = response.authResults[i] === 0; // 0表示授权成功
          result.set(perm, granted);
          console.info(`[SensorPerm] ${perm}: ${granted ? '已授权' : '被拒绝'}`);
        }
      } catch (error) {
        const err = error as BusinessError;
        console.error(`[SensorPerm] 请求权限失败: ${err.code} - ${err.message}`);
      }
    }

    return result;
  }

  // 功能：批量检查传感器相关权限
  async checkAllSensorPermissions(): Promise<boolean> {
    const sensorPerms: Permissions[] = [
      'ohos.permission.ACCELEROMETER',
      'ohos.permission.GYROSCOPE',
      'ohos.permission.ACTIVITY_MOTION'
    ];

    const results = await this.requestPermissions(sensorPerms);
    let allGranted = true;
    results.forEach((granted, perm) => {
      if (!granted) {
        console.warn(`[SensorPerm] 权限未授予: ${perm}`);
        allGranted = false;
      }
    });
    return allGranted;
  }
}

3.3 传感器数据订阅基础模板

以下是一个通用的传感器数据订阅模板，展示完整的订阅→使用→取消订阅生命周期：

// sensor_subscribe_template.ets
// 功能：传感器数据订阅通用模板
import sensor from '@ohos.sensor';
import { BusinessError } from '@ohos.base';

// 传感器数据回调类型定义
interface SensorData {
  x: number;
  y: number;
  z: number;
  timestamp: number;
}

@Entry
@Component
struct SensorSubscribeTemplate {
  @State sensorData: SensorData = { x: 0, y: 0, z: 0, timestamp: 0 };
  @State isSubscribed: boolean = false;
  @State dataCount: number = 0;
  @State errorMsg: string = '';

  private callback: (data: sensor.AccelerometerResponse) => void = () => {};

  aboutToDisappear() {
    // 组件销毁时务必取消订阅，防止内存泄漏
    this.unsubscribeSensor();
  }

  // 功能：订阅加速度计数据
  subscribeSensor() {
    try {
      // 定义数据回调函数
      this.callback = (data: sensor.AccelerometerResponse) => {
        this.sensorData = {
          x: parseFloat(data.x.toFixed(4)),
          y: parseFloat(data.y.toFixed(4)),
          z: parseFloat(data.z.toFixed(4)),
          timestamp: data.timestamp
        };
        this.dataCount++;
      };

      // 使用 on 方法订阅传感器数据
      // interval 参数控制采样频率：
      // - 'game' : 20000μs (50Hz)  适合游戏
      // - 'ui'   : 60000μs (16Hz)  适合UI交互
      // - 'normal': 200000μs (5Hz) 适合普通应用
      sensor.on(sensor.SensorType.ACCELEROMETER, this.callback, {
        interval: 'game'
      });

      this.isSubscribed = true;
      this.errorMsg = '';
      console.info('[SensorTemplate] 加速度计订阅成功');
    } catch (error) {
      const err = error as BusinessError;
      this.errorMsg = `订阅失败: ${err.code} - ${err.message}`;
      console.error(`[SensorTemplate] ${this.errorMsg}`);
    }
  }

  // 功能：取消订阅传感器数据
  unsubscribeSensor() {
    if (!this.isSubscribed) return;

    try {
      // 使用 off 方法取消订阅，传入相同的回调引用
      sensor.off(sensor.SensorType.ACCELEROMETER, this.callback);
      this.isSubscribed = false;
      console.info('[SensorTemplate] 加速度计取消订阅成功');
    } catch (error) {
      const err = error as BusinessError;
      this.errorMsg = `取消订阅失败: ${err.code} - ${err.message}`;
      console.error(`[SensorTemplate] ${this.errorMsg}`);
    }
  }

  // 功能：单次获取传感器数据
  getSensorOnce() {
    try {
      sensor.once(sensor.SensorType.ACCELEROMETER, (data: sensor.AccelerometerResponse) => {
        this.sensorData = {
          x: parseFloat(data.x.toFixed(4)),
          y: parseFloat(data.y.toFixed(4)),
          z: parseFloat(data.z.toFixed(4)),
          timestamp: data.timestamp
        };
        this.dataCount++;
        console.info('[SensorTemplate] 单次获取成功');
      });
    } catch (error) {
      const err = error as BusinessError;
      this.errorMsg = `单次获取失败: ${err.code} - ${err.message}`;
    }
  }

  build() {
    Column() {
      // 标题栏
      Text('传感器订阅模板')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      // 数据展示卡片
      Column() {
        Text('加速度计数据')
          .fontSize(18)
          .fontWeight(FontWeight.Medium)
          .margin({ bottom: 12 })

        Row() {
          this.DataAxis('X', this.sensorData.x, '#FF6B6B')
          this.DataAxis('Y', this.sensorData.y, '#4ECDC4')
          this.DataAxis('Z', this.sensorData.z, '#45B7D1')
        }
        .width('100%')
        .justifyContent(FlexAlign.SpaceAround)

        Text(`数据包计数: ${this.dataCount}`)
          .fontSize(14)
          .fontColor('#888888')
          .margin({ top: 8 })

        Text(`时间戳: ${this.sensorData.timestamp}`)
          .fontSize(12)
          .fontColor('#666666')
          .margin({ top: 4 })
      }
      .width('100%')
      .padding(20)
      .borderRadius(16)
      .backgroundColor('#1a1a2e')
      .margin({ bottom: 20 })

      // 错误信息
      if (this.errorMsg) {
        Text(this.errorMsg)
          .fontSize(14)
          .fontColor('#FF6B6B')
          .margin({ bottom: 12 })
      }

      // 操作按钮
      Row() {
        Button(this.isSubscribed ? '取消订阅' : '开始订阅')
          .backgroundColor(this.isSubscribed ? '#FF6B6B' : '#50C878')
          .fontColor('#ffffff')
          .onClick(() => {
            if (this.isSubscribed) {
              this.unsubscribeSensor();
            } else {
              this.subscribeSensor();
            }
          })
          .width('40%')

        Button('单次获取')
          .backgroundColor('#4A90D9')
          .fontColor('#ffffff')
          .onClick(() => this.getSensorOnce())
          .width('40%')
          .margin({ left: 12 })
      }
      .width('100%')
      .justifyContent(FlexAlign.Center)
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#0d0d1a')
  }

  @Builder
  DataAxis(label: string, value: number, color: string) {
    Column() {
      Text(label)
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
        .fontColor(color)
      Text(`${value}`)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .fontColor('#ffffff')
        .margin({ top: 4 })
      Text('m/s²')
        .fontSize(12)
        .fontColor('#888888')
    }
    .alignItems(HorizontalAlign.Center)
  }
}

3.4 传感器采样间隔参数详解

// sensor_interval_config.ets
// 功能：传感器采样间隔配置与性能影响分析
import sensor from '@ohos.sensor';

// 采样间隔枚举值与实际频率对照表
interface IntervalConfig {
  name: string;       // 配置名称
  interval: number;   // 微秒(μs)
  frequency: number;  // 赫兹(Hz)
  useCase: string;    // 适用场景
  powerImpact: string; // 功耗影响
}

const INTERVAL_CONFIGS: IntervalConfig[] = [
  { name: '极快', interval: 5000,   frequency: 200, useCase: '高速运动追踪', powerImpact: '极高' },
  { name: '游戏', interval: 20000,  frequency: 50,  useCase: '游戏操控',     powerImpact: '高' },
  { name: 'UI',   interval: 60000,  frequency: 16,  useCase: 'UI交互动画',   powerImpact: '中' },
  { name: '正常', interval: 200000, frequency: 5,   useCase: '日常监测',     powerImpact: '低' },
  { name: '省电', interval: 1000000,frequency: 1,   useCase: '后台计步',     powerImpact: '极低' },
];

// 功能：根据业务场景选择最优采样间隔
function selectOptimalInterval(scenario: 'game' | 'ui' | 'normal' | 'power_save'): number {
  const scenarioMap: Record<string, number> = {
    'game':       20000,   // 50Hz - 游戏需要低延迟
    'ui':         60000,   // 16Hz - UI刷新足够流畅
    'normal':     200000,  // 5Hz  - 常规监测
    'power_save': 1000000, // 1Hz  - 省电模式
  };
  return scenarioMap[scenario] ?? 200000;
}

// 功能：带自定义间隔的传感器订阅
function subscribeWithInterval(
  type: sensor.SensorType,
  intervalUs: number,
  callback: (data: sensor.AccelerometerResponse) => void
): void {
  try {
    sensor.on(type, callback, { interval: intervalUs });
    console.info(`[IntervalConfig] 订阅成功，间隔: ${intervalUs}μs (${1000000 / intervalUs}Hz)`);
  } catch (error) {
    console.error(`[IntervalConfig] 订阅失败: ${JSON.stringify(error)}`);
  }
}

四、踩坑与注意事项

4.1 常见错误码与解决方案

4.2 回调引用陷阱

// ❌ 错误写法：每次渲染创建新的回调函数，导致off()无法匹配
sensor.on(sensor.SensorType.ACCELEROMETER, (data) => {
  // 匿名函数，每次都是新引用
});
sensor.off(sensor.SensorType.ACCELEROMETER, (data) => {
  // 这是一个新的匿名函数，无法取消之前的订阅！
});

// ✅ 正确写法：保存回调引用，确保on/off使用同一引用
private accelCallback = (data: sensor.AccelerometerResponse) => {
  // 处理数据
};
sensor.on(sensor.SensorType.ACCELEROMETER, this.accelCallback);
sensor.off(sensor.SensorType.ACCELEROMETER, this.accelCallback);

4.3 生命周期管理要点

1. 组件销毁时必须取消订阅：在aboutToDisappear()中调用off()
2. 页面隐藏时暂停订阅：在onPageHide()中取消订阅，onPageShow()中恢复
3. 避免重复订阅：订阅前检查订阅状态，防止多次on()导致回调叠加
4. 后台运行限制：HarmonyOS后台传感器订阅会被系统限制，需申请长驻后台权限

4.4 多传感器并发注意事项

• 同时订阅多个传感器时，各传感器回调独立触发，时间戳可能不对齐
• 高频订阅多个传感器会显著增加功耗，建议按需开启
• 某些传感器共享硬件资源，同时订阅可能互相干扰（如加速度计与线性加速度）

五、HarmonyOS 6适配

5.1 API变更

HarmonyOS 6对传感器模块进行了以下优化：

5.2 适配代码示例

// harmonyos6_adapter.ets
// 功能：HarmonyOS 6传感器API适配层
import sensor from '@ohos.sensor';

// 功能：兼容性传感器订阅封装
async function subscribeSensorCompat(
  type: sensor.SensorType,
  callback: (data: sensor.AccelerometerResponse) => void,
  interval: number = 20000
): Promise<boolean> {
  try {
    // HarmonyOS 6新增：检查传感器是否可用
    if (sensor.isSensorAvailable && !sensor.isSensorAvailable(type)) {
      console.warn('[HOS6Adapter] 传感器不可用，跳过订阅');
      return false;
    }

    // 标准订阅方式（兼容HOS5和HOS6）
    sensor.on(type, callback, { interval });

    // HarmonyOS 6新增：设置数据批处理模式
    // 减少回调频率，降低CPU唤醒次数
    if (sensor.setBatchInterval) {
      sensor.setBatchInterval(type, 100000); // 100ms批处理间隔
      console.info('[HOS6Adapter] 已启用批处理模式');
    }

    return true;
  } catch (error) {
    console.error(`[HOS6Adapter] 订阅失败: ${JSON.stringify(error)}`);
    return false;
  }
}

六、总结

本文系统解析了HarmonyOS传感器框架的核心架构与@ohos.sensor模块的使用方法：

flowchart LR
    A[传感器开发流程] --> B[查询能力<br/>getSensorList]
    B --> C[声明权限<br/>module.json5]
    C --> D[动态申请<br/>requestPermissions]
    D --> E[订阅数据<br/>sensor.on]
    E --> F[处理数据<br/>callback]
    F --> G{是否继续?}
    G -->|是| F
    G -->|否| H[取消订阅<br/>sensor.off]
    H --> I[释放资源]

    classDef stepStyle fill:#4A90D9,stroke:#2C5F8A,color:#fff,font-weight:bold
    classDef decisionStyle fill:#FF8C42,stroke:#CC6B30,color:#fff,font-weight:bold
    classDef endStyle fill:#50C878,stroke:#2E8B57,color:#fff,font-weight:bold

    class A,B,C,D,E stepStyle
    class G decisionStyle
    class F,H,I endStyle

核心要点回顾：

1. 分层架构：理解应用层→框架层→HAL→硬件层的数据通路，有助于定位问题层级
2. 能力查询先行：开发前务必调用getSensorList()确认设备传感器支持情况
3. 权限三步走：声明→申请→检查，缺一不可
4. 回调引用一致性：on()和off()必须使用同一个回调函数引用
5. 生命周期绑定：订阅与组件/页面生命周期绑定，防止泄漏
6. 采样率选择：根据业务场景选择合适的interval，平衡精度与功耗
7. HarmonyOS 6适配：关注批处理、自适应采样等新特性

下一篇将深入加速度计的物理原理与运动感知算法实现，敬请期待。