En esta página

El sistema de recursos de Qt

El sistema de recursos de Qt es un mecanismo independiente de la plataforma que permite incluir archivos de recursos en una aplicación. Úsalo si tu aplicación necesita siempre un determinado conjunto de archivos (como iconos, archivos de traducción o imágenes) y no quieres utilizar métodos específicos del sistema para empaquetar y localizar dichos recursos.

Lo más habitual es que los archivos de recursos se incrusten en el ejecutable de la aplicación, o en bibliotecas y complementos que carga dicho ejecutable. Como alternativa, los archivos de recursos también pueden almacenarse en un archivo de recursos externo.

El sistema de recursos se basa en una estrecha colaboración entre el Resource Compiler de Qt, el sistema de compilación y la API de tiempo de ejecución de Qt.

Nota: Actualmente , el sistema de recursos de Qt no utiliza ninguna funcionalidad específica del sistema para gestionar los recursos, como las que existen en Windows, macOS e iOS. Esto podría cambiar en una futura versión de Qt.

El compilador de recursos « Resource Compiler » (rcc) de Qt XML

La herramienta de línea de comandos «Resource Compiler » (rcc) lee archivos de recursos y genera un archivo fuente en C++ o Python, o bien un archivo « .rcc ».

La lista de archivos y los metadatos relacionados se pasan a rcc en forma de un archivo de colección de recursos de Qt.

Por defecto, rcc generará código fuente en C++ que luego se compilará como parte de un ejecutable o una biblioteca. La opción « -g python » genera código fuente en Python en su lugar. La opción « -binary » genera un archivo binario que, por convención, se guarda en un archivo « .rcc » y puede cargarse en tiempo de ejecución.

Nota: Aunque es posible ejecutar rcc desde la línea de comandos, normalmente es mejor dejar esta tarea en manos de un sistema de compilación. Véanse también las secciones sobre qmake y CMake más adelante.

Archivo de recopilación de recursos de Qt (.qrc)

Un archivo ` .qrc ` es un documento XML que enumera los archivos locales que se van a incluir como recursos en tiempo de ejecución. Sirve como entrada para ` rcc`.

A continuación se muestra un ejemplo de archivo « .qrc »:

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

Cada elemento <file> del XML identifica un archivo del árbol de fuentes de la aplicación. La ruta se resuelve de forma relativa al directorio que contiene el archivo .qrc.

La ruta también se utiliza, por defecto, para identificar el contenido del archivo en tiempo de ejecución. Es decir, el archivo copy.png estará disponible en el sistema de recursos como :/images/copy.png o qrc:/images/copy.png. Para anular este nombre predeterminado en tiempo de ejecución, consulta «Prefijos y alias».

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code, y Qt Visual Studio Tools te permiten crear, examinar y editar archivos « .qrc » a través de una interfaz de usuario muy práctica. Excepto el Diseñador de « Qt Widgets », también ofrecen asistentes para proyectos que utilizan el sistema de recursos de Qt.

Integración con el sistema de compilación

El procesamiento de los archivos de recursos con rcc suele realizarse en el momento de la compilación de la aplicación. Varias herramientas de compilación cuentan con soporte específico para ello, entre ellas CMake y qmake.

CMake

Si « CMAKE_AUTORCC » está activado, basta con añadir los archivos « .qrc » como fuentes a tu ejecutable o biblioteca. Los archivos de recursos a los que se hace referencia quedarán entonces integrados en el binario:

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

Consulta la documentación de CMake sobre AUTORCC para obtener más detalles al respecto.

Una alternativa a AUTORCC es utilizar la función qt_add_resources de Qt6Core para CMake, que ofrece un mayor control sobre la creación de recursos. Por ejemplo, permite especificar el contenido del recurso directamente en el archivo del proyecto sin necesidad de escribir primero un archivo « .qrc »:

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

Por último, `qt_add_qml_module ` permite integrar recursos ` Qt Quick ` en el sistema de recursos de su aplicación. La función está definida en el componente ` Qml ` del paquete CMake ` Qt6 `.

qmake

qmake admite la gestión de recursos mediante la variable RESOURCES. Si añades una ruta de archivo .qrc a la variable, los archivos de recursos indicados se integrarán en la biblioteca o el ejecutable generado:

RESOURCES = application.qrc

En el caso de aplicaciones sencillas, también es posible dejar que qmake genere el archivo ` .qrc ` por ti, evitando así la necesidad de mantener un archivo adicional:

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

Esto crea un recurso compuesto por varios archivos ` .png `, a los que se puede acceder de la siguiente manera: ` ":/images/copy.png"`.

Si la estructura de directorios de los archivos que deseas incluir en el recurso no se ajusta a lo que espera la aplicación, puedes especificar resources.base. base es un prefijo de ruta que indica el punto raíz del alias del archivo. En el ejemplo siguiente, si resources.base se establece en "images", entonces se puede acceder a copy.png como ":/copy.png".

API de tiempo de ejecución

La API de Qt que se encarga de iterar y leer archivos cuenta con soporte integrado para el sistema de recursos de Qt. Se puede pasar una ruta de recurso en lugar de una ruta de archivo local a ` QFile ` y ` QDir`, pero también, por ejemplo, a los constructores ` QIcon`, ` QImage` y ` QPixmap `:

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

El prefijo : deja claro que «/images/cut.png» debe cargarse desde el sistema de recursos de Qt.

También puedes hacer referencia al sistema de recursos de Qt a través de un QUrl. En este caso, utiliza el esquema qrc:

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

Temas avanzados

Prefijos

Un archivo ` .qrc ` puede establecer un prefijo que se añadirá al nombre de cada archivo local, indicado en un elemento ` <file> `, para obtener el nombre con el que se identificará el archivo dentro del sistema de recursos.

Los prefijos permiten estructurar los recursos, evitando conflictos entre archivos de recursos añadidos a través de diferentes archivos ` .qrc ` en distintas bibliotecas o complementos.

Nota: Los prefijos /qt y /qt-project.org están reservados para casos de uso documentados en Qt. El archivo qt.conf se consulta, por ejemplo, en :/qt/etc/qt.conf o qrc:/qt/etc/qt.conf.

Alias

A veces resulta conveniente que un archivo de recursos esté disponible en una ruta diferente en tiempo de ejecución. Los archivos « .qrc » permiten hacerlo estableciendo un atributo « alias »:

<file alias="cut-img.png">images/cut.png</file>

De este modo, solo se podrá acceder al archivo desde la aplicación como :/cut-img.png o qrc:/cut-img.png.

Descartar el contenido del archivo

A veces se desea añadir un nodo de archivo al sistema de archivos de recursos, pero sin añadir realmente el contenido del archivo. Los archivos .qrc permiten hacerlo estableciendo el atributo empty en true.

<file empty="true">Button.qml</file>

De este modo, se sigue pudiendo acceder al archivo desde la aplicación, pero su contenido está vacío.

Esto resulta útil para eliminar el código fuente QML del binario de una aplicación.

Nota: Si se omite el código fuente QML del binario, el motor QML tendrá que basarse en las unidades de compilación creadas por qmlcachegen o qmlsc. Estas están vinculadas a la versión específica de Qt con la que se compilaron. Si se cambia la versión de Qt que utiliza la aplicación, ya no se podrán cargar.

Selectores de idioma

Algunos recursos deben cambiar en función de la configuración regional del usuario, como los archivos de traducción o los iconos. Los archivos de colección de recursos admiten esta función mediante el atributo « lang » de la etiqueta « qresource », en el que se especifica una cadena de configuración regional adecuada. Por ejemplo:

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

Si la configuración regional del usuario es el francés (es decir, QLocale::system().language() es francés), :/cut.jpg o qrc:/cut.jpg se convierte en una referencia a la imagen cut_fr.jpg. Para otras configuraciones regionales, se utiliza cut.jpg.

Consulta la documentación de QLocale para obtener una descripción del formato que se debe utilizar para las cadenas de configuración regional.

Consulte QFileSelector para conocer un mecanismo adicional para seleccionar recursos específicos de cada configuración regional.

Incrustación de archivos de gran tamaño

Por defecto, rcc integra los archivos de recursos en los ejecutables en forma de matrices de C++. Esto puede resultar problemático, especialmente en el caso de recursos de gran tamaño.

Si el compilador tarda demasiado o incluso falla debido a un desbordamiento de memoria, puedes optar por un modo especial en el que los recursos se incrustan en un proceso de dos pasos. El compilador de C++ solo reserva el espacio suficiente en el ejecutable o la biblioteca de destino para los recursos. La incrustación real del contenido y los metadatos del archivo de recursos se realiza después de la fase de compilación y enlace, mediante otra llamada a rcc.

En qmake, esto se habilita añadiendo « resources_big » a la variable « CONFIG »:

CONFIG += resources_big

En el caso de CMake, es necesario utilizar la función qt_add_big_resources.

Archivos de recursos externos

Una alternativa a la incorporación de los archivos de recursos en el binario es almacenarlos en un archivo « .rcc » independiente. rcc permite hacerlo mediante la opción « -binary ». A continuación, dicho archivo « .rcc » debe cargarse en tiempo de ejecución con « QResource ».

Por ejemplo, un conjunto de datos de recursos especificados en un archivo .qrc se puede compilar de la siguiente manera:

rcc -binary myresource.qrc -o myresource.rcc

En la aplicación, este recurso se registraría con un código como este:

QResource::registerResource("/path/to/myresource.rcc");

Si utilizas CMake, puedes emplear la función ` qt_add_binary_resources ` para programar la llamada a ` rcc ` anterior:

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Recursos en una aplicación Qt for Python

El archivo de recopilación de recursos se convierte en un módulo de Python mediante el Resource Compiler rcc:

rcc -g python mainwindow.qrc > mainwindow_rc.py

A continuación, el módulo se puede importar a la aplicación:

import mainwindow_rc.py

Compresión

rcc intenta comprimir el contenido para optimizar el uso del espacio en disco en los binarios finales. De forma predeterminada, realizará una comprobación heurística para determinar si merece la pena comprimirlo y almacenará el contenido sin comprimir si no consigue comprimirlo lo suficiente. Para controlar el umbral, puedes utilizar la opción « -threshold », que indica a rcc el porcentaje del tamaño del archivo original que debe ahorrarse para que este almacene el archivo en formato comprimido.

rcc -threshold 25 myresources.qrc

El valor por defecto es «70», lo que indica que el archivo comprimido debe ser un 70 % más pequeño que el original (no más del 30 % del tamaño del archivo original).

Es posible desactivar la compresión si se desea. Esto puede resultar útil si tus recursos ya contienen un formato comprimido, como los archivos .png, y no quieres incurrir en el coste de CPU durante la compilación para confirmar que no se puede comprimir. Otra razón es si el uso del disco no supone un problema y la aplicación prefiere mantener el contenido como páginas de memoria limpias en tiempo de ejecución. Para ello, se debe especificar el argumento de línea de comandos « -no-compress ».

rcc -no-compress myresources.qrc

rcc También te permite controlar en cierta medida el nivel de compresión y el algoritmo de compresión; por ejemplo:

rcc -compress 2 -compress-algo zlib myresources.qrc

También es posible utilizar compress y threshold como atributos en una etiqueta file del archivo .qrc. Para seleccionar el algoritmo, configura el atributo compression-algorithm.

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

Lo anterior seleccionará el algoritmo zstd con un nivel de compresión 1.

rcc Admite los siguientes algoritmos y niveles de compresión:

  • best: utiliza el mejor algoritmo de entre los que se indican a continuación, en su nivel de compresión más alto, para lograr la máxima compresión a costa de un mayor consumo de tiempo de CPU durante la compilación. Este valor resulta útil en el archivo XML para indicar que un archivo debe comprimirse al máximo, independientemente de los algoritmos que admita rcc.
  • zstd: utiliza la biblioteca Zstandard para comprimir el contenido. Los niveles de compresión válidos van del 1 al 19; el 1 corresponde a la menor compresión (menor tiempo de CPU) y el 19 a la mayor compresión (mayor tiempo de CPU). El nivel predeterminado es 14. Un valor especial de 0 indica a la biblioteca zstd que elija un valor predeterminado definido por la implementación.
  • zlib: utiliza la biblioteca zlib para comprimir el contenido. Los niveles de compresión válidos van del 1 al 9, siendo el 1 el que aplica la menor compresión (menor tiempo de CPU) y el 9 el que aplica la mayor compresión (mayor tiempo de CPU). El valor especial 0 significa «sin compresión» y no debe utilizarse. El valor por defecto viene definido por la implementación, pero suele ser el nivel 6.
  • none: sin compresión. Es lo mismo que la opción « -no-compress ».

La compatibilidad tanto con Zstandard como con zlib es opcional. Si no se ha detectado una biblioteca determinada en tiempo de compilación, intentar pasar -compress-algo para esa biblioteca dará lugar a un error. El algoritmo de compresión por defecto es zstd si está habilitado, y zlib si no lo está.

Carga y descarga explícita de recursos integrados

Los recursos incrustados en el código ejecutable o en la biblioteca de C++ se registran automáticamente en el sistema de recursos de Qt mediante el constructor de una variable global interna. Dado que las variables globales se inicializan antes de que se ejecute main(), los recursos están disponibles cuando el programa comienza a ejecutarse.

Al incrustar recursos en bibliotecas estáticas, el enlazador de C++ podría eliminar las variables estáticas que registran los recursos. Por lo tanto, si incrustas recursos en una biblioteca estática, debes registrarlos explícitamente llamando a ` Q_INIT_RESOURCE()` con el nombre base del archivo ` .qrc `. Por ejemplo:

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    //...
}

También puede eliminar explícitamente los recursos registrados de la aplicación, por ejemplo, al descargar un complemento. Para ello, utilice Q_CLEANUP_RESOURCE().

Nota: Dado que los inicializadores de recursos generados por rcc se declaran en el espacio de nombres global, las llamadas a Q_INIT_RESOURCE() y Q_CLEANUP_RESOURCE() deben realizarse fuera de cualquier espacio de nombres.

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