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。每个 qmldir 都会将隐式导入重定向到模块的规范资源位置，因此views/MyView.qml 可以直接使用MyButton 以及该模块中的任何其他类型，而无需显式导入。

您可以在调用qt_add_qml_module() 之前，在项目中显式设置该策略：

qt_policy(SET QTP0004 NEW)

或者，在调用qt_standard_project_setup()时，指定REQUIRES 版本为 6.8 或更高。

若未显式设置策略，Qt 6.8 会发出警告。