Back to Qt.io
Contact Us Blog Download Qt
本页内容

QNearFieldManager Class

QNearFieldManager 类提供了访问 NFC 事件通知的功能。更多内容...

头文件： #include <QNearFieldManager>
CMake： find_package(Qt6 REQUIRED COMPONENTS Nfc)
target_link_libraries(mytarget PRIVATE Qt6::Nfc)
qmake： QT += nfc
继承自： QObject

公共类型

enum class AdapterState { Offline, TurningOn, Online, TurningOff }

公共函数

QNearFieldManager(QObject *parent = nullptr)
virtual ~QNearFieldManager()
(since 6.2) bool isEnabled() const
bool isSupported(QNearFieldTarget::AccessMethod accessMethod = QNearFieldTarget::AnyAccess) const
(since 6.2) void setUserInformation(const QString &message)
bool startTargetDetection(QNearFieldTarget::AccessMethod accessMethod)
void stopTargetDetection(const QString &errorMessage = QString())

信号

void adapterStateChanged(QNearFieldManager::AdapterState state)
void targetDetected(QNearFieldTarget *target)
(since 6.2) void targetDetectionStopped()
void targetLost(QNearFieldTarget *target)

详细说明

NFC Forum 设备支持两种通信模式。第一种模式是点对点通信，用于两个 NFC Forum 设备之间的通信。第二种模式是主从通信，用于 NFC Forum 设备与 NFC Forum 标签或非接触式卡之间的通信。当目标设备进入通信范围时，会发出targetDetected() 信号。 可从连接此信号的插槽发起通信。

在主从通信中，NFC Forum 设备通常作为主设备运行。部分设备还能够作为从设备运行，即所谓的“卡模拟模式”。在此模式下，本地 NFC 设备将模拟 NFC Forum 标签或非接触式卡片。

应用程序可连接到targetDetected()和targetLost()信号，以便在NFC论坛标签进入或离开近场时收到通知。在发出这些信号之前，必须使用startTargetDetection()函数启动目标检测。 可通过stopTargetDetection()函数停止目标检测。当不再需要该目标时，应将其删除，否则可能会阻止其他应用程序访问该目标。

Linux 上的 NFC

Linux NFC 项目提供了支持 Linux 平台 NFC 的软件。neard 守护进程将允许通过 DBus 接口访问受支持的硬件。QtNfc 需要 neard 0.14 版本，该版本可通过源代码编译或使用相应的 Linux 软件包管理器进行安装。目前并非所有 API 功能都受到支持。 要使QtNfc 能够访问 DBus 接口，neard 守护进程必须处于运行状态。若遇到问题，可通过启用“qt.nfc.neard”的分类日志记录来获取调试输出。

成员类型文档

enum class QNearFieldManager::AdapterState

此枚举描述了NFC适配器可能处于的不同状态。

常量值描述
QNearFieldManager::AdapterState::Offline1NFC适配器处于离线状态。
QNearFieldManager::AdapterState::TurningOn2NFC 适配器正在开启。
QNearFieldManager::AdapterState::Online3NFC适配器已联机。
QNearFieldManager::AdapterState::TurningOff4NFC 适配器正在关闭。

成员函数文档

[explicit] QNearFieldManager::QNearFieldManager(QObject *parent = nullptr)

使用 `parent` 创建一个新的近场管理器。

[virtual noexcept] QNearFieldManager::~QNearFieldManager()

摧毁近场管理器。

[signal] void QNearFieldManager::adapterStateChanged(QNearFieldManager::AdapterState state)

每当NFC适配器的state 发生变化时，都会发出此信号。

注意：目前 ，该信号仅在 Android 系统上触发。

[since 6.2] bool QNearFieldManager::isEnabled() const

如果设备具有 NFC 适配器且已开启，则返回true ；否则返回false 。

该函数在 Qt 6.2 中引入。

另请参阅 isSupported()。

bool QNearFieldManager::isSupported(QNearFieldTarget::AccessMethod accessMethod = QNearFieldTarget::AnyAccess) const

如果底层设备具有NFC适配器，则返回true ；否则返回false 。如果提供了accessMethod ，则该函数仅在NFC适配器支持给定的accessMethod 时，才返回true 。

另请参阅 isEnabled()。

[since 6.2] void QNearFieldManager::setUserInformation(const QString &message)

设置系统向用户显示的消息。如果目标检测正在运行，message 将立即更新，并可作为进度消息使用。 在调用 `startTargetDetection()` 且未出现错误消息之前设置的最后一条消息将用作成功消息。如果目标检测未运行，则在下次检测开始时，将使用 `message ` 作为初始消息。默认情况下，不会向用户显示任何消息。

注意：目前， 此函数仅对 iOS 有效，因为系统会在扫描期间显示弹出窗口。在 iOS 上，此 `message ` 会被映射为扫描成功完成后显示的警报消息。其他平台将忽略 `message`。

该函数于 Qt 6.2 中引入。

另请参阅 startTargetDetection() 和stopTargetDetection()。

bool QNearFieldManager::startTargetDetection(QNearFieldTarget::AccessMethod accessMethod)

开始检测目标，若目标检测成功启动，则返回true ；否则返回false 。当目标进入近距离范围时，会触发targetDetected()信号。仅会报告具有指定accessMethod 的标签。目标检测将持续进行，直到调用stopTargetDetection()为止。

若要检测具有不同accessMethod 的目标，必须先调用stopTargetDetection()。

注意：在 iOS平台上 ，无法同时为 NdefAccess 和 TagTypeSpecificAccess 启动目标检测。因此，如果选择了 AnyAccess，则将改用 NdefAccess。

注意：在 使用 neard的平台上， 一旦检测到标签，目标检测将立即停止。

另请参阅 stopTargetDetection()。

void QNearFieldManager::stopTargetDetection(const QString &errorMessage = QString())

停止检测目标。targetDetected() 信号将不再发出，直到再次调用startTargetDetection() 为止。之前检测到的目标仍然有效。

注意：在 iOS平台上 ，调用此方法后，已检测到的目标将失效（例如，尝试写入或读取 NDEF 消息将导致错误）。

如果提供了errorMessage ，则向系统提示应用程序的目标未达成。此时会向用户显示errorMessage 以及相应的错误图标。若向该函数传递空的errorMessage ，则表示操作已成功结束；否则，应向该函数传递errorMessage 。

注意：目前， errorMessage 仅在 iOS 上生效，因为系统会在扫描过程中显示一个弹出窗口，其中会显示errorMessage 。其他平台将忽略此参数。

另请参阅 setUserInformation()。

[signal] void QNearFieldManager::targetDetected(QNearFieldTarget *target)

每当检测到目标时，都会发出此信号。target 参数代表被检测到的目标。

该信号将针对所有被检测到的目标发出。

QNearFieldManager 虽然该对象仍持有对 `target` 的所有权，但直到调用 `QNearFieldManager ` 的析构函数之前，它都不会被销毁。可通过调用 `setParent()` 来转移所有权。

请勿从连接到此信号的插槽中删除 `target `，而应调用 `deleteLater()`。

注意： 如果target 在移出邻近区域之前被删除，则 不会发出targetLost() 信号。

另请参阅 targetLost()。

[signal, since 6.2] void QNearFieldManager::targetDetectionStopped()

每当目标检测停止时，都会发出此信号。

注意： 该信号通常 在调用stopTargetDetection()时发出。此外，在 iOS 系统中，用户还可以在扫描过程中通过系统显示的弹出窗口停止检测，这也会触发该信号的发出。

该函数于 Qt 6.2 中引入。

[signal] void QNearFieldManager::targetLost(QNearFieldTarget *target)

每当目标移出近距离范围时，都会发出此信号。target 参数表示丢失的目标。

请勿从连接到此信号的插槽中删除 `target `，而应使用 `deleteLater()`。

另请参阅 QNearFieldTarget::disconnected()。

© 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.