QPluginLoader Class
La clase QPluginLoader carga un complemento en tiempo de ejecución. Más información...
| Encabezado: | #include <QPluginLoader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredado de: | QObject |
- Lista de todos los miembros, incluidos los heredados
- QPluginLoader forma parte de las clases de complementos.
Nota: Todas las funciones de esta clase son reentrantes.
Propiedades
Funciones públicas
| QPluginLoader(QObject *parent = nullptr) | |
| QPluginLoader(const QString &fileName, QObject *parent = nullptr) | |
| virtual | ~QPluginLoader() |
| QString | errorString() const |
| QString | fileName() const |
| QObject * | instance() |
| bool | isLoaded() const |
| bool | load() |
| QLibrary::LoadHints | loadHints() const |
| QJsonObject | metaData() const |
| void | setFileName(const QString &fileName) |
| void | setLoadHints(QLibrary::LoadHints loadHints) |
| bool | unload() |
Miembros públicos estáticos
| QObjectList | staticInstances() |
| QList<QStaticPlugin> | staticPlugins() |
Elementos no miembros relacionados
| void | qRegisterStaticPluginFunction(QStaticPlugin plugin) |
Descripción detallada
QPluginLoader proporciona acceso a un complemento de Qt. Un complemento de Qt se almacena en una biblioteca compartida (una DLL) y ofrece estas ventajas con respecto a las bibliotecas compartidas a las que se accede mediante QLibrary:
- QPluginLoader comprueba que el complemento esté vinculado a la misma versión de Qt que la aplicación.
- QPluginLoader proporciona acceso directo a un objeto componente raíz (instance()), en lugar de obligarte a resolver una función C manualmente.
Una instancia de un objeto QPluginLoader opera sobre un único archivo de biblioteca compartida, al que denominamos «plugin». Proporciona acceso a la funcionalidad del plugin de forma independiente de la plataforma. Para especificar qué plugin se debe cargar, basta con pasar un nombre de archivo en el constructor o establecerlo mediante setFileName().
Las funciones más importantes son load() para cargar dinámicamente el archivo del complemento, isLoaded() para comprobar si la carga se ha realizado correctamente, y instance() para acceder al componente raíz del complemento. La función instance() intenta cargar implícitamente el complemento si aún no se ha cargado. Se pueden utilizar varias instancias de QPluginLoader para acceder al mismo complemento físico.
Una vez cargados, los complementos permanecen en memoria hasta que se hayan descargado todas las instancias de QPluginLoader o hasta que la aplicación finalice. Puedes intentar descargar un complemento utilizando ` unload()`; sin embargo, si otras instancias de `QPluginLoader` están utilizando la misma biblioteca, la llamada fallará, y la descarga solo se producirá cuando todas las instancias hayan llamado a ` unload()`. Justo antes de que se produzca la descarga, el componente raíz también se eliminará.
Consulta «Cómo crear complementos de Qt » para obtener más información sobre cómo hacer que tu aplicación sea extensible mediante complementos.
Ten en cuenta que QPluginLoader no se puede utilizar si tu aplicación está enlazada estáticamente con Qt. En este caso, también tendrás que enlazar los complementos de forma estática. Puedes utilizar QLibrary si necesitas cargar bibliotecas dinámicas en una aplicación enlazada estáticamente.
Véase también QLibrary.
Documentación sobre propiedades
fileName : QString
Esta propiedad contiene el nombre del archivo del complemento
Recomendamos omitir la extensión del archivo en el nombre, ya que QPluginLoader buscará automáticamente el archivo con la extensión adecuada (véase QLibrary::isLibrary()).
Al cargar el complemento, QPluginLoader busca en todas las ubicaciones de complementos especificadas por QCoreApplication::libraryPaths(), a menos que el nombre del archivo tenga una ruta absoluta. Tras cargar el complemento correctamente, fileName() devuelve el nombre completo del complemento, incluida la ruta completa al complemento si se ha proporcionado en el constructor o se ha pasado a setFileName().
Si el nombre de archivo no existe, no se establecerá. En ese caso, esta propiedad contendrá una cadena vacía.
Por defecto, esta propiedad contiene una cadena vacía.
Funciones de acceso:
| QString | fileName() const |
| void | setFileName(const QString &fileName) |
Véase también load().
loadHints : QLibrary::LoadHints
Proporciona a la función ` load()` algunas indicaciones sobre cómo debe comportarse.
Puedes proporcionar indicaciones sobre cómo se resuelven los símbolos del complemento. De forma predeterminada, desde Qt 5.7, QLibrary::PreventUnloadHint está activado.
Consulta la documentación de QLibrary::loadHints para obtener una descripción completa de cómo funciona esta propiedad.
Funciones de acceso:
| QLibrary::LoadHints | loadHints() const |
| void | setLoadHints(QLibrary::LoadHints loadHints) |
Véase también QLibrary::loadHints.
Documentación de las funciones miembro
[explicit] QPluginLoader::QPluginLoader(QObject *parent = nullptr)
Crea un cargador de complementos con el archivo ` parent` especificado.
[explicit] QPluginLoader::QPluginLoader(const QString &fileName, QObject *parent = nullptr)
Crea un cargador de complementos con la extensión de archivo « parent » indicada, que cargará el complemento especificado por « fileName ».
Para que se pueda cargar, la extensión del archivo debe ser una extensión válida para una biblioteca cargable según la plataforma; por ejemplo, .so en Unix, - .dylib en macOS e iOS, y .dll en Windows. La extensión se puede verificar con QLibrary::isLibrary().
Véase también setFileName().
[virtual noexcept] QPluginLoader::~QPluginLoader()
Destruye el objeto QPluginLoader.
A menos que se haya llamado explícitamente a unload(), el complemento permanece en memoria hasta que la aplicación se cierre.
Véase también isLoaded() y unload().
QString QPluginLoader::errorString() const
Devuelve una cadena de texto con la descripción del último error que se ha producido.
QObject *QPluginLoader::instance()
Devuelve el objeto componente raíz del complemento. El complemento se carga si es necesario. La función devuelve un objeto ` nullptr ` si no se ha podido cargar el complemento o si no se ha podido instanciar el objeto componente raíz.
Si el objeto del componente raíz se ha destruido, al llamar a esta función se crea una nueva instancia.
El componente raíz, devuelto por esta función, no se elimina cuando se destruye el ` QPluginLoader `. Si quieres asegurarte de que se elimine el componente raíz, debes llamar a ` unload()` tan pronto como ya no necesites acceder al componente principal. Cuando finalmente se descargue la biblioteca, el componente raíz se eliminará automáticamente.
El objeto componente es un ` QObject`. Utilice ` qobject_cast()` para acceder a las interfaces que le interesen.
Véase también load().
bool QPluginLoader::isLoaded() const
Devuelve ` true ` si el complemento está cargado; en caso contrario, devuelve ` false`.
Véase también load().
bool QPluginLoader::load()
Carga el complemento y devuelve ` true ` si se ha cargado correctamente; en caso contrario, devuelve ` false`. Dado que ` instance()` siempre llama a esta función antes de resolver cualquier símbolo, no es necesario llamarla explícitamente. En algunas situaciones, es posible que quieras que el complemento se cargue por adelantado, en cuyo caso deberías utilizar esta función.
Véase también unload().
QJsonObject QPluginLoader::metaData() const
Devuelve los metadatos de este complemento. Los metadatos son datos especificados en formato JSON mediante la macro Q_PLUGIN_METADATA() al compilar el complemento.
Los metadatos se pueden consultar de forma rápida y sin coste alguno, sin necesidad de cargar el complemento. Esto permite, por ejemplo, almacenar allí las capacidades del complemento y decidir si se carga o no en función de dichos metadatos.
[static] QObjectList QPluginLoader::staticInstances()
Devuelve una lista de instancias de complementos estáticos (componentes raíz) que contiene el cargador de complementos.
Véase también staticPlugins().
[static] QList<QStaticPlugin> QPluginLoader::staticPlugins()
Devuelve una lista de objetos `QStaticPlugins` almacenados por el cargador de complementos. La función es similar a ` staticInstances()` con la diferencia de que un objeto ` QStaticPlugin ` también contiene información de metadatos.
Véase también staticInstances().
bool QPluginLoader::unload()
Descarga el complemento y devuelve ` true ` si se ha podido descargar; en caso contrario, devuelve ` false`.
Esto ocurre automáticamente al cerrar la aplicación, por lo que normalmente no deberías tener que llamar a esta función.
Si hay otras instancias de ` QPluginLoader ` que estén utilizando el mismo complemento, la llamada fallará, y la descarga solo se producirá cuando todas las instancias hayan llamado a `unload()`.
No intentes eliminar el componente raíz. En su lugar, confía en que unload() lo eliminará automáticamente cuando sea necesario.
Artículos relacionados para no socios
void qRegisterStaticPluginFunction(QStaticPlugin plugin)
Registra el objeto ` plugin ` especificado con el cargador de complementos, y es utilizado por la función ` Q_IMPORT_PLUGIN()`.
© 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.