qt_add_qml_plugin
Define un complemento asociado a un módulo QML.
El comando se define en el componente « Qml » del paquete « Qt6 », que se puede cargar de la siguiente manera:
find_package(Qt6 REQUIRED COMPONENTS Qml)Sinopsis
qt_add_qml_plugin(
target
[BACKING_TARGET backing_target]
[STATIC | SHARED]
[OUTPUT_DIRECTORY]
[URI]
[CLASS_NAME]
[NO_GENERATE_PLUGIN_SOURCE]
[NAMESPACE namespace]
)Si los comandos sin versión están desactivados, utiliza en su lugar qt6_add_qml_plugin(). Admite el mismo conjunto de argumentos que este comando.
Descripción
Este comando crea el objetivo de complemento asociado a un módulo QML. Normalmente, qt_add_qml_module() lo invoca internamente para crear o actualizar el complemento asociado a su objetivo subyacente. No debes llamar a esta función directamente a menos que existan circunstancias especiales que requieran crear el objetivo de una forma específica.
La documentación de qt_add_qml_module() describe diferentes patrones estructurales sobre cómo se pueden organizar los objetivos de CMake asociados a un módulo QML. Ten en cuenta que, aunque el módulo QML no tenga un objetivo de respaldo independiente y toda la funcionalidad se implemente directamente en el complemento (lo cual no es la configuración recomendada), debes seguir llamando a `qt_add_qml_module()` en lugar de ` qt_add_qml_plugin()`.
Argumentos
target especifica el nombre del objetivo que se utilizará para el complemento QML. Si aún no existe, se creará.
BACKING_TARGET Especifica el nombre del objetivo de respaldo al que está asociado el complemento. El objetivo de respaldo puede ser el mismo que el del complemento ` target`; en ese caso, solo habrá un objetivo fusionado, pero esto no suele recomendarse (véase `qt_add_qml_module() ` para obtener más información). Siempre debe proporcionarse ` BACKING_TARGET `, a menos que existan circunstancias especiales que requieran que el objetivo del complemento se cree antes que el objetivo de respaldo. Si no se proporciona BACKING_TARGET, debe especificarse la opción URI.
Por defecto, el complemento se crea con un tipo compatible con el objetivo de soporte. Si el objetivo de soporte es una biblioteca estática, el complemento también se creará como biblioteca estática. Si el objetivo de soporte es una biblioteca compartida, el complemento se creará como biblioteca de módulos. Cuando no se especifique ningún objetivo de respaldo o el complemento no tenga un objetivo de respaldo independiente, el tipo de complemento se puede especificar mediante las palabras clave « STATIC » o « SHARED ». Si el tipo de complemento no viene determinado por ninguna de las condiciones anteriores, se creará un complemento estático si Qt se ha compilado como bibliotecas estáticas; en caso contrario, se creará un complemento de biblioteca de módulos.
OUTPUT_DIRECTORY Especifica el directorio en el que se creará la biblioteca del complemento. Siempre debe ser la misma ubicación que la del archivo `qmldir` del módulo QML. Cuando no se especifica ` OUTPUT_DIRECTORY `, se obtendrá a partir de la información almacenada en ` BACKING_TARGET`, si está disponible. Tenga en cuenta que esto podría diferir del directorio de la propia biblioteca del destino de respaldo. Si no se puede obtener un directorio de salida del destino de respaldo, se utilizará por defecto CMAKE_CURRENT_BINARY_DIR.
URI Declara el identificador del módulo QML al que está asociado este complemento. El identificador del módulo es el identificador (en notación URI con puntos) del módulo QML. Si no se especifica URI, se debe proporcionar un BACKING_TARGET y el objetivo subyacente debe tener su URI registrado en él (normalmente mediante una llamada previa a qt_add_qml_module()).
Cada complemento debe tener una clase C++ que registre el módulo en el motor QML. Por defecto, qt_add_qml_plugin() genera automáticamente los archivos fuente de esta clase C++ y los añade a la lista de fuentes del target. La clase de complemento generada cumple con el requisito de que el complemento sea opcional (véase «Archivos qmldir de definición de módulos»). El nombre de la clase se determina de la siguiente manera:
- Si se ha especificado `
CLASS_NAME`, se utilizará ese nombre. Debe coincidir con el nombre utilizado en el archivo `qmldir` del módulo QML. - Si no se ha especificado
CLASS_NAME, pero síBACKING_TARGET, el nombre de la clase C++ se tomará de los datos registrados en ese destino de respaldo. Dichos datos suelen registrarse mediante una llamada previa a qt_add_qml_module(), y coincidirán con el nombre utilizado en el archivoqmldirgenerado. Esta es la forma recomendada de proporcionar el nombre de la clase en la mayoría de los casos. - Si aún así no se puede determinar el nombre de la clase, se establece como el URI del módulo, sustituyendo los puntos por guiones bajos y añadiendo «
Plugin» al final.
Si se especifica un espacio de nombres con la palabra clave « NAMESPACE », el código del complemento se generará en un espacio de nombres de C++ con ese nombre.
Algunos complementos pueden requerir que la clase del complemento se escriba manualmente. Por ejemplo, es posible que el complemento tenga que realizar una inicialización adicional o registrar elementos que no estén implementados por la clase de complemento predeterminada. En tales casos, se puede especificar la opción « NO_GENERATE_PLUGIN_SOURCE ». En ese caso, el usuario será responsable de escribir su propia clase de complemento en C++ y añadirla a target. Tenga en cuenta que, si necesita escribir su propia clase de complemento, es muy poco probable que el complemento pueda ser opcional. Esto, a su vez, significa que la palabra clave « NO_PLUGIN_OPTIONAL » debe incluirse en la llamada a ` qt_add_qml_module()` al definir el módulo QML; de lo contrario, el archivo ` qmldir ` generado será incorrecto. Asegúrate de que tu clase de complemento utilice el mismo nombre de clase que el determinado según la lógica anterior.
© 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.