QTP0004

QML 模块中包含 QML 文件的额外目录需要额外的 qmldir 文件。

此策略在 Qt 6.8 中引入。它会导致构建系统为 QML 模块中包含 QML 文件的每个额外目录生成一个额外的 qmldir 文件。

启用此策略可确保模块中每个 QML 组件的隐式导入与模块本身相同。这意味着所有组件无需显式导入模块即可相互看到。

OLD 该策略的行为是只为模块的根目录生成 qmldir 文件。

NEW 该策略的行为是，为模块中包含 QML 文件的每个目录生成一个单独的 qmldir 文件。每个生成的 qmldir 文件都包含一个prefer 指令，用于将隐式导入重定向到模块的规范资源位置。

模块背景

QML 引擎总是隐式导入 QML 文件所在的目录。对于模块根目录下的文件，隐式导入会解析到模块本身，因此所有同级组件都是可见的。但是，当 QML 文件放在子目录中时，隐式导入会解析到该子目录。如果不添加显式import 语句，子目录中的组件就无法看到同一模块中的其他组件。这也是经常出现错误的原因之一。

使用NEW 行为时，编译系统会在每个子目录中生成一个 qmldir 文件，其中包含指向模块规范资源位置的prefer 指令。这样，模块中每个 QML 文件的隐式导入就等同于模块本身的导入，因此所有组件无论在哪个目录下都能相互找到。

示例

考虑一个模块，其 QML 文件跨越多个子目录：

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Main.qml
        controls/MyButton.qml
        views/MyView.qml
)

views/MyView.qml 通常需要使用controls 子目录中的MyButton 。如果使用OLD 行为，就会无声无息地失败：views/MyView.qml 隐式导入了views 子目录，因此除非明确添加import MyModule ，否则找不到MyButton 。

使用NEW 行为时，会在controls 和views 子目录中生成一个额外的 qmldir。每个子目录都会将隐式导入重定向到模块的规范资源位置，因此views/MyView.qml 可以使用MyButton 以及模块中的任何其他类型，而无需显式导入。

在调用qt_add_qml_module() 之前，可在项目中明确设置策略：

qt_policy(SET QTP0004 NEW)

或者，使用REQUIRES 6.8 或更高版本调用qt_standard_project_setup()。

如果不明确设置策略，Qt 6.8 会发出警告。