Qt NFC 概述

Qt NFC API 的典型用例包括

检测 NFC 标签。
读写 NDEF 消息。
注册 NDEF 消息处理程序。
共享文件和消息。

下文将介绍如何使用Qt NFC C++ 类和 QML 类型来处理上述用例。

注：在 Android 系统中，新 NFC 标签的检测仅适用于前台应用程序。由于 Android 方面的 API 限制，Android 服务不支持此功能。在服务中使用标签的唯一方法是提供一个接受标签的AIDL接口，并将其转发给 Qt，如下例所示。

public void setTag(Tag pTag) {
    Intent newIntent = new Intent();
    newIntent.putExtra(NfcAdapter.EXTRA_TAG, pTag);
    QtNative.onNewIntent(newIntent);
}

C++ 概述

C++ API 可访问Qt NFC API 的全部功能集。本节将介绍可供开发人员使用的主要功能。

检测 NFC 标签

QNearFieldManager 类负责检测进入设备范围的新 NFC 标签。当标签进入或离开范围时，会发出QNearFieldManager::targetDetected() 和QNearFieldManager::targetLost() 信号。传入的QNearFieldTarget 参数是每个检测到的标签的主要交互点。在调用QNearFieldManager::startTargetDetection() 之前，检测不会真正开始。

m_manager = new QNearFieldManager(this);
connect(m_manager, &QNearFieldManager::targetDetected,
        this, &MainWindow::targetDetected);
connect(m_manager, &QNearFieldManager::targetLost,
        this, &MainWindow::targetLost);
m_manager->startTargetDetection(QNearFieldTarget::NdefAccess);

最后可以停止检测：

m_manager->stopTargetDetection();

虽然每个QNearFieldTarget 实例都归其相关的QNearFieldManager 实例所有，但手动删除每个实例还是有好处的。否则，它们将继续存在，直到QNearFieldManager 实例被删除。最好的办法是响应QNearFieldManager::targetLost() 信号：

void MainWindow::targetLost(QNearFieldTarget *target)
{
    target->deleteLater();
}

注意： 只有在槽内删除目标对象时，才能通过 deleteLater() 删除目标对象。

连接 NFC 标签

QNearFieldTarget 中所有需要连接的函数都将自行创建连接。活动连接将阻止其他实例创建连接，因为同一时间只允许一个连接。

Qt 5 会在函数结束时断开标签连接，以允许其他实例连接。QNearFieldManager::setKeepConnection() 允许改变这种行为。

自 Qt XML 6 起，QNearFieldTarget 默认保持连接。只有当QNearFieldTarget 被销毁或调用QNearFieldManager::disconnect() 时，连接才会关闭。

读写 NDEF 消息

QNearFieldManager::targetDetected() 信号返回的QNearFieldTarget 实例用于与标签交互。读写消息是一种异步操作。QNearFieldTarget::RequestId 类关联了单个操作及其结果。

void MainWindow::targetDetected(QNearFieldTarget *target)
{
    switch (m_touchAction) {
    case NoAction:
        break;
    case ReadNdef:
        connect(target, &QNearFieldTarget::ndefMessageRead, this, &MainWindow::ndefMessageRead);
        connect(target, &QNearFieldTarget::error, this, &MainWindow::targetError);

        m_request = target->readNdefMessages();
        if (!m_request.isValid()) // cannot read messages
            targetError(QNearFieldTarget::NdefReadError, m_request);
        break;
    case WriteNdef:
        connect(target, &QNearFieldTarget::requestCompleted, this, &MainWindow::ndefMessageWritten);
        connect(target, &QNearFieldTarget::error, this, &MainWindow::targetError);

        m_request = target->writeNdefMessages(QList<QNdefMessage>() << ndefMessage());
        if (!m_request.isValid()) // cannot write messages
            targetError(QNearFieldTarget::NdefWriteError, m_request);
        break;
    }
}

一旦QNearFieldTarget::readNdefMessages() 请求处理成功，就会发出QNearFieldTarget::ndefMessageRead() 信号。每个返回的QNdefMessage 可能由零个或多个QNdefRecord 条目组成，这些条目可通过其类型加以识别。有关记录处理的更多信息，请参阅QNdefRecord 类文档。如上述代码所示，NDEF 消息的写入是通过QNearFieldTarget::writeNdefMessages() 触发的。写操作成功完成的标志是发出带有相应请求 ID 的QNearFieldTarget::requestCompleted() 信号。在读取或写入过程中出现的任何类型的错误都会通过QNearFieldTarget::error() 显示。

支持的 NFC 功能

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