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:

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:

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:

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:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en « Examples ». Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde « Command Palette » y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
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.