Back to Qt.io
Contact Us Blog Download Qt

QNearFieldManager Class

QNearFieldManager 类提供对 NFC 事件通知的访问。更多

Header： #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 论坛标签或非接触式卡。

应用程序可以连接到targetDetected() 和targetLost() 信号，以便在 NFC Forum 标签进入或离开近距离时获得通知。在发出这些信号之前，必须使用startTargetDetection() 功能启动目标检测。目标检测可通过stopTargetDetection() 功能停止。当不再需要目标时，应删除目标，因为其他应用程序可能会被阻止访问目标。

Linux 上的 NFC

Linux NFC 项目提供了支持 Linux 平台上 NFC 的软件。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()。

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