En esta página

qt_target_qml_sources

Añade archivos QML y recursos a un destino de módulo QML ya existente.

Este comando se introdujo en Qt 6.2.

El comando está definido en el componente « Qml » del paquete « Qt6 », que se puede cargar de la siguiente manera:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Sinopsis

qt_target_qml_sources(
    target
    [QML_FILES ...]
    [RESOURCES ...]
    [PREFIX resource_path]
    [OUTPUT_TARGETS out_targets_var]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_QMLDIR_TYPES]
)

Si los comandos sin versión están desactivados, utiliza en su lugar qt6_target_qml_sources(). Admite el mismo conjunto de argumentos que este comando.

Descripción

Nota: Este comando requiere CMake 3.19 o posterior.

qt_target_qml_sources() Permite añadir más archivos a un módulo QML después de haber llamado a qt_add_qml_module(). Normalmente, se pasa el conjunto de archivos y recursos de .qml directamente a qt_add_qml_module(), pero en algunos casos puede ser conveniente, o incluso necesario, añadir archivos después de haber llamado a qt_add_qml_module(). Por ejemplo, es posible que se desee añadir archivos de forma condicional en función de una expresión de la instrucción ` if `, o desde subdirectorios que solo se añadirán si se cumplen determinados criterios. Quizás se quiera añadir un conjunto de archivos con características diferentes a las del resto, como un prefijo de recursos distinto, o con el linting y la compilación de bytecode desactivados. El comando ` qt_target_qml_sources() ` permite estos casos de uso.

Argumentos

El « target » debe ser el objetivo de respaldo de un módulo QML o, si el módulo QML no tiene un objetivo de respaldo independiente, debe ser el objetivo del complemento del módulo.

QML_FILES es una lista de archivos « .qml », « .js » y « .mjs » que se añadirán al módulo QML. Esta opción tiene exactamente el mismo efecto que la opción « QML_FILES » del comando «qt_add_qml_module()», incluida la compilación automática a código byte y el procesamiento de lint.

Las opciones « NO_CACHEGEN » y « NO_LINT » también tienen el mismo efecto que en «qt_add_qml_module()». Desactivan la compilación a bytecode y el procesamiento de lint para los archivos enumerados con « QML_FILES ». Este comportamiento también se puede especificar solo para archivos individuales mediante las propiedades del archivo fuente.

NO_QMLDIR_TYPES impide que el ` QML_FILES ` se añada como tipos al archivo ` qmldir ` generado.

RESOURCES Tiene exactamente el mismo efecto que la opción « RESOURCES » del comando «qt_add_qml_module() ». Proporciona una lista de archivos que se añadirán al « target » como recursos normales. Estos archivos suelen ser elementos como imágenes, sombreadores, etc., a los que el código QML hace referencia de alguna manera.

Los archivos añadidos al módulo mediante « QML_FILES » o « RESOURCES » se colocarán bajo el mismo prefijo de recursos y la misma ruta de destino que si se hubieran añadido mediante el comando «qt_add_qml_module() ». Esto se puede anular indicando una ubicación diferente con la opción « PREFIX ». El valor que siga a la palabra clave « PREFIX » se utilizará directamente, sin añadir ninguna ruta de destino. La ruta de recurso final de cada archivo será el prefijo, más la ruta del archivo bajo CMAKE_CURRENT_SOURCE_DIR. La propiedad del archivo fuente QT_RESOURCE_ALIAS también se puede utilizar para anular esa ruta relativa.

qt_add_qml_module(backing
    URI Example
    VERSION 1.0
    RESOURCE_PREFIX /my.company.com/imports
)

qt_target_qml_sources(backing
    QML_FILES special/First.qml
    RESOURCES icons/logo.png
)

qt_target_qml_sources(backing
    PREFIX /other.company.com/debugging
    QML_FILES Inspector.qml
)

En el ejemplo anterior, los recursos del objetivo « backing » tendrán finalmente el siguiente contenido:

  • /my.company.com/imports/Example/special/First.qml
  • /my.company.com/imports/Example/icons/logo.png
  • /other.company.com/debugging/Inspector.qml

OUTPUT_TARGETS es análogo a la misma opción de `qt_add_qml_module()`. Úsalo para especificar el nombre de una variable en la que se almacenarán los objetivos adicionales creados para las compilaciones estáticas. Si se va a instalar el ` target `, estos objetivos adicionales también deberán instalarse para cumplir los requisitos de enlace.

Propiedades de los archivos fuente

Se pueden utilizar varias propiedades de los archivos fuente para influir en cómo se trata cada archivo « .qml » individual en distintos momentos del procesamiento del módulo QML. Estas propiedades anulan cualquier opción de nivel superior especificada en las llamadas a ` qt_target_qml_sources() ` o `qt_add_qml_module()`. Todas estas propiedades deben configurarse antes de añadir los archivos con cualquiera de esos dos comandos.

QT_QML_SKIP_QMLLINT Se puede establecer la propiedad « TRUE » en un archivo fuente para evitar que se incluya en el procesamiento automático de qmllint. Por defecto, todos los archivos « .qml » se incluirán en la ejecución de lint del objetivo, pero esta opción se puede utilizar para excluir archivos específicos.

QT_QML_SKIP_CACHEGEN Hace algo similar, impidiendo que un archivo fuente se compile a código byte cuando esta propiedad se establece en « TRUE ». Ten en cuenta que el archivo seguirá añadiéndose a « target » como recurso en formato no compilado (véase Almacenamiento en caché de fuentes QML compiladas).

Establezca la propiedad « QT_QML_SKIP_QMLDIR_ENTRY » del archivo fuente en « TRUE » para evitar que ese archivo QML o JavaScript se añada como tipo al archivo « qmldir » del módulo QML (véase «Generación automática de archivos « qmldir » y «typeinfo»»). Normalmente, esto se utilizaría para un archivo que no exponga un tipo público, como un archivo JavaScript privado. En el caso de los archivos JavaScript con nombres en mayúsculas que no sean módulos ECMAScript ni estén declarados como bibliotecas sin estado mediante ` .pragma library `, deberías considerar esta opción. Si los incluyes en el archivo ` qmldir `, se reevaluarán en el ámbito de cada documento QML que importe, de forma explícita o implícita, el módulo al que pertenecen.

Por defecto, al generar el archivo qmldir , se generará una única entrada de tipo por cada archivo .qml que proporcione un tipo. Se le asignará un número de versión X.0, donde X es la versión principal del módulo QML. Si el módulo QML tiene alguna versión PAST_MAJOR_VERSIONS establecida, se aplicará el mismo patrón a estas también, añadiendo X.0 por cada versión principal anterior X. En los casos en los que un archivo deba proporcionar entradas de tipo para un conjunto diferente de versiones (por ejemplo, si se añadió por primera vez en una versión de parche menor tras el lanzamiento de .0 ), especifica esas versiones en la propiedad QT_QML_SOURCE_VERSIONS del archivo fuente. Se creará una entrada de tipo para cada versión.

Si el tipo que proporciona un archivo ` .qml ` es un singleton, establece su propiedad ` QT_QML_SINGLETON_TYPE ` en ` TRUE`. Del mismo modo, la propiedad de origen ` QT_QML_INTERNAL_TYPE ` del archivo se puede establecer en ` TRUE ` para indicar que el tipo que proporciona es interno. El nombre del tipo también se puede sobrescribir mediante la propiedad « QT_QML_SOURCE_TYPENAME ». Estas tres propiedades se reflejarán en las entradas de tipo del archivo en el archivo « qmldir » generado. Las propiedades de origen deben establecerse antes de crear el módulo al que pertenece el singleton.

Todos los archivos enumerados con QML_FILES o RESOURCES se añadirán a los recursos de target. Su ubicación en los recursos consiste en un punto base y una ruta relativa. El punto base, por defecto, es la concatenación del prefijo de recursos del módulo QML y su ruta de destino, pero estos se pueden sobrescribir con el argumento PREFIX. La ruta relativa será, por defecto, la ruta del archivo relativa a la propiedad de destino « SOURCE_DIR » de « target ». Esta ruta relativa puede sobrescribirse configurando la propiedad « QT_RESOURCE_ALIAS » en el archivo fuente. Esto se utiliza habitualmente para recopilar archivos de diferentes directorios y hacer que aparezcan en los recursos bajo una ubicación común. Sin embargo, desde Qt 6.8, habilitar QTP0004 suele ser una mejor opción si el objetivo es que todos los archivos del módulo Qml se puedan encontrar en la importación implícita. En los casos en los que siga siendo necesaria una configuración manual de este tipo, es recomendable pasar ` NO_GENERATE_EXTRA_QMLDIRS ` a ` qt_add_qml_module`, ya que los `qmldirs` adicionales no tienen en cuenta los alias de los archivos de recursos.

set_source_files_properties(nested/way/down/File.qml PROPERTIES
    QT_RESOURCE_ALIAS File.qml
)
set_source_files_properties(TemplateFile.qml PROPERTIES
    QT_RESOURCE_ALIAS templates/File.qml
    QT_QML_SKIP_QMLDIR_ENTRY TRUE
    QT_QML_SKIP_QMLLINT TRUE
    QT_QML_SKIP_CACHEGEN TRUE
)
set_source_files_properties(FunnySingleton.qml PROPERTIES
    QT_QML_SINGLETON_TYPE TRUE
)
qt_add_qml_module(qt_target_qml_sources_example
    URI Example
    VERSION 2.3
    RESOURCE_PREFIX /my.company.com/imports
    NO_GENERATE_EXTRA_QMLDIRS
    QML_FILES
        nested/way/down/File.qml
        TemplateFile.qml
        FunnySingleton.qml
)

set_source_files_properties(some_old_thing.qml PROPERTIES
    QT_QML_SOURCE_VERSIONS "1.1;2.0"
    QT_QML_SOURCE_TYPENAME OldThing
)
set_source_files_properties(../../../images/button-types.png PROPERTIES
    QT_RESOURCE_ALIAS button-types.png
)
qt_target_qml_sources(qt_target_qml_sources_example
    QML_FILES some_old_thing.qml
    RESOURCES
        ../../../images/button-types.png
        doc/README.txt
)

En el ejemplo anterior, los recursos del objetivo « qt_target_qml_sources_example » tendrán el siguiente contenido:

  • /my.company.com/imports/Example/File.qml
  • /my.company.com/imports/Example/FunnySingleton.qml
  • /my.company.com/imports/Example/templates/File.qml
  • /my.company.com/imports/Example/some_old_thing.qml
  • /my.company.com/imports/Example/button-types.png
  • /my.company.com/imports/Example/doc/README.txt

El archivo « qmldir » generado contendrá las siguientes entradas de tipo:

File 2.0 File.qml
singleton FunnySingleton 2.0 FunnySingleton.qml
OldThing 1.1 some_old_thing.qml
OldThing 2.0 some_old_thing.qml

Nota: El archivo fuente FunnySingleton.qml debe contener ya la instrucción « pragma Singleton ». Al establecer la propiedad « QT_QML_SINGLETON_TYPE » del archivo fuente no se genera automáticamente el pragma.

pragma Singleton
import QtQml

QtObject {}

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