En esta página

URL comentada

Lee mensajes formateados en el formato de intercambio de datos NFC (NDEF).

El ejemplo de URL anotada utiliza Qt NFC para mostrar el contenido de mensajes en formato NDEF (NFC Data Exchange Format) con un formato específico, leídos desde una etiqueta NFC. El mensaje NDEF debe contener un registro URI, un registro MIME opcional de tipo « image/* » y uno o más registros de texto localizados.

Este es el estado inicial del ejemplo:

Página principal de NFC con URL comentadas

Si se toca una etiqueta, se mostrará su contenido NDEF. Esta es la interfaz de usuario para una etiqueta que contiene un registro de texto y un registro URI:

Detalles de la etiqueta NFC con URL anotada

Al pulsar en la pantalla, la URL se abrirá en el navegador.

Definición de la clase AnnotatedUrl

La clase ` AnnotatedUrl ` envuelve a ` QNearFieldManager`, la clase que proporciona la funcionalidad de detección de etiquetas NFC. Los mensajes NDEF son leídos por ` QNearFieldManager ` y reenviados a un controlador contenido en la clase ` AnnotatedUrl `. Tras analizar el mensaje NDEF, la clase emite la señal ` annotatedUrl() `. La interfaz de usuario reacciona a la señal mostrando el contenido del mensaje 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;
};

Nota: El método startDetection() se utiliza para aplazar la detección real de la etiqueta hasta que se hayan establecido todas las conexiones entre la interfaz de usuario y la lógica relacionada con NFC. Esto es importante cuando la aplicación se inicia automáticamente al tocar una etiqueta NFC. Actualmente, este caso de uso es compatible con 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();
}

Filtrado de mensajes

Como se ha mencionado anteriormente, la aplicación admite mensajes NDEF de un formato específico. Un mensaje correcto debe contener los siguientes campos:

  • Al menos un registro de texto NDEF, que se utilizará como encabezado.
  • Exactamente un registro NDEF URI.
  • Un registro MIMEopcional con un icono.

El orden de los registros no está estrictamente especificado.

Para validar el mensaje NDEF se utiliza una instancia de ` QNdefFilter `. El filtro se configura de la siguiente manera:

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

Si el mensaje entrante no se ajusta al filtro, se muestra un mensaje de error:

Vista de los datos de la etiqueta NFC de la URL comentada

Nota: La aplicación de ejemplo NDEF Editor se puede utilizar para crear etiquetas con una estructura de mensaje correcta o incorrecta.

Implementación del controlador AnnotatedUrl

Los mensajes NFC leídos por el ` QNearFieldManager ` se reenvían a ` AnnotatedUrl::handleMessage`.

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

En primer lugar, los mensajes se validan mediante el método QNdefFilter::match():

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

Si los mensajes tienen el formato correcto, continúa el análisis.

Dado que los mensajes NFC se componen de varios registros NDEF, recorrer todos los registros permite extraer los tres parámetros que se mostrarán en la interfaz de usuario: el URI, el título y el mapa de píxeles:

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

Por último, tras haber extraído los parámetros del mensaje NFC, se emite la señal correspondiente para que la interfaz de usuario pueda gestionarlos.

    }

    emit annotatedUrl(url, title, pixmap);
}

Gestión del estado del adaptador

En Android, los cambios de estado del adaptador se pueden detectar conectándose a la señal « QNearFieldManager::adapterStateChanged()». Esto permite detener la detección cuando el adaptador NFC está desactivado y reiniciarla cuando el adaptador se vuelve a activar. Este enfoque se implementa en la ranura « 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);
    }
}

Inicio automático de la aplicación

Android admite el inicio automático de la aplicación al tocar una etiqueta NDEF. Consulta Qt NFC en Android para conocer los cambios necesarios en el archivo de manifiesto de Android.

La introducción de un archivo AndroidManifest.xml personalizado requiere pasos especiales por parte del sistema de compilación.

Compilación con qmake

Al utilizar qmake, es necesario añadir lo siguiente al archivo .pro:

android {
    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

    DISTFILES += \
        android/AndroidManifest.xml
}
Compilación con CMake

Si se utiliza CMake, hay que añadir lo siguiente al archivo CMakeLists.txt:

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

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Proyecto de ejemplo en code.qt.io

Véase también 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.