qt_target_qml_sources

将 QML 文件和资源添加到现有的 QML 模块目标中。

该命令于 Qt 6.2 版本中引入。

该命令定义在Qt6 包的Qml 组件中，可按以下方式加载：

find_package(Qt6 REQUIRED COMPONENTS Qml)

语法概述

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

如果禁用了无版本号的命令，请改用qt6_target_qml_sources() 。该命令支持与本命令相同的参数集。

描述

qt_target_qml_sources() 该命令允许在调用qt_add_qml_module()之后，向 QML 模块中添加更多文件。 通常，您会将一组.qml 文件和资源直接传递给qt_add_qml_module()，但在某些情况下，可能希望甚至有必要在调用qt_add_qml_module()之后添加文件。 例如，您可能希望根据if 语句的表达式有条件地添加文件，或者从只有在满足特定条件时才会被添加的子目录中添加文件。您可能希望添加一组与其他文件特性不同的文件，例如具有不同的资源前缀，或者禁用了代码检查和字节码编译。qt_target_qml_sources() 命令可支持这些场景。

参数

target 必须是QML模块的后端目标；如果QML模块没有单独的后端目标，则必须是该模块的插件目标。

QML_FILES 是一个包含.qml 、.js 和.mjs 文件的列表，这些文件将被添加到QML模块中。此选项的效果与qt_add_qml_module()命令的QML_FILES 选项完全相同，包括自动编译为字节码和lint处理。

NO_CACHEGEN 和NO_LINT 选项的效果也与qt_add_qml_module()中的效果相同。它们会禁用对QML_FILES 中列出的文件的字节码编译和lint处理。此行为也可通过源文件属性针对单个文件单独指定。

NO_QMLDIR_TYPES 防止将QML_FILES 作为类型添加到生成的qmldir文件中。

RESOURCES 其效果与qt_add_qml_module()命令的RESOURCES 选项完全相同。它提供了一组文件列表，这些文件将作为普通资源添加到target 中。这些文件通常是 QML 代码以某种方式引用的图像、着色器等内容。

通过QML_FILES 或RESOURCES 添加到模块中的文件，其资源前缀和目标路径与使用qt_add_qml_module()命令添加时完全一致。可以通过使用PREFIX 选项指定不同的位置来覆盖此行为。PREFIX 关键字后面的值将被直接采用，不会附加任何目标路径。 每个文件的最终资源路径将由前缀加上该文件在 `CMAKE_CURRENT_SOURCE_DIR` 下的路径组成。也可以使用源文件属性 `QT_RESOURCE_ALIAS` 来覆盖该相对路径。

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
)

在上面的示例中，backing 目标的资源最终将包含以下内容：

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

OUTPUT_TARGETS 这与qt_add_qml_module() 的同名选项类似。使用该选项指定一个变量名称，用于存储为静态构建创建的任何额外目标。如果将安装该target ，则这些额外目标也需要一并安装，以满足链接要求。

源文件属性

可以使用一些源文件属性来影响每个.qml 文件在QML模块处理的不同阶段中的处理方式。这些属性会覆盖在调用qt_target_qml_sources() 或qt_add_qml_module()时指定的任何更高层级的选项。所有这些属性都必须在使用上述任一命令添加文件之前设置好。

QT_QML_SKIP_QMLLINT 可将源文件的TRUE 属性设置为 ，以防止该文件被纳入自动的qmllint处理。默认情况下，所有.qml 文件都会被纳入目标的lint运行中，但可以使用此选项来排除特定文件。

QT_QML_SKIP_CACHEGEN 该属性具有类似功能，当其值设置为TRUE 时，可阻止源文件被编译为字节码。请注意，该文件仍会以未编译的形式作为资源添加到target 中（参见“缓存已编译的QML源文件”）。

将源文件属性QT_QML_SKIP_QMLDIR_ENTRY 设置为TRUE ，可防止该QML或JavaScript文件作为类型被添加到QML模块的qmldir 文件中（参见“自动生成qmldir 和typeinfo文件”）。这通常用于不公开公共类型的文件，例如私有JavaScript文件。 对于名称为大写且既非 ECMAScript 模块，也未通过.pragma library 声明为无状态库的 JavaScript 文件，您应考虑使用此选项。若将其包含在qmldir 文件中，这些文件将在每个显式或隐式导入其所属模块的 QML 文档的作用域内被重新评估。

默认情况下，在生成qmldir 文件时，对于每个提供类型的.qml 文件，都会生成一个类型条目。该条目将获得版本号X.0 ，其中X 是 QML 模块的主版本号。如果 QML 模块设置了PAST_MAJOR_VERSIONS ，则也会对这些版本应用相同的模式，为每个过去的主版本X 追加X.0 。 如果文件需要为另一组版本提供类型条目（例如，该文件最初是在.0 发布后的某个次要补丁版本中添加的），请在源文件的QT_QML_SOURCE_VERSIONS 属性中指定这些版本。系统将为每个版本创建一个类型条目。

如果.qml 文件提供的类型是单例，请将其QT_QML_SINGLETON_TYPE 属性设置为TRUE 。同样，该文件的QT_QML_INTERNAL_TYPE 源属性可设置为TRUE ，以表明其提供的类型是内部类型。 类型本身的名称也可以通过QT_QML_SOURCE_TYPENAME 属性进行重写。这三项设置都会反映在生成的qmldir 文件中的类型条目中。必须在创建单例所属的模块之前设置这些源属性。

所有通过QML_FILES 或RESOURCES 列出的文件都将被添加到target 的资源中。这些资源在文件系统中的位置由一个基点和一个相对路径组成。基点默认由QML模块的资源前缀与其目标路径拼接而成，但可以通过PREFIX参数进行覆盖。 相对路径默认为相对于target 的SOURCE_DIR 目标属性的文件路径。可以通过在源文件上设置QT_RESOURCE_ALIAS 属性来覆盖此相对路径。这通常用于从不同目录收集文件，并使其在资源中显示在同一位置下。 然而，自 Qt 6.8 起，如果目标是让 Qml 模块中的所有文件都能在隐式导入中被找到，启用QTP0004通常是更好的选择。 在仍需进行此类手动配置的情况下，建议将NO_GENERATE_EXTRA_QMLDIRS 传递给qt_add_qml_module ，因为额外的qmldirs并未考虑资源文件的别名。

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
)

在上述示例中，qt_target_qml_sources_example 目标的资源最终将包含以下内容：

• /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

生成的qmldir 文件将包含以下类型条目：

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 {}