QML モジュール

QMLモジュールは、モジュールをインポートするクライアントが利用できる、タイプネームスペース内のバージョン管理された型およびJavaScriptリソースを提供します。モジュールが提供する型は、プラグイン内のC++で定義することも、QMLドキュメントで定義することもできます。モジュールはQMLのバージョン管理システムを利用しており、これによりモジュールを個別に更新することが可能になります。

QMLモジュールを定義することで、以下のことが可能になります：

• プロジェクト内での共通QML型の共有 — 例えば、異なるウィンドウで使用されるUIコンポーネントのグループなど
• QMLベースのライブラリの配布
• 個別の機能をモジュール化することで、アプリケーションが個々のニーズに必要なライブラリのみを読み込めるようにする
• 型やリソースのバージョン管理。これにより、クライアントのコードを壊すことなく、モジュールを安全に更新できます

最新の QML モジュール

QML モジュールは、CMake API、特にqt_add_qml_module を使用して定義するのが最適です。以下のセクションでは、最新の QML モジュールを作成するためのあらゆる側面について説明します。

QMLドキュメントによるオブジェクト型の定義

QML型はQMLドキュメント内で直接定義することができ、これは再利用可能なコンポーネントを作成する最も簡単な方法です。大文字で始まる各QMLファイルは、同じモジュール内の他のQMLファイルで使用できる型を自動的に定義します。

C++ からの QML 型の定義

パフォーマンスの向上や低レベルAPIへのアクセスを目的として、C++で型を定義し、それをQMLに公開することも可能です。C++型では、静的型付けとコンパイルの利点を活かしつつ、プロパティ、メソッド、シグナルを完全に制御できます。

CMake による統合

qt_add_qml_module というCMakeコマンドを使用すると、QMLファイル、C++型、およびリソースを1つのまとまりのあるモジュールに統合できます。このコマンドは、型の登録、リソースのコンパイル、QMLツールとの統合を自動的に処理するため、現代的なQMLモジュール開発において推奨されるアプローチとなっています。

QMLモジュールの最新化

このガイドは、古いCMakeベースのQmlモジュールを新しいバージョンのQtへ移行するための手引きです。新しいCMakeポリシーへの適応方法や、時代遅れの手法を避ける方法について解説しています。

QMLモジュールの微調整

『QMLモジュールの作成』に記載されている高度なモジュール設定オプションを使用すると、モジュールの動作をきめ細かく制御できます。これには、同じバイナリへの複数のQMLモジュールの追加、バージョン管理、カスタムディレクトリ構成、およびQMLプラグインに関する高度なトピックが含まれます。

旧式のQMLモジュール

モジュールは、モジュール定義ファイル（qmldirファイル）によって定義されます。各モジュールには、その識別子となるタイプネームスペースが関連付けられています。モジュールは、QMLオブジェクト型（QMLドキュメントまたはC++プラグインによって定義される）やJavaScriptリソースを提供でき、クライアントからインポートされる可能性があります。

モジュールを定義するには、開発者はそのモジュールに属するさまざまなQMLドキュメント、JavaScriptリソース、およびC++プラグインを単一のディレクトリにまとめ、適切なモジュール定義qmldirファイルを作成して、そのディレクトリ内に配置する必要があります。その後、そのディレクトリをモジュールとしてQMLのインポートパスにインストールできます。

なお、プロジェクト内で共通のQML型を共有する方法は、モジュールの定義だけではありません。この目的には、単純なQMLドキュメントディレクトリのインポートも使用できます。

サポートされているQMLモジュールタイプ

QMLでは、2種類のモジュールがサポートされています：

• 識別済みモジュール
• レガシーモジュール（非推奨）

識別済みモジュールは、識別子を明示的に定義し、QMLのインポートパスにインストールされます。 識別済みモジュールは（型のバージョン管理により）保守性が高く、QMLエンジンによって型登録の保証が提供されますが、これはレガシーモジュールには提供されません。レガシーモジュールは、レガシーコードがQMLの最新バージョンでも引き続き動作するようにするためにのみサポートされており、クライアントは可能な限り使用を避けるべきです。

クライアントは、QMLドキュメント内またはJavaScriptファイルからQMLモジュールをインポートできます。このトピックの詳細については、QMLモジュールのインポートに関するドキュメントを参照してください。

C++プラグインでの型と機能の提供

C++で実装されたロジックが多数あるアプリケーションや、C++で型を定義してQMLに公開しているアプリケーションでは、QMLプラグインを実装することが望ましい場合があります。また、QML拡張モジュールの開発者は、パフォーマンスの向上や柔軟性の向上のために、（QMLドキュメントで定義するのではなく）C++プラグインで一部の型を実装したいと考えるかもしれません。

QML用のすべてのC++プラグインには、QMLエンジンがプラグインをロードする際に呼び出される初期化関数が用意されています。この初期化関数では、プラグインが提供するすべての型を登録する必要がありますが、それ以外の処理（例えば、QObjectのインスタンス化など）を行ってはなりません。

詳細については、「QML用C++プラグインの作成」を参照してください。