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 では、ポリシーを明示的に設定していない場合、警告が表示されます。