モジュール定義 qmldir ファイル

qmldir ファイルには、以下の2つの異なるタイプがあります：

• QMLドキュメントのディレクトリ一覧ファイル
• QMLモジュール定義ファイル

このドキュメントでは、モジュール内で利用可能な QML タイプ、JavaScript ファイル、およびプラグインを列挙する、2 番目の形式のqmldir ファイルについてのみ説明します。1 番目の形式のqmldir ファイルの詳細については、「ディレクトリ一覧 qmldir ファイル」を参照してください。

モジュール定義 qmldir ファイルの内容

qmldir ファイルは、以下のコマンドを含むプレーンテキストファイルです：

• モジュール識別子の宣言
• オブジェクト型の宣言
• 内部オブジェクト型の宣言
• JavaScriptリソースの宣言
• プラグイン宣言
• プラグインクラス名の宣言
• 型記述ファイルの宣言
• モジュールの依存関係の宣言
• モジュールのインポート宣言
• デザイナーのサポート宣言
• 推奨パスの宣言

コマンドに加えて、# で始まる行であるコメントを追加することもできます。

モジュール識別子の宣言

module <ModuleIdentifier>

モジュールのモジュール識別子を宣言します。<ModuleIdentifier> は、モジュールの (ドット区切りの URI 表記による) 識別子であり、モジュールのインストールパスと一致している必要があります。

モジュール識別子ディレクティブは、ファイルの最初の行に記述する必要があります。qmldir ファイルには、モジュール識別子ディレクティブを1つだけ記述できます。

例：

module ExampleModule

オブジェクト型の宣言

[singleton] <TypeName> <InitialVersion> <File>

モジュールによって利用可能となるQMLオブジェクト型を宣言します。

• [singleton] オプション。シングルトン型を宣言するために使用します。
• <TypeName> は、利用可能にする型です
• <InitialVersion> は、その型が提供されるモジュールのバージョンです
• <File> は、その型を定義する QML ファイルの（相対）ファイル名

qmldir ファイルには、0個以上のオブジェクト型宣言を含めることができます。ただし、モジュールの特定のバージョン内では、各オブジェクト型に一意の型名を付ける必要があります。

例：

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

内部オブジェクト型の宣言

internal <TypeName> <File>

モジュール内に存在するが、モジュールのユーザーには公開すべきではないオブジェクト型を宣言します。

qmldir ファイルには、0個以上の内部オブジェクト型の宣言を含めることができます。

例：

internal MyPrivateType MyPrivateType.qml

これは、モジュールがリモートからインポートされる場合（「リモートでインストールされた識別済みモジュール」を参照）に必要です。なぜなら、エクスポートされた型がモジュール内の非エクスポート型に依存している場合、エンジンはその非エクスポート型もロードしなければならないからです。

JavaScriptリソース宣言

<ResourceIdentifier> <InitialVersion> <File>

モジュールによって利用可能にする JavaScript ファイルを宣言します。このリソースは、指定された識別子とバージョン番号を介して利用可能になります。

qmldir ファイルには、0個以上のJavaScriptリソース宣言を含めることができます。ただし、各JavaScriptリソースは、モジュールの特定のバージョン内において一意の識別子を持つ必要があります。

例：

MyScript 1.0 MyScript.js

詳細については、JavaScriptリソースの定義および「QMLでのJavaScriptリソースのインポート」に関するドキュメントを参照してください。

プラグイン宣言

[optional] plugin <Name> [<Path>]

モジュールによって利用可能となるプラグインを宣言します。

• optional は、プラグイン自体に関連するコードを含まず、リンク先のライブラリをロードするのみであることを示します。これが指定され、かつモジュールの型がすでに利用可能である場合（つまり、ライブラリが他の手段でロード済みであることを示す場合）、QMLはプラグインをロードしません。
• <Name> はプラグインライブラリ名です。これは通常、プラットフォームに依存するプラグインバイナリのファイル名とは異なります。たとえば、ライブラリ `MyAppTypes ` は、Linux では `libMyAppTypes.so `、Windows では `MyAppTypes.dll ` となります。
• <Path> (オプション) 以下のいずれかを指定します：
  • プラグインファイルが含まれるディレクトリへの絶対パス、または
  • qmldir ファイルが含まれるディレクトリから、プラグインファイルが含まれるディレクトリまでの相対パス。

デフォルトでは、エンジンはqmldir ファイルが含まれているディレクトリ内でプラグインライブラリを検索します。（プラグインの検索パスはQQmlEngine::pluginPathList()で照会でき、QQmlEngine::addPluginPath()を使用して変更できます。）

qmldir ファイルには、0個以上の C++ プラグイン宣言を含めることができます。ただし、プラグインの読み込みは比較的負荷の高い処理であるため、クライアントは最大で 1 つのプラグインのみを指定することを推奨します。

例：

plugin MyPluginLibrary

プラグインのクラス名宣言

classname <C++ plugin class>

モジュールで使用される C++ プラグインのクラス名を指定します。

この情報は、追加機能のためにC++プラグインに依存するすべてのQMLモジュールに必須です。静的リンクでビルドされたQt Quick アプリケーションは、この情報がないとモジュールのインポートを解決できません。

型記述ファイルの宣言

typeinfo <File>

モジュールの型記述ファイルを宣言します。このファイルは、 Qt Creator が読み取り可能な、モジュールのタイプ記述ファイルを宣言します。これにより、QMLツールはモジュールのプラグインによって定義されたタイプに関する情報にアクセスできます。<File> は、.qmltypes ファイルの（相対）ファイル名です。

例:

typeinfo mymodule.qmltypes

このようなファイルがない場合、QML ツールは、プラグインで定義された型に対するコード補完などの機能を提供できない可能性があります。

モジュールの依存関係の宣言

depends <ModuleIdentifier> <InitialVersion>

このモジュールが別のモジュールに依存していることを宣言します。

例：

depends MyOtherModule 1.0

この宣言が必要となるのは、依存関係が隠されている場合のみです。例えば、あるモジュールの C++ コードを使用して（場合によっては条件付きで）QML を読み込み、その QML が他のモジュールに依存している場合などです。このような場合、アプリケーションパッケージに他のモジュールを含めるためには、depends 宣言が必要です。

モジュールインポート宣言

import <ModuleIdentifier> [<Version>]

このモジュールが別のモジュールをインポートすることを宣言します。

例：

import MyOtherModule 1.0

他のモジュールの型は、このモジュールがインポートされるのと同じ型名前空間で利用可能になります。バージョンを省略すると、他のモジュールの利用可能な最新バージョンがインポートされます。バージョンとして `auto ` を指定すると、QMLの `import ` ステートメントで指定されたこのモジュールのバージョンと同じバージョンがインポートされます。

デザイナー対応宣言

designersupported

プラグインがQt Quick Designerでサポートされている場合は、このプロパティを設定してください。デフォルトでは、プラグインはサポートされません。

Qt Quick Designer でサポートされるプラグインは、適切にテストされている必要があります。つまり、Qt Quick Designer が QML を実行するために使用する qml2puppet 内で実行された際、プラグインがクラッシュしないことが求められます。 一般的に、プラグインはQt Quick Designer内で正常に動作し、過剰なメモリ消費、qml2puppetの著しい動作遅延、あるいはQt Quick Designer内でプラグインを実質的に使用不能にするような重大な不具合を引き起こしてはなりません。

サポートされていないプラグインの項目は、Qt Quick Designer では描画されませんが、空のボックスとして表示され、プロパティの編集は可能です。

推奨されるパス宣言

prefer <Path>

このプロパティは、QMLエンジンに対し、このモジュールに関連する追加ファイルを現在のディレクトリではなく、<path>から読み込むよう指示します。これは、qmlcachegenでコンパイルされたファイルを読み込むために使用できます。

たとえば、モジュールの QML ファイルをリソースとしてリソースパス:/my/path/MyModule/ に追加することができます。その後、ファイルシステム上のファイルではなく、リソースシステム内のファイルを使用するために、qmldir ファイルにprefer :/my/path/MyModule を追加します。 その後、それらに対して qmlcachegen を使用すると、プリコンパイルされたファイルがモジュールのすべてのクライアントから利用可能になります。

バージョン管理の仕組み

特定のメジャーバージョン向けにエクスポートされたすべての QML タイプは、同じメジャーバージョンの最新バージョンで利用可能です。たとえば、あるモジュールがバージョン 1.0 でMyButton タイプを、バージョン 1.1 でMyWindow タイプを提供している場合、モジュールのバージョン1.1 をインポートするクライアントは、MyButton およびMyWindow タイプを使用できるようになります。 ただし、その逆は成り立ちません。特定のマイナーバージョン向けにエクスポートされた型は、それより古いマイナーバージョンをインポートした場合には使用できません。前述の例で言えば、クライアントがモジュールのバージョン1.0 をインポートした場合、MyButton 型のみを使用でき、MyWindow 型は使用できません。

モジュールは複数のメジャーバージョンを提供できますが、クライアントが一度にアクセスできるのは1つのメジャーバージョンだけです。たとえば、MyExampleModule 2.0 をインポートすると、そのメジャーバージョンにのみアクセスでき、以前のメジャーバージョンにはアクセスできません。異なるメジャーバージョンに属するアーティファクトを単一のディレクトリとqmldir ファイルの下に整理することも可能ですが、メジャーバージョンごとに異なるディレクトリを使用することを推奨します。 もし前者の方法（1つのディレクトリと1つのqmldir ファイル）を採用する場合は、ファイル名にバージョンサフィックスを使用するようにしてください。例えば、MyExampleModule 2.0 に属するアーティファクトは、ファイル名に.2 というサフィックスを使用できます。

そのバージョンに対して明示的にエクスポートされた型がない場合、そのバージョンをインポートすることはできません。あるモジュールがバージョン 1.0 でMyButton という型を提供し、バージョン 1.1 でMyWindow という型を提供している場合、そのモジュールのバージョン 1.2 やバージョン 2.0 をインポートすることはできません。

1つの型は、異なるマイナーバージョンの異なるファイルで定義されることがあります。この場合、クライアントによるインポート時には、最も一致するバージョンが使用されます。たとえば、あるモジュールがqmldir ファイルを通じて以下の型を指定していたとします：

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

ExampleModule の1.2 バージョンをインポートするクライアントは、MyButton11.qml で提供されるMyButton 型定義（その型の最新バージョンであるため）と、MyRectangle12.qml で提供されるMyRectangle 型定義を使用できます。

バージョン管理システムにより、特定の QML ファイルはインストールされているソフトウェアのバージョンに関係なく確実に動作します。これは、バージョン指定されたインポートではそのバージョン用の型のみがインポートされ、たとえ実際にインストールされているバージョンがそれらの識別子を提供していたとしても、他の識別子は利用可能なままになるためです。

qmldir ファイルの例

qmldir ファイルの一例を以下に示します。

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

上記のqmldir ファイルは、「ExampleModule」というモジュールを定義しています。 このファイルは、モジュールのバージョン 2.0 および 2.1 において、CustomButton という QML オブジェクト型を定義しており、バージョンごとに異なる実装が定義されています。また、クライアントによってモジュールがインポートされる際にエンジンによって読み込まれる必要があるプラグインを指定しており、そのプラグインは、QML 型システムに対して C++ で定義された様々な型を登録することができます。 Unix系システムでは、QMLエンジンはlibexamplemodule.so をQQmlExtensionPlugin として読み込もうとし、Windowsではexamplemodule.dll をQQmlExtensionPlugin として読み込みます。最後に、qmldir ファイルはJavaScriptリソースを指定しており、これはモジュールのバージョン2.0以降（同じメジャーバージョン内）がインポートされた場合にのみ利用可能です。

モジュールがQMLのインポートパスにインストールされている場合、クライアントは次のようにしてモジュールをインポートし、使用することができます：

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

上記で使用されている `CustomButton ` 型は、CustomButton21.qml ファイルで指定された定義に由来し、MathFunctions 識別子で識別される JavaScript リソースは、mathfuncs.js ファイルで定義されます。

型記述ファイル

QMLモジュールは、そのqmldir ファイル内で1つまたは複数の型情報ファイルを参照することができます。これらは通常.qmltypes という拡張子を持ち、外部ツールによって読み込まれ、C++で定義され、通常はプラグインを介してインポートされる型に関する情報を取得するために使用されます。

したがって、qmltypesファイルはQMLモジュールの機能には影響を与えません。その唯一の用途は、 Qt Creator が、コード補完やエラーチェック、その他の機能をモジュールのユーザーに提供できるようにすることにあります。

C++でQML型を定義するモジュールは、すべて型記述ファイルを同梱する必要があります。

モジュール用の qmltypes ファイルを作成する最良の方法は、ビルドシステムと `QML_ELEMENT ` マクロを使用して生成することです。これに関するドキュメントに従えば、それ以上の操作は必要ありません。`qmltyperegistrar` が自動的に `.qmltypes ` ファイルを生成します。

例：モジュールが `/tmp/imports/My/Module` にある場合、実際のプラグインバイナリと並んで `plugins.qmltypes ` というファイルが生成されるはずです。

xml-ph-0000@deepl.internal を登録するために、次の行を

typeinfo plugins.qmltypes

を/tmp/imports/My/Module/qmldir に追加して、モジュールを登録してください。