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

带注释的 URL

读取经过格式化的NFC数据交换格式（NDEF）消息。

“带注释的 URL”示例使用 Qt NFC 来显示从NFC标签中读取的、具有特定格式的NFC数据交换格式（NDEF）消息的内容。该NDEF消息应包含一个URI记录、一个可选的image/* MIME记录，以及一个或多个本地化文本记录。

这是该示例的初始状态：

带注释的URL NFC主屏幕

如果触摸标签，其NDEF内容将被显示。以下是包含文本记录和URI记录的标签的用户界面：

带注释的URL NFC标签详细信息

点击屏幕时，浏览器将打开该URL。

AnnotatedUrl 类定义

AnnotatedUrl 类封装了QNearFieldManager 类，该类提供NFC标签检测功能。NDEF消息由QNearFieldManager 读取，并转发至AnnotatedUrl 类中的处理程序。解析NDEF消息后，该类会发出annotatedUrl() 信号。用户界面响应该信号，显示NDEF消息的内容。

class AnnotatedUrl : public QObject
{
    Q_OBJECT

public:
    explicit AnnotatedUrl(QObject *parent = 0);
    ~AnnotatedUrl();

    void startDetection();

signals:
    void annotatedUrl(const QUrl &url, const QString &title, const QPixmap &pixmap);
    void nfcStateChanged(bool enabled);
    void tagError(const QString &error);

public slots:
    void targetDetected(QNearFieldTarget *target);
    void targetLost(QNearFieldTarget *target);
    void handleMessage(const QNdefMessage &message, QNearFieldTarget *target);
    void handlePolledNdefMessage(QNdefMessage message);
    void handleAdapterStateChange(QNearFieldManager::AdapterState state);

private:
    QNearFieldManager *manager;
    QNdefFilter messageFilter;
};

注意： startDetection() 方法用于将 实际的标签检测推迟到UI与NFC相关逻辑之间的所有连接都建立之后。当应用程序在接触NFC标签时自动启动时，这一点非常重要。目前，Android系统支持此类用例。

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainWindow mainWindow;
    AnnotatedUrl annotatedUrl;

    QObject::connect(&annotatedUrl, &AnnotatedUrl::annotatedUrl,
                     &mainWindow, &MainWindow::displayAnnotatedUrl);
    QObject::connect(&annotatedUrl, &AnnotatedUrl::nfcStateChanged,
                     &mainWindow, &MainWindow::nfcStateChanged);
    QObject::connect(&annotatedUrl, &AnnotatedUrl::tagError,
                     &mainWindow, &MainWindow::showTagError);

    annotatedUrl.startDetection();
    mainWindow.show();

    return a.exec();
}

消息过滤

如上所述，该应用支持特定格式的 NDEF 消息。一条正确的消息应包含以下字段：

  • 至少一个NDEF Text 记录，该记录将用作头部。
  • 且仅包含一个NDEF URI 记录。
  • 一个可选的、包含图标的 MIME 记录。

记录的顺序没有严格规定。

使用QNdefFilter 的实例来验证NDEF消息。过滤器的配置如下：

    messageFilter.setOrderMatch(false);
    messageFilter.appendRecord<QNdefNfcTextRecord>(1, 100);
    messageFilter.appendRecord<QNdefNfcUriRecord>(1, 1);
    messageFilter.appendRecord(QNdefRecord::Mime, "", 0, 1);

如果传入的消息与过滤器不匹配，将显示一条错误消息：

带注释的 URL NFC 标签数据显示

注意： 可使用NDEF Editor示例应用程序创建消息结构正确或错误的标签。

AnnotatedUrl 处理程序的实现

由QNearFieldManager 读取的NFC消息将转发至AnnotatedUrl::handleMessage 。

void AnnotatedUrl::handleMessage(const QNdefMessage &message, QNearFieldTarget *target)
{

首先，使用QNdefFilter::match() 方法对消息进行验证：

    if (!messageFilter.match(message)) {
        emit tagError("Invalid message format");
        return;
    }

如果消息格式正确，则继续进行解析。

由于 NFC 消息由多个 NDEF 记录组成，遍历所有记录可提取 3 个参数并在 UI 中显示：Uri、Title 和 Pixmap：

    for (const QNdefRecord &record : message) {
        if (record.isRecordType<QNdefNfcTextRecord>()) {
            QNdefNfcTextRecord textRecord(record);

            title = textRecord.text();
            QLocale locale(textRecord.locale());
        } else if (record.isRecordType<QNdefNfcUriRecord>()) {
            QNdefNfcUriRecord uriRecord(record);

            url = uriRecord.uri();
        } else if (record.typeNameFormat() == QNdefRecord::Mime &&
                   record.type().startsWith("image/")) {
            pixmap = QPixmap::fromImage(QImage::fromData(record.payload()));
        }

最后，在提取 NFC 消息的参数后，会触发相应的信号，以便 UI 进行处理。

    }

    emit annotatedUrl(url, title, pixmap);
}

适配器状态处理

在 Android 平台上，可通过订阅 `QNearFieldManager::adapterStateChanged()` 信号来检测适配器状态的变化。这使得在 NFC 适配器禁用时能够停止检测，并在适配器重新启用时恢复检测。该机制在 `AnnotatedUrl::handleAdapterStateChange ` 槽中实现。

void AnnotatedUrl::handleAdapterStateChange(QNearFieldManager::AdapterState state)
{
    if (state == QNearFieldManager::AdapterState::Online) {
        startDetection();
    } else if (state == QNearFieldManager::AdapterState::Offline) {
        manager->stopTargetDetection();
        emit nfcStateChanged(false);
    }
}

应用程序自动启动

Android 支持在触摸 NDEF 标签时自动启动应用程序。有关 Android 清单文件所需的更改，请参阅《Android 上的Qt NFC 》。

引入自定义的 AndroidManifest.xml 需要在构建系统方面采取特殊步骤。

使用 qmake 构建

使用 qmake 时，需在.pro 文件中添加以下内容：

android {
    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

    DISTFILES += \
        android/AndroidManifest.xml
}
使用 CMake 构建

使用 CMake 时，需在CMakeLists.txt 中添加以下内容：

if(ANDROID)
    set_property(TARGET annotatedurl
        APPEND PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
        ${CMAKE_CURRENT_SOURCE_DIR}/android
    )
endif()

运行示例

您可以通过以下方式运行示例：

示例项目 @ code.qt.io

另请参阅 Qt 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.