QML 模块的现代化改造

在 Qt 6 中，Qml 模块变得更加强大且易于使用。以下各节将介绍如何对已使用qt_add_qml_module 的 Qml 模块进行现代化改造。

另请参阅《将 QML 模块移植到 CMake》，了解如何将 QML 模块移植到qt_add_qml_moduleCMake API。

使用 qt_standard_project_setup

qt_standard_project_setup除其他功能外，还会设置现代 QML 模块所需的Qt CMake 策略。若要使您的 QML 模块现代化并遵循最佳实践，请在项目顶级CMakeLists.txt 文件中，于任何qt_add_qml_module调用之前调用qt_standard_project_setup：

qt_standard_project_setup(REQUIRES 6.8)

使用新的标准资源路径前缀

随着QTP0001 的发布，QML 模块的标准资源路径已从:/ 移至:/qt/qml 。请勿使用自定义资源前缀，也不要在引擎中扩展导入路径。请从所有qt_add_qml_module调用中移除所有RESOURCE_PREFIX 参数，同时移除所有对QQmlEngine::addImportPath 或类似函数的调用。请将 C++ 和 QML 代码中的所有 qrc 路径更改为使用新的资源路径前缀：

// C++ usages like:
QUrl someUrl("qrc:/MyQmlModule/MyResource1.png");
// need to be changed to
QUrl someUrl("qrc:/qt/qml/MyQmlModule/MyResource1.png");

// QML usages like:
":/MyQmlModule/MyResource1.png"
// need to be changed to
":/qt/qml/MyQmlModule/MyResource1.png"

另请参阅《在 Qml 中使用 Qt 资源系统》。

使用 `loadFromModule` 加载 QML 文件

使用默认导入路径时，您可以使用loadFromModule 方法，例如QQmlApplicationEngine::loadFromModule 、QQuickView::loadFromModule 或QQmlComponent::loadFromModule 等。

使用 `loadFromModule ` 加载您的 QML 文件，例如：

engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");

将 OUTPUT_DIRECTORY 和 IMPORT_PATH 替换为 DEPENDENCIES TARGET

请避免在qt_add_qml_module 中设置IMPORT_PATH 。相反，请使用DEPENDENCIES TARGET 来声明对当前导入路径中无法找到的其他 QML 模块的依赖关系。

使用 `DEPENDENCIES TARGET ` 还能省去 `QT_QML_OUTPUT_DIRECTORY ` CMake 变量以及 `qt_add_qml_module` 的 `OUTPUT_DIRECTORY ` 参数，因此请删除它们的定义和用法。

例如：

### in the CMakeLists.txt file defining the dependent QML module:
# don't set QT_QML_OUTPUT_DIRECTORY and remove lines like these:
set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml)

qt_add_qml_module(MyThirdPartyQmlLibraryDependency
    URI MyThirdPartyQmlLibraryDependency
    ....
    # custom output paths are obsolete due to DEPENDENCIES TARGET below, so remove:
    OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml
}

### in the CMakeLists.txt file defining the QML module that uses the dependency:
qt_add_qml_module(MyQmlLibrary
    URI MyQmlModule
    ...
    # replace import paths like these:
    IMPORT_PATH ${CMAKE_CURRENT_BINARY_DIR}/thirdparty/qml
    # with:
    DEPENDENCIES TARGET MyThirdPartyQmlLibraryDependency
}

注意：您 可能需要在 CMakeLists.txt 中调用qt_add_qml_module之前先调用add_subdirectory() ，以便DEPENDENCIES TARGET 能找到该目标。

有关如何声明模块依赖关系的更多信息，请参阅《声明模块依赖关系》。

另请参阅 《Qt Qml 的变更》和《将 QML 模块移植到 CMake》。

通过 CMake 将一切整合起来 QML 模块的精细调整

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