Qt NFC 概述

使用Qt NFC API的典型用例包括：

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

以下各节将介绍如何使用Qt NFC 的 C++ 类和 QML 类型来实现上述用例。

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

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();
}

注意： 只有当目标对象是在槽（slot）内部被删除时，才应通过 deleteLater() 进行删除。

连接 NFC 标签

QNearFieldTarget 中所有需要连接的功能都会自动建立连接。活跃的连接会阻止其他实例建立连接，因为同一时间只允许存在一个连接。

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

自 Qt 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 功能

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