QMLドキュメント

QMLドキュメントとは、QMLドキュメントの構文に準拠した文字列のことです。ドキュメントはQMLオブジェクト型を定義します。ドキュメントは通常、ローカルまたはリモートに保存された".qml" ファイルから読み込まれますが、コード内で手動で構築することも可能です。 ドキュメントで定義されたオブジェクト型のインスタンスは、QMLコード内のComponent 、またはC++内のQQmlComponent を使用して作成できます。あるいは、オブジェクト型が特定の型名でQML型システムに明示的に公開されている場合、その型を他のドキュメントのオブジェクト宣言で直接使用することも可能です。

ドキュメント内で再利用可能なQMLオブジェクト型を定義できる機能は、クライアントがモジュール化され、可読性が高く、保守しやすいコードを記述できるようにするための重要な要素です。

Qt 5.4 以降、ドキュメントのファイル拡張子として".ui.qml" を使用することも可能になりました。QML エンジンは、これらのファイルを標準の .qml ファイルと同様に扱い、拡張子の.ui 部分は無視します。Qt Design Studio は、これらのファイルをUI ファイルとして扱います。これらのファイルには、QML 言語機能の一部のみを含めることができます。

QMLドキュメントの構造

QMLドキュメントは、インポートセクションとオブジェクト宣言セクションの2つのセクションで構成されます。ドキュメント内のインポートセクションには、そのドキュメントで使用可能なQMLオブジェクト型およびJavaScriptリソースを定義するインポート文が含まれます。オブジェクト宣言セクションでは、ドキュメントで定義されたオブジェクト型をインスタンス化する際に作成されるオブジェクトツリーを定義します。

簡単なドキュメントの例は以下の通りです。

import QtQuick 2.0

Rectangle {
    width: 300
    height: 200
    color: "blue"
}

このトピックの詳細については、「QMLドキュメントの構造」を参照してください。

QML言語の構文

ドキュメントのオブジェクト宣言セクションでは、適切なQML構文を用いて有効なオブジェクト階層を指定する必要があります。オブジェクト宣言には、カスタムオブジェクト属性の指定を含めることができます。オブジェクトのメソッド属性はJavaScript関数として指定でき、オブジェクトのプロパティ属性にはプロパティバインディング式を割り当てることができます。

有効な構文の詳細については、QMLの構文に関するドキュメントを参照してください。また、このトピックに関する詳細な情報については、QMLとJavaScriptの統合に関するドキュメントを参照してください。

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

前のセクションで簡単に説明したように、ドキュメントは暗黙的に QML オブジェクト型を定義します。QML の基本原則の一つは、オブジェクト型を定義し、それを再利用できることです。これにより、QML コードの保守性が向上し、オブジェクト階層宣言の可読性が高まり、UI 定義とロジック実装の分離が促進されます。

次の例では、クライアント開発者がファイル内のドキュメントを使用して、Button 型を定義しています：

// Button.qml
import QtQuick

Rectangle {
    width: 100; height: 100
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

これにより、Button 型をアプリケーション内で使用できるようになります：

// application.qml
import QtQuick

Column {
    Button { width: 50; height: 50 }
    Button { x: 50; width: 100; height: 50; color: "blue" }
    Button { width: 50; height: 50; radius: 8 }
}

このトピックに関する詳細については、ドキュメント内でのオブジェクト型の定義に関するドキュメントを参照してください。

リソースの読み込みとネットワーク透過性

QMLはネットワーク透過的であることに留意することが重要です。アプリケーションは、ローカルパス上のドキュメントと同様に、リモートパス上のドキュメントも簡単にインポートできます。実際、url のプロパティにはリモートまたはローカルのURLを割り当てることができ、QMLエンジンが関連するネットワーク通信をすべて処理します。

インポートにおけるネットワーク透過性の詳細については、「ネットワーク透過性」のドキュメントを参照してください。

スコープと名前解決

ドキュメント内の式には通常、オブジェクトまたはオブジェクトのプロパティが含まれます。複数のオブジェクトが定義される可能性があり、異なるオブジェクトが同じ名前のプロパティを持つ場合もあるため、QMLでは事前に定義されたシンボル解決のセマンティクスを定義する必要があります。このトピックに関する詳細については、スコープとシンボル解決のページをご覧ください。