本页内容

Qt Sensors C++ 概述

传感器类型

设备上可能存在多种类型的传感器。Qt Sensors API 支持的类型未必都能在设备上使用,同时也可能存在一些未在Qt Sensors API 中定义的类型。可通过调用QSensor::sensorTypes() 函数来查询设备上可用的传感器类型。

有关内置传感器类型的列表,请参阅下文的“传感器类”部分。

常见约定

除非另有说明,Qt Sensors 采用右手笛卡尔坐标系。

具有右手笛卡尔坐标系中+x、+y和+z轴的装置

为了能够测量所有 6 个方向,会使用负值。

一种具有正负x、y和z轴的装置,其轴向延伸至所有六个方向

当涉及绕某轴旋转时,该旋转应表示为右手旋转。

带有弯曲箭头的装置,显示绕x、y和z轴的顺时针旋转

通常,传感器数据是以QScreen::nativeOrientation 为基准方向的,即设备以自然姿态握持时(通常为设备徽标朝上时)设备的顶部方向。如果要在屏幕上显示数值,可能需要对数值进行转换,使其与用户界面的方向一致。 某些传感器可能会将数据定义为与用户界面(UI)方向一致。相关说明将在该传感器的文档中注明。

该设备的侧视图、正视图、俯视图和底视图,并标注了设备顶部和底部的边缘

使用传感器

QSensor 的生命周期通常为:

  • 在栈或堆上创建QSensor 或其子类的实例。
  • 根据应用程序的要求进行配置。
  • 开始接收数值。
  • 应用程序使用传感器数据。
  • 停止接收值。

以下是在堆和栈上创建传感器的示例。

// On the heap (deleted when this object is deleted)
QAccelerometer *sensor = new QAccelerometer(this);

// On the stack (deleted when the current scope ends)
QOrientationSensor orient_sensor;

以通用方式访问传感器数据

处理传感器数据的首选方法是使用读取类。但是,有时可能无法这样做。例如,您可能正在将应用程序部署到一个具有新型传感器类型的设备上,但该设备没有描述读取类的 C++ 头文件。

得益于 Qt 的属性系统,您仍然可以访问传感器数据。要做到这一点,您需要了解以下三项信息:

  • 传感器类型。
  • 属性名称或索引。
  • 属性类型或可比类型。

例如,以下是一个访问加速度计属性的示例。该代码无需在编译时链接到QAccelerometer 或QAccelerometerReading 。

// start the sensor
QSensor sensor("QAccelerometer");
sensor.start();

// later
QSensorReading *reading = sensor.reading();
qreal x = reading->property("x").value<qreal>();
qreal y = reading->value(1).value<qreal>();

您也可以在运行时获取所有这些信息。

在运行时发现传感器并读取属性

有时在开发阶段可能无法得知可用的传感器。可以通过如下所示的方式查明有哪些传感器可用:

QList<QSensor*>mySensorList;
for(constQByteArray&type: QSensor::sensorTypes()) {
    qDebug() << "Found a sensor type:" << type;
   for(constQByteArray&标识符: QSensor::sensorsForType(type)) {
        qDebug() << "    " << "Found a sensor of that type:" << identifier;
        QSensor*sensor= newQSensor(type, this);
        sensor->setIdentifier(identifier);
        mySensorList.append(sensor);
    }
}

此外,还可以查询这些传感器的读数详情,如下所示:

for(QSensor*传感器 : mySensorList) {
    const intfirstProperty=QSensorReading::staticMetaObject.propertyOffset();
    // 若尚未调用 start(),则先连接后端
    if(!sensor->connectToBackend())
        continue;
    qDebug() << "Sensor" << sensor->identifier() << "reading properties:";
    QSensorReading*reading = sensor->reading();
    if(reading) {
        constQMetaObject*mo = 读数->metaObject();
        for(inti=firstProperty; i< mo->propertyCount();++i) {
            QByteArray name= mo->property(i).name();
            qDebug() << "    " << name << reading->property(name).toByteArray();
        }
    }
}

前端、后端

Qt Sensors API 包含前端(供应用程序开发人员使用)和后端(设备实现者在此编写代码以访问其硬件)。作为应用程序开发人员,您无需访问后端,但了解其工作原理可能会有所帮助。

来自应用程序的命令通过QSensor 传递,进而下发至设备插件。数据则通过QSensorReading 类返回。

应用程序、QSensor、QSensorBackend、QSensorReading 和设备插件之间的数据流

有关后端的更多信息,请参阅《Qt Sensors 后端》。

主要类

构成Qt Sensors API的主要类。

QSensor

表示单个硬件传感器

QSensorFilter

用于传感器变化异步通知的高效回调机制

QSensorReading

用于存储来自传感器的读数

读取类

访问传感器数据的最佳方式是通过以下其中一个类。

QAccelerometerReading

报告沿 X、Y 和 Z 轴的线性加速度

QAmbientLightReading

表示环境光传感器的一次读数

QAmbientTemperatureReading

存储环境温度的读数

QCompassReading

表示来自指南针的一次读数

QGyroscopeReading

表示陀螺仪传感器的一次读数

QHumidityReading

存储来自湿度传感器的读数

QLightReading

表示来自光传感器的单次读数

QMagnetometerReading

表示磁力计的一个读数

QOrientationReading

表示来自姿态传感器的单次读数

QPressureReading

存储来自压力传感器的读数

QProximityReading

表示接近传感器的一次读数

QRotationReading

表示旋转传感器的一次读数

QTiltReading

存储来自倾斜传感器的读数

传感器类

这些类提供了便捷的封装,可减少类型转换的需求。每个类都代表Qt Sensors API所识别的一种传感器类型。请注意,运行时可能会提供其他类型。有关更多信息,请参阅“传感器类型”。

QAccelerometer

围绕 QSensor 的便捷封装

QAmbientLightSensor

QSensor 的便捷封装类

QAmbientTemperatureSensor

QSensor 的便捷封装类

QCompass

QSensor 的便捷封装类

QGyroscope

QSensor 的便捷封装类

QHumiditySensor

QSensor 的便捷封装类

QLightSensor

QSensor 的便捷封装

QMagnetometer

QSensor 的便捷封装类

QOrientationSensor

QSensor 的便捷封装类

QPressureSensor

QSensor 的便捷封装类

QProximitySensor

QSensor 的便捷封装类

QRotationSensor

QSensor 的便捷封装类

QTiltSensor

QSensor 的便捷封装类

过滤器类

与传感器类类似,这些类提供了便捷的封装,减少了类型转换的需求。

QAccelerometerFilter

围绕 QSensorFilter 的便捷封装类

QAmbientLightFilter

QSensorFilter 的便捷封装类

QAmbientTemperatureFilter

QSensorFilter 的便捷封装类

QCompassFilter

QSensorFilter 的便捷封装类

QGyroscopeFilter

QSensorFilter 的便捷封装类

QHumidityFilter

QSensorFilter 的便捷封装类

QLightFilter

QSensorFilter 的便捷封装类

QMagnetometerFilter

QSensorFilter 的便捷封装类

QOrientationFilter

QSensorFilter 的便捷封装类

QPressureFilter

QSensorFilter 的便捷封装类

QProximityFilter

QSensorFilter 的便捷封装类

QRotationFilter

QSensorFilter 的便捷封装类

QTiltFilter

QSensorFilter 的便捷封装类

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.