qt_target_qml_sources

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

Este comando se introdujo en Qt 6.2.

El comando se define en el componente Qml del paquete Qt6, que puede cargarse de este modo:

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, utilice qt6_target_qml_sources() en su lugar. Admite el mismo conjunto de argumentos que este comando.

Descripción

qt_target_qml_sources() proporciona la posibilidad de 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 .qml a qt_add_qml_module() directamente, pero en algunos casos, puede ser deseable, o incluso necesario, añadir archivos después de que qt_add_qml_module() haya sido llamada. Por ejemplo, puede que desee añadir archivos condicionalmente basándose en una expresión de la sentencia if, o de subdirectorios que sólo se añadirán si se cumplen ciertos criterios. Es posible que desee añadir un conjunto de archivos con características diferentes a los demás, como un prefijo de recurso diferente, o con linting y compilación de bytecode desactivados. El comando qt_target_qml_sources() permite estos escenarios.

Argumentos

target debe ser el destino de respaldo de un módulo QML o, si el módulo QML no tiene un destino de respaldo independiente, debe ser el destino de 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 bytecode y el procesamiento de lint.

Las opciones NO_CACHEGEN y NO_LINT también tienen el mismo efecto que para qt_add_qml_module(). Desactivan la compilación bytecode y el procesamiento lint para los archivos listados con QML_FILES. Este comportamiento también puede especificarse sólo para archivos individuales utilizando las propiedades del archivo fuente.

NO_QMLDIR_TYPES evita que 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 a target como recursos ordinarios. Estos archivos son típicamente cosas como imágenes, shaders, etc. a los que el código QML hace referencia de alguna manera.

Los archivos añadidos al módulo a través de QML_FILES o RESOURCES se colocarán bajo el mismo prefijo de recurso y ruta de destino que si se hubieran añadido mediante el comando qt_add_qml_module(). Esto se puede anular proporcionando una ubicación diferente con la opción PREFIX. El valor que sigue a la palabra clave PREFIX se utilizará directamente, sin añadir ninguna ruta de destino. La ruta final del recurso de cada archivo será el prefijo, más la ruta del archivo debajo de CMAKE_CURRENT_SOURCE_DIR. La propiedad de 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 destino backing terminarán con 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 también análoga a la misma opción para qt_add_qml_module(). Utilícela para especificar el nombre de una variable en la que almacenar cualquier objetivo adicional creado para las compilaciones estáticas. Si se va a instalar target, estos objetivos adicionales también deberán instalarse para satisfacer los requisitos de vinculación.

Propiedades del archivo fuente

Se puede utilizar una serie de propiedades de archivo fuente para influir en el tratamiento de cada archivo .qml individual en distintos puntos del procesamiento del módulo QML. Estas 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 establecerse antes de añadir los archivos con cualquiera de estos dos comandos.

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

QT_QML_SKIP_CACHEGEN hace algo similar, impidiendo que un archivo fuente sea compilado a código de bytes cuando esta propiedad se establece en TRUE. Tenga en cuenta que el archivo se seguirá añadiendo a target como recurso sin compilar (consulte Almacenamiento en caché de fuentes QML compiladas).

Establezca la propiedad QT_QML_SKIP_QMLDIR_ENTRY source file en TRUE para evitar que ese archivo QML o JavaScript se añada como tipo al archivo qmldir del módulo QML (consulte Generación automática de archivos qmldir y typeinfo). Esto se utilizaría normalmente para un archivo que no expone un tipo público, como un archivo JavaScript privado. Para archivos JavaScript con nombres en mayúsculas que no sean módulos ECMAScript ni estén declarados como bibliotecas sin estado a través de .pragma library, debería considerar esta opción. Si los incluye en el archivo qmldir, se reevalúan en el ámbito de cada documento QML que importe explícita o implícitamente el módulo al que pertenecen.

Por defecto, al generar el archivo qmldir , se generará una única entrada de tipo para 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 algún conjunto PAST_MAJOR_VERSIONS, también se aplicará el mismo patrón, añadiendo X.0 por cada versión principal anterior X. Para situaciones en las que un archivo necesita proporcionar entradas de tipo para un conjunto diferente de versiones (por ejemplo, se añadió por primera vez en una versión de parche menor después de la versión .0 ), especifique 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, establezca su propiedad QT_QML_SINGLETON_TYPE en TRUE. Del mismo modo, la propiedad fuente QT_QML_INTERNAL_TYPE del archivo puede establecerse en TRUE para indicar que el tipo que proporciona es interno. El nombre del tipo en sí también se puede anular utilizando 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 listados 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 es, por defecto, la concatenación del prefijo del recurso del módulo QML y su ruta de destino, pero puede modificarse 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 anularse estableciendo la propiedad QT_RESOURCE_ALIAS en el archivo fuente. Esto se utiliza comúnmente 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 es a menudo una mejor opción si el objetivo es que todos los archivos del módulo QML puedan encontrarse en la importación implícita. En los casos en que esta configuración manual siga siendo necesaria, es aconsejable pasar NO_GENERATE_EXTRA_QMLDIRS a qt_add_qml_module, ya que los qmldirs adicionales no tienen en cuenta el aliasing 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 destino 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

pragma Singleton
import QtQml

QtObject {}