Back to Qt.io
Contact Us Blog Download Qt
本页内容

qt_import_qml_plugins qt_target_compile_qml_to_cpp

qt_query_qml_module

检索有关 QML 模块的信息。

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

find_package(Qt6 REQUIRED COMPONENTS Qml)

该命令于 Qt 6.3 中引入。

语法

qt_query_qml_module(
    target
    [URI uri_var]
    [VERSION version_var]
    [PLUGIN_TARGET plugin_target_var]
    [TARGET_PATH target_path_var]
    [MODULE_RESOURCE_PATH module_resource_path_var]
    [QMLDIR qmldir_var]
    [TYPEINFO typeinfo_var]
    [QML_FILES qml_files_var]
    [QML_FILES_DEPLOY_PATHS qml_files_deploy_paths_var]
    [QML_FILES_PREFIX_OVERRIDES qml_files_prefix_overrides_var]
    [RESOURCES resources_var]
    [RESOURCES_DEPLOY_PATHS resources_deploy_paths_var]
    [RESOURCES_PREFIX_OVERRIDES resources_prefix_overrides_var]
)

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

描述

该命令用于获取有关 QML 模块target 的信息。该target 必须已由qt_add_qml_module() 函数创建，或已作为该函数的参数传递。target 不能是导入的目标。

该命令提供的信息使调用者能够部署单个 QML 模块的所有部分。项目应使用标准的install(TARGETS)命令安装target 及其关联的插件目标（如果该模块有插件目标且其与底层target 分离）。其余部分均可通过install(FILES) 进行部署。

参数

每个可选参数指定一个变量名称，用于存储相应的 QML 模块属性。

URI 和VERSION 分别提供模块的 URI 和版本号。

PLUGIN_TARGET 可用于获取 QML 模块的插件目标名称。并非所有 QML 模块都有插件，因此此选项返回的值可能是空字符串。如果 QML 模块没有单独的后端目标，则target 将与插件目标相同。

TARGET_PATH 是URI 中将点 (.) 替换为正斜杠 (/) 后的路径。它表示在 QML 模块基础安装目录下的路径，该 QML 模块的qmldir 文件（以及可能的其他文件）应部署在此路径下。QML 模块安装目录作为 QML 导入路径，QML 引擎将在此路径下查找 QML 模块。qt_generate_deploy_qml_app_script()函数使用的默认基础 QML 模块安装目录为qml 。使用部署脚本的项目可以使用QT_DEPLOY_QML_DIR变量，而无需硬编码此位置（另请参阅QT_DEPLOY_PREFIX）。

MODULE_RESOURCE_PATH 提供可找到 QML 模块内联文件的资源路径。该路径由qt_add_qml_module() 的 `RESOURCE_PREFIX ` 与模块的 `TARGET_PATH` 拼接而成。该查询值不应用于部署，但在需要时，可帮助将资源路径与文件系统位置进行匹配。

QMLDIR 提供qmldir 文件的路径。部署 QML 模块时，应将该文件复制到目标路径。在部署脚本中，可通过${QT_DEPLOY_PREFIX}/${QT_DEPLOY_QML_DIR} 获取此位置。

TYPEINFO 提供模块的 typeinfo 文件路径（如果存在）。如果模块没有 typeinfo 文件，则该值将为空字符串。typeinfo 文件应部署到与qmldir 文件相同的路径下。

QML_FILES 提供通过以下任一方法添加到 QML 模块中的所有文件列表：

所有文件都将以绝对路径记录。

QML_FILES_DEPLOY_PATHS 该列表的元素数量与QML_FILES 完全一致。QML_FILES_DEPLOY_PATHS 列表的每个元素都是目标路径下的子路径，QML_FILES 中对应的元素应部署在此路径下。QML_FILES_DEPLOY_PATHS 中的路径包含文件名，因为由于使用了资源别名（参见QT_RESOURCE_ALIAS），该路径中的文件名可能与QML_FILES 中的文件名不同。

QML_FILES_DEPLOY_PATHS 中的条目也可以是空字符串。使用qt_target_qml_sources()并指定自定义PREFIX 添加的任何文件都不会有部署路径，因为使用自定义前缀通常意味着该文件位于QML模块的目标路径之外。

QML_FILES_PREFIX_OVERRIDES 提供另一个列表，其元素数量与QML_FILES 完全相同。如果按照前一段所述使用自定义前缀添加了文件，则QML_FILES_PREFIX_OVERRIDES 列表中对应的条目将包含所使用的自定义前缀。对于所有其他文件，其列表条目将为空字符串。

注意：作为特例， 如果QML_FILES 列表中仅包含一个文件，那么QML_FILES_DEPLOY_PATHS 或QML_FILES_PREFIX_OVERRIDES 可能为空字符串，具体取决于该文件是否带有自定义前缀。这是因为 CMake 表示列表和字符串的方式决定了无法区分空字符串与仅包含一个空元素的列表。

RESOURCES 、RESOURCES_DEPLOY_PATHS 和RESOURCES_PREFIX_OVERRIDES 选项与上文讨论的QML_FILES 选项类似。RESOURCES 提供了一个列表，其中包含作为RESOURCES 参数添加到 QML 模块中的所有文件，这些参数是通过qt_add_qml_module()或qt_target_qml_sources() 传递的。所有路径均为绝对路径。RESOURCES_DEPLOY_PATHS 和RESOURCES_PREFIX_OVERRIDES 的含义及用法分别与QML_FILES_DEPLOY_PATHS 和QML_FILES_PREFIX_OVERRIDES 相同。

示例

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml)

set(module_name "MyThings")
qt_add_qml_module(${module_name}
    URI My.Things
    VERSION 1.3
    RESOURCE_PREFIX org.mycompany/imports
    QML_FILES
        First.qml
        Second.qml
    RESOURCES
        Third.txt
)

qt_query_qml_module(${module_name}
    URI module_uri
    VERSION module_version
    PLUGIN_TARGET module_plugin_target
    TARGET_PATH module_target_path
    QMLDIR module_qmldir
    TYPEINFO module_typeinfo
    QML_FILES module_qml_files
    QML_FILES_DEPLOY_PATHS qml_files_deploy_paths
    RESOURCES module_resources
    RESOURCES_DEPLOY_PATHS resources_deploy_paths
)

message("My QML module URI is: ${module_uri}")
message("My QML module version is: ${module_version}")

# Install the QML module backing library
set(staging_prefix "staging")
install(TARGETS ${module_name}
    ARCHIVE DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}"
    LIBRARY DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}"
    RUNTIME DESTINATION "${staging_prefix}/${CMAKE_INSTALL_BINDIR}"
)
set(module_dir "${staging_prefix}/qml/${module_target_path}")

# Install the QML module runtime loadable plugin
install(TARGETS "${module_plugin_target}"
    LIBRARY DESTINATION "${module_dir}"
    RUNTIME DESTINATION "${module_dir}"
)

# Install the QML module meta information.
install(FILES "${module_qmldir}"   DESTINATION "${module_dir}")
install(FILES "${module_typeinfo}" DESTINATION "${module_dir}")

# Install QML files, possibly renamed.
list(LENGTH module_qml_files num_files)
math(EXPR last_index "${num_files} - 1")
foreach(i RANGE 0 ${last_index})
    list(GET module_qml_files       ${i} src_file)
    list(GET qml_files_deploy_paths ${i} deploy_path)
    get_filename_component(dst_name "${deploy_path}" NAME)
    get_filename_component(dest_dir "${deploy_path}" DIRECTORY)
    install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}")
endforeach()

# Install resources, possibly renamed.
list(LENGTH module_resources num_files)
math(EXPR last_index "${num_files} - 1")
foreach(i RANGE 0 ${last_index})
    list(GET module_resources       ${i} src_file)
    list(GET resources_deploy_paths ${i} deploy_path)
    get_filename_component(dst_name "${deploy_path}" NAME)
    get_filename_component(dest_dir "${deploy_path}" DIRECTORY)
    install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}")
endforeach()

qt_import_qml_plugins qt_target_compile_qml_to_cpp

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