識別済みモジュール

識別済みモジュールとは、インストールされており、QMLエンジンがドット区切りの識別子文字列形式のURIによって識別できるモジュールのことです。このURIは、モジュールが自身のqmldir ファイル内で指定する必要があります。これにより、ローカルファイルシステム上のどの場所にモジュールが存在しても、一意の識別子を使用してそのモジュールをインポートできるようになります。

識別済みモジュールをインポートする際は、引用符で囲まれていない識別子と、オプションのバージョン番号が使用されます：

import QtQuick
import com.mycompany.qml.mymodule 1.0

識別されたモジュールは、QMLエンジンによって検出されるために、インポートパスにインストールされている必要があります。

構文上、URIのドットで区切られた各セグメントは、正規なECMAScript識別子名でなければなりません。つまり、例えば、セグメントは数字で始まってはならず、また「-」（マイナス）文字を含んではなりません。 URIはディレクトリ名に変換されるため、ラテンアルファベットの英数字、アンダースコア、およびドットに限定する必要があります。

ローカルにインストールされた識別済みモジュール

QML および/または C++ ファイルのディレクトリは、モジュールのメタデータを含むqmldir ファイルが含まれており、かつ QML のインポートパスにインストールされていれば、識別済みモジュールとして共有できます。 ローカルファイルシステム上の任意の QML ファイルは、モジュールの URI を参照するimportステートメントを使用することで、このディレクトリをモジュールとしてインポートでき、そのファイルは、モジュールによって定義されたQML オブジェクト型およびJavaScript リソースを使用できるようになります。

モジュールの `qmldir ` ファイルは、URI のドット区切り識別子文字列を反映したインポートパス内のディレクトリ構造に配置する必要があります。識別子内の各ドット（「.」）は、ディレクトリツリー内のサブレベルを表します。たとえば、モジュール `com.mycompany.mymodule ` の `qmldir ` ファイルは、インポートパス内のどこかに `com/mycompany/mymodule/qmldir ` というサブパスに配置する必要があります。

モジュールの異なるバージョンを、そのモジュール自身のサブディレクトリに保存することが可能です。例えば、モジュールのバージョン 2.1 は、com/mycompany/mymodule.2/qmldir またはcom/mycompany/mymodule.2.1/qmldir の下に配置できます。エンジンは、最も適合するモジュールを自動的に読み込みます。

あるいは、qmldirファイル自体内で異なるタイプのバージョン管理を定義することも可能ですが、この方法では、そのようなモジュールの更新が難しくなる可能性があります（更新手順の一環として、qmldir ファイルのマージを行う必要があるため）。

例

以下の QML プロジェクトのディレクトリ構造を考えてみましょう。最上位ディレクトリ `myapp` の下には、`mycomponents` という名前のサブディレクトリに一連の共通 UI コンポーネントがあり、`main` という名前のサブディレクトリにメインのアプリケーションコードがあります。具体的には以下の通りです。

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

mycomponents ディレクトリを識別可能なモジュールとして利用可能にするには、そのディレクトリに、モジュール識別子を定義し、モジュールが提供するオブジェクトタイプを記述したqmldir ファイルを含める必要があります。たとえば、モジュールのバージョン 1.0 でCheckBox 、DialogBox 、およびSlider の各タイプを利用可能にする場合、qmldir ファイルには次のように記述します：

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

さらに、インポートパス内のqmldir ファイルの場所は、モジュールのドット区切り識別子文字列と一致している必要があります。たとえば、最上位のmyapp ディレクトリがC:\qml\projects にあり、モジュールが「myapp.mycomponents」として識別される場合、次のようにします：

• C:\qml\projects パスをインポートパスに追加する必要があります
• qmldir ファイルは以下の場所に配置する必要があります。C:\qml\projects\myapp\mycomponents\qmldir

この設定が完了すると、ローカルファイルシステム上のどこにあるQMLファイルでも、そのURIと適切なバージョンを指定することで、モジュールをインポートできるようになります：

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

リモートでインストールされた識別済みモジュール

識別済みモジュールは、ネットワークリソースとしてもアクセス可能です。前の例で、C:\qml\projects ディレクトリがhttp://www.some-server.com/qml/projects としてホストされ、この URL が QML のインポートパスに追加されていた場合、まったく同じ方法でモジュールをインポートできます。

なお、ファイルがネットワーク経由でモジュールをインポートする場合、そのファイルはモジュールによって提供される QML および JavaScript リソースにのみアクセスでき、モジュール内の C++ プラグインによって定義された型にはアクセスできません。

識別済みモジュールのセマンティクス

識別されたモジュールに対しては、QML エンジンにより以下の保証が提供されます。

• 他のモジュールは、そのモジュールの名前空間内の型を変更または上書きできない
• 他のモジュールは、そのモジュールの名前空間に新しい型を登録できない
• クライアントによる型名の使用は、指定されたバージョン管理とインポート順序に応じて、所定の型定義に決定論的に解決されます

これにより、モジュールを使用するクライアントは、モジュール内で定義されたオブジェクト型が、モジュール作成者が文書化したとおりに動作することを確実に保証されます。

識別済みモジュールには、いくつかの制限があります:

• 識別されたモジュールは、QML のインポートパスにインストールされなければなりません
• module identifierディレクティブで指定されたモジュール識別子は、モジュールのインストールパスと一致している必要があります（QML インポートパスを基準とし、ディレクトリ区切り文字はピリオドに置き換えられます）
• モジュールは、その型をモジュール識別子の型名前空間に登録しなければならない
• モジュールは、他のモジュールの名前空間に型を登録してはならない

たとえば、識別済みモジュールが `$QML_IMPORT_PATH/ExampleModule` にインストールされる場合、モジュール識別子ディレクティブは次のようになります:

module ExampleModule

strict モジュールが `$QML_IMPORT_PATH/com/example/CustomUi` にインストールされている場合、モジュール識別子ディレクティブは次のようになります：

module com.example.CustomUi

これにより、クライアントは次のインポート文を使用して上記のモジュールをインポートできるようになります：

import com.example.CustomUi