QResource Class
La clase QResource proporciona una interfaz para leer directamente de los recursos. Más...
| Cabecera: | #include <QResource> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluyendo los heredados
- QResource es parte de Input/Output y Networking.
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
Descripción Detallada
QResource es un objeto que representa un conjunto de datos (y posiblemente hijos) relativos a una única entidad resource. QResource da acceso directo a los bytes en su formato crudo. De esta forma, el acceso directo permite la lectura de datos sin copia de búfer o indirección. La indirección suele ser útil cuando se interactúa con la entidad de recurso como si fuera un archivo, lo que puede conseguirse con QFile. Los datos e hijos detrás de un QResource normalmente se compilan en una aplicación/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 cargará como un gran conjunto de datos y luego se distribuirá por partes a través de referencias en el árbol de recursos.
Un QResource puede cargarse con una ruta absoluta, tratada como un sistema de archivos enraizado con un carácter /, o en notación de recursos enraizado con un carácter :. También se puede abrir un recurso relativo que se encontrará en la lista de rutas devuelta por QDir::searchPaths().
Un QResource que esté representando un archivo tendrá datos respaldándolo, estos datos pueden posiblemente estar comprimidos, en cuyo caso qUncompress() debe ser usado para acceder a los datos reales; esto sucede implícitamente cuando se accede a través de un QFile. Un QResource que esté representando un directorio tendrá sólo hijos y ningún dato.
Carga dinámica de recursos
Un recurso puede dejarse fuera del binario de una aplicación y cargarse cuando se necesite en tiempo de ejecución utilizando la función registerResource(). El archivo de recursos pasado a registerResource() debe ser un recurso binario creado por rcc. Puede encontrar más información sobre recursos binarios en la documentación del Sistema de Recursos Qt.
Esto puede ser útil a menudo cuando se carga un gran conjunto de iconos de aplicación que pueden cambiar en función de una configuración, o que pueden ser editados por un usuario y posteriormente recreados. El recurso se carga inmediatamente en memoria, ya sea como resultado de una operación de lectura de un único archivo, o como un archivo mapeado en memoria.
Este enfoque puede suponer una importante ganancia de rendimiento, ya que sólo se cargará un único archivo, y los datos se entregarán a través de la ruta solicitada en setFileName().
La función unregisterResource() elimina una referencia a un fichero en particular. Si hay objetos QResource que actualmente hacen referencia a recursos relacionados con el fichero no registrado, seguirán siendo válidos pero el propio fichero de recursos se eliminará de las raíces de recursos, y por tanto no se podrán crear más QResource que apunten a estos datos de recursos. El propio recurso se eliminará 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 fichero pasado para determinar si está soportado por la versión actual de Qt. Esas pruebas son sólo para comprobar que la cabecera del archivo no solicita características (como la descompresión Zstandard) que no han sido compiladas o que el archivo no es de una versión futura de Qt. No confirman la validez de todo el archivo.
QResource no debería utilizarse en archivos en cuya procedencia no se pueda confiar. Las aplicaciones deberían diseñarse para intentar cargar sólo archivos de recursos cuya procedencia sea al menos tan fiable como la de la propia aplicación o sus plugins.
Ver también El Sistema de Recursos Qt, QFile, QDir, y QFileInfo.
Documentación de tipos de miembros
enum QResource::Compression
Este enum es utilizado por compressionAlgorithm() para indicar qué algoritmo utilizó la herramienta RCC para comprimir la carga útil.
| Constante | Valor | Descripción |
|---|---|---|
QResource::NoCompression | 0 | El contenido no está comprimido |
QResource::ZlibCompression | 1 | El contenido está comprimido con zlib y puede descomprimirse con la función qUncompress(). |
QResource::ZstdCompression | 2 | Los contenidos están comprimidos utilizando zstd. Para descomprimir, 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())
Construye un QResource apuntando 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 encontró a través de QDir::searchPaths() se indicará en la ruta.
Véase también fileName().
[protected] QStringList QResource::children() const
Devuelve una lista de todos los recursos en este directorio, si el recurso representa 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 existe. Si no está comprimido, esta función devuelve QResource::NoCompression.
Si esta función devuelve QResource::ZlibCompression, puede 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, necesitas usar las funciones de la librería Zstandard (cabecera<zstd.h> ). Qt no proporciona un wrapper.
Ver manual de Zstandard.
Véase también data() y isFile().
const uchar *QResource::data() const
Devuelve acceso directo a un segmento de datos de sólo lectura, que este recurso representa. Si el recurso está comprimido, los datos devueltos también lo estarán. El usuario deberá descomprimir los datos o utilizar uncompressedData(). Si el recurso es un directorio, se devuelve nullptr.
Véase también uncompressedData(), size() y isFile().
QString QResource::fileName() const
Devuelve la ruta completa al archivo que representa este QResource tal y como se le 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 tener children() en él, 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 tanto, tiene datos detrás, 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, false en caso contrario.
QDateTime QResource::lastModified() const
Devuelve la fecha y hora en que se modificó por última vez el archivo antes de empaquetarlo 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 dado en la ubicación del árbol de recursos especificada por mapRoot, y devuelve true si el archivo se abre con éxito; 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 dado en la ubicación del árbol de recursos especificada por mapRoot, y devuelve true si el archivo se abre con éxito; en caso contrario devuelve false.
Advertencia: Los datos deben permanecer válidos durante toda la 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 QResource para que apunte a file. file puede ser absoluto, en cuyo caso se abre directamente, si es relativo entonces se intentará encontrar el archivo en QDir::searchPaths().
Véase también fileName() y absoluteFilePath().
void QResource::setLocale(const QLocale &locale)
Establece un QResource para cargar sólo la localización del recurso a para locale. Si no se encuentra un recurso para la localización específica, entonces se utiliza la localización 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 obtener el tamaño sin comprimir.
Véase también data(), uncompressedSize() y isFile().
QByteArray QResource::uncompressedData() const
Devuelve los datos del recurso, descomprimiéndolos primero, si los datos se almacenaron comprimidos. Si el recurso es un directorio o se produce un error al descomprimir, se devuelve un QByteArray nulo.
Nota: Si los datos estaban comprimidos, esta función se descomprimirá cada vez que se llame. 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 lo mismo 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 dado en la ubicación en el árbol de recursos especificada por mapRoot, y devuelve true si el recurso se descarga con éxito y no existen referencias para el recurso; 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 dado en la ubicación en el árbol de recursos especificada por mapRoot, y devuelve true si el recurso se descarga con éxito y no existen referencias en el recurso; 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.
