En esta página

QResource Class

La clase QResource proporciona una interfaz para leer directamente desde los recursos. Más información...

Encabezado: #include <QResource>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum Compression { NoCompression, ZlibCompression, ZstdCompression }

Funciones públicas

QResource(const QString &file = QString(), const QLocale &locale = QLocale())
~QResource()
QString absoluteFilePath() const
QResource::Compression compressionAlgorithm() const
const uchar *data() const
QString fileName() const
bool isValid() const
QDateTime lastModified() const
QLocale locale() const
void setFileName(const QString &file)
void setLocale(const QLocale &locale)
qint64 size() const
QByteArray uncompressedData() const
qint64 uncompressedSize() const

Miembros públicos estáticos

bool registerResource(const QString &rccFileName, const QString &mapRoot = QString())
bool registerResource(const uchar *rccData, const QString &mapRoot = QString())
bool unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
bool unregisterResource(const uchar *rccData, const QString &mapRoot = QString())

Funciones protegidas

QStringList children() const
bool isDir() const
bool isFile() const

Descripción detallada

QResource es un objeto que representa un conjunto de datos (y, posiblemente, elementos secundarios) relacionados con una única entidad de recurso. QResource proporciona acceso directo a los bytes en su formato sin procesar. De este modo, el acceso directo permite leer los datos sin necesidad de copiarlos a un búfer ni de utilizar indirecciones. La indirección suele resultar útil cuando se interactúa con la entidad de recurso como si se tratara de un archivo; esto se puede lograr mediante ` QFile`. Los datos y los elementos secundarios asociados a un `QResource` suelen compilarse en una aplicación o biblioteca, pero también es posible cargar un recurso en tiempo de ejecución. Cuando se carga en tiempo de ejecución, el archivo de recursos se carga como un gran conjunto de datos y, a continuación, se distribuye por partes a través de referencias en el árbol de recursos.

Un QResource puede cargarse con una ruta absoluta, ya sea tratada como un sistema de archivos con raíz en el carácter « / », o en notación de recursos con raíz en el carácter « : ». También se puede abrir un recurso relativo, que se encontrará en la lista de rutas devueltas por « QDir::searchPaths()».

Un QResource que represente un archivo tendrá datos que lo respalden; estos datos pueden estar comprimidos, en cuyo caso se debe utilizar qUncompress() para acceder a los datos reales; esto ocurre de forma implícita cuando se accede a través de un QFile. Un QResource que represente un directorio solo tendrá elementos secundarios y ningún dato.

Carga dinámica de recursos

Un recurso puede omitirse en el binario de una aplicación y cargarse cuando sea necesario en tiempo de ejecución mediante la función ` registerResource()`. El archivo de recursos pasado a ` registerResource()` debe ser un recurso binario creado con `rcc`. Se puede encontrar más información sobre los recursos binarios en la documentación del sistema de recursos de Qt.

Esto suele resultar útil a la hora de cargar un gran conjunto de iconos de la aplicación que pueden cambiar en función de una configuración, o que el usuario puede editar y volver a crear posteriormente. El recurso se carga inmediatamente en memoria, ya sea como resultado de una única operación de lectura de archivo o como un archivo mapeado en memoria.

Este enfoque puede suponer una mejora significativa del rendimiento, ya que solo se cargará un único archivo y los datos se proporcionarán a través de la ruta solicitada en setFileName().

La función unregisterResource() elimina una referencia a un archivo concreto. Si hay objetos QResource que actualmente hacen referencia a recursos relacionados con el archivo no registrado, seguirán siendo válidos, pero el propio archivo de recursos se eliminará de las raíces de recursos y, por lo tanto, no se podrá crear ningún otro QResource que apunte a estos datos de recursos. El propio recurso se desasignará de la memoria cuando se destruya el último QResource que apunte a él.

Corrupción y seguridad

La clase `QResource` realiza algunas comprobaciones sobre el archivo pasado para determinar si es compatible con la versión actual de Qt. Esas comprobaciones solo sirven para verificar que la cabecera del archivo no solicite características (como la descompresión Zstandard) que no se hayan compilado o que el archivo no pertenezca a una versión futura de Qt. No confirman la validez del archivo en su totalidad.

No se debe utilizar QResource con archivos cuya procedencia no sea fiable. Las aplicaciones deben diseñarse para intentar cargar únicamente archivos de recursos cuya procedencia sea, como mínimo, tan fiable como la de la propia aplicación o sus complementos.

Véase también El sistema de recursos de Qt, QFile, QDir y QFileInfo.

Documentación sobre tipos de miembros

enum QResource::Compression

compressionAlgorithm() utiliza esta enumeración para indicar qué algoritmo ha empleado la herramienta RCC para comprimir la carga útil.

ConstanteValorDescripción
QResource::NoCompression0El contenido no está comprimido
QResource::ZlibCompression1El contenido se comprime con zlib y se puede descomprimir mediante la función qUncompress().
QResource::ZstdCompression2El contenido está comprimido con zstd. Para descomprimirlo, utilice la función ` ZSTD_decompress ` de la biblioteca zstd.

Véase también compressionAlgorithm().

Documentación de las funciones miembro

QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())

Crea un objeto `QResource` que apunta a ` file`. ` locale ` se utiliza para cargar una localización específica de los datos de un recurso.

Véase también QFileInfo, QDir::searchPaths(), setFileName() y setLocale().

[noexcept] QResource::~QResource()

Libera los recursos del objeto « QResource ».

QString QResource::absoluteFilePath() const

Devuelve la ruta real que representa este QResource; si el recurso se ha encontrado mediante la función QDir::searchPaths(), esto se indicará en la ruta.

Véase también fileName().

[protected] QStringList QResource::children() const

Devuelve una lista de todos los recursos de este directorio; si el recurso es un archivo, la lista estará vacía.

Véase también isDir().

QResource::Compression QResource::compressionAlgorithm() const

Devuelve el tipo de compresión con el que está comprimido este recurso, si es que lo está. Si no está comprimido, esta función devuelve ` QResource::NoCompression`.

Si esta función devuelve « QResource::ZlibCompression », puedes descomprimir los datos utilizando la función « qUncompress()». Hasta Qt 5.13, este era el único algoritmo de compresión posible.

Si esta función devuelve ` QResource::ZstdCompression`, deberá utilizar las funciones de la biblioteca Zstandard (cabecera `<zstd.h> `). Qt no proporciona una envoltura.

Consulte el manual de Zstandard.

Véanse también data() y isFile().

const uchar *QResource::data() const

Devuelve acceso directo a un segmento de datos de solo lectura que representa este recurso. Si el recurso está comprimido, los datos devueltos también lo están. En ese caso, el usuario debe descomprimir los datos o utilizar la función ` uncompressedData()`. Si el recurso es un directorio, se devuelve ` nullptr `.

Véanse también uncompressedData(), size() y isFile().

QString QResource::fileName() const

Devuelve la ruta completa del archivo que representa este objeto ` QResource ` tal y como se pasó.

Véase también setFileName() y absoluteFilePath().

[protected] bool QResource::isDir() const

Devuelve ` true ` si el recurso representa un directorio y, por lo tanto, puede contener ` children()`; devuelve `false` si representa un archivo.

Véase también isFile().

[protected] bool QResource::isFile() const

Devuelve ` true ` si el recurso representa un archivo y, por lo tanto, contiene datos, y `false` si representa un directorio.

Véase también isDir().

bool QResource::isValid() const

Devuelve « true » si el recurso existe realmente en la jerarquía de recursos; en caso contrario, devuelve «false».

QDateTime QResource::lastModified() const

Devuelve la fecha y la hora en que se modificó por última vez el archivo antes de incluirlo en un recurso.

QLocale QResource::locale() const

Devuelve la configuración regional utilizada para localizar los datos de QResource.

Véase también setLocale().

[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())

Registra el recurso con el rccFileName indicado en la ubicación del árbol de recursos especificada por mapRoot y devuelve true si el archivo se abre correctamente; en caso contrario, devuelve false.

Véase también unregisterResource().

[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())

Registra el recurso con el rccData indicado en la ubicación del árbol de recursos especificada por mapRoot y devuelve true si el archivo se abre correctamente; en caso contrario, devuelve false.

Advertencia: Los datos deben seguir siendo válidos durante todo el tiempo de vida de cualquier QFile que pueda hacer referencia a los datos del recurso.

Véase también unregisterResource().

void QResource::setFileName(const QString &file)

Establece un objeto ` QResource ` para que apunte a ` file`. ` file ` puede ser una ruta absoluta, en cuyo caso se abre directamente; si es relativa, se intentará localizar el archivo mediante ` QDir::searchPaths()`.

Véase también fileName() y absoluteFilePath().

void QResource::setLocale(const QLocale &locale)

Establece un objeto ` QResource ` para que solo se cargue la localización del recurso correspondiente a ` locale`. Si no se encuentra un recurso para esa configuración regional específica, se utiliza la configuración regional C.

Véase también locale() y setFileName().

qint64 QResource::size() const

Devuelve el tamaño de los datos almacenados que respaldan el recurso.

Si el recurso está comprimido, esta función devuelve el tamaño de los datos comprimidos. Consulte uncompressedSize() para conocer el tamaño sin comprimir.

Véanse también data(), uncompressedSize() y isFile().

QByteArray QResource::uncompressedData() const

Devuelve los datos del recurso, descomprimiéndolos primero si estaban almacenados comprimidos. Si el recurso es un directorio o se produce un error durante la descompresión, se devuelve un valor nulo ` QByteArray `.

Nota: Si los datos estaban comprimidos, esta función los descomprimirá cada vez que se llame a ella. El resultado no se almacena en caché entre llamadas.

Véase también uncompressedSize(), size(), compressionAlgorithm() y isFile().

qint64 QResource::uncompressedSize() const

Devuelve el tamaño de los datos de este recurso. Si los datos no estaban comprimidos, esta función devuelve el mismo resultado que size(). Si lo estaban, esta función extrae el tamaño de los datos originales sin comprimir del flujo almacenado.

Véase también size(), uncompressedData() y isFile().

[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())

Desregistra el recurso con el rccFileName indicado en la ubicación del árbol de recursos especificada por mapRoot y devuelve true si el recurso se ha descargado correctamente y no existen referencias al mismo; en caso contrario, devuelve false.

Véase también registerResource().

[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())

Desregistra el recurso con el rccData indicado en la ubicación del árbol de recursos especificada por mapRoot y devuelve true si el recurso se ha descargado correctamente y no existen referencias al mismo; en caso contrario, devuelve false.

Véase también registerResource().

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