En esta página

Implementación de complementos

En este tema se explica cómo implementar bibliotecas de complementos para que Qt o tu aplicación las carguen en tiempo de ejecución. Si utilizas complementos estáticos, el código de los complementos ya forma parte del ejecutable de tu aplicación y no se requieren pasos de implementación adicionales.

El directorio de complementos

En Qt, cuando se inicia una aplicación, el directorio del ejecutable de la aplicación es el directorio base en el que Qt busca los complementos.

Por ejemplo, en Windows, si la aplicación se encuentra en C:\Program Files\MyApp y tiene un complemento de estilo, Qt busca en C:\Program Files\MyApp\styles.

Para averiguar dónde se encuentra el ejecutable de tu aplicación, consulta QCoreApplication::applicationDirPath().

Qt también busca en el directorio especificado por ` QLibraryInfo::path` (`QLibraryInfo::PluginsPath`), que normalmente se encuentra en ` QTDIR/plugins`; ` QTDIR ` es el directorio donde está instalado Qt. Si deseas que Qt busque en otras ubicaciones, puedes añadir tantas rutas como necesites mediante llamadas a ` QCoreApplication::addLibraryPath`(). Si deseas establecer tus propias rutas, puedes utilizar ` QCoreApplication::setLibraryPaths`().

Como alternativa, puedes utilizar un archivo qt.conf para anular las rutas fijas que se compilan en la biblioteca de Qt. Para obtener más información, consulta Uso de qt.conf.

Otra posibilidad es configurar la variable de entorno QT_PLUGIN_PATH antes de ejecutar la aplicación; las rutas múltiples se pueden separar con un separador de rutas del sistema. Una vez configurada, Qt busca los complementos en las rutas especificadas en esta variable.

Nota: No exportes QT_PLUGIN_PATH como variable de entorno a nivel de sistema, ya que puede interferir con otras instalaciones de Qt.

Carga y verificación dinámica de complementos

Al cargar complementos, la biblioteca Qt realiza una serie de comprobaciones de validez para determinar si el complemento se puede cargar y utilizar. Esta comprobación de validez permite tener instaladas varias versiones y configuraciones de Qt simultáneamente.

Se aplican las siguientes reglas:

  • Los complementos vinculados a una biblioteca Qt que tenga un número de versión menor más alto no serán cargados por una biblioteca con un número de versión menor más bajo.


    Ejemplo: Qt 6.2.0 no cargará un complemento compilado con Qt 6.3.0. Ejemplo: Qt 6.2.0 cargará un complemento compilado con Qt 6.1.0. Ejemplo: Qt 6.2.0 cargará un complemento compilado con Qt 6.2.1.

  • Los complementos vinculados a una biblioteca Qt con un número de versión principal inferior no serán cargados por una biblioteca con un número de versión principal superior.


    Ejemplo: Qt 6.0.0 no cargará un complemento compilado con Qt 5.15.0.

Al compilar complementos para ampliar una aplicación, es importante asegurarse de que el complemento esté configurado de la misma manera que la aplicación. Esto significa que, si la aplicación se ha compilado en modo de lanzamiento, los complementos también deben compilarse en modo de lanzamiento. Excepto en los sistemas operativos Unix, donde el sistema de complementos no cargará complementos compilados en un modo diferente al de la aplicación.

Depuración de complementos

Existen varios problemas que pueden impedir que los complementos escritos correctamente funcionen con las aplicaciones diseñadas para utilizarlos. Muchos de ellos están relacionados con diferencias en la forma en que se han compilado los complementos y las aplicaciones, lo que a menudo se debe a sistemas y procesos de compilación distintos.

Para obtener información de diagnóstico de Qt sobre cada complemento que intenta cargar, utiliza la variable de entorno ` QT_DEBUG_PLUGINS `. Establece esta variable en un valor distinto de cero en el entorno en el que se ejecuta tu aplicación.

La siguiente tabla describe las causas más comunes de los problemas que experimentan los desarrolladores al crear complementos, así como las posibles soluciones.

ProblemaCausaSolución
Los complementos no se cargan sin mostrar ningún mensaje de error, incluso cuando la aplicación los abre directamente. La variable de entorno ` Qt Widgets Designer ` muestra las bibliotecas de complementos en su cuadro de diálogo « Help|About Plugins », pero no aparece ningún complemento en la lista correspondiente a cada una de ellas.La aplicación y sus complementos se han compilado en modos diferentes.Compila el complemento con la misma configuración que el ejecutable.

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