QMLドキュメントの構造

QMLドキュメントとは、以下の3つの部分で構成される、独立したQMLソースコードのことです：

• オプションのプラグマ一覧
• インポート文
• 単一のルートオブジェクト宣言

慣例により、インポートとオブジェクト階層の定義の間には、1行の空白行が挿入されます。

QMLドキュメントは常にUTF-8形式でエンコードされます。

プラグマ

プラグマとは、QML エンジン自体に対する指示であり、現在のファイル内のオブジェクトの特定の特性を指定したり、エンジンによるコードの解釈方法を変更したりするために使用できます。以下のプラグマについて、以下で詳しく説明します。

シングルトン

pragma Singleton QMLドキュメントのルートに定義されたコンポーネントをシングルトンとして宣言します。詳細については、「QMLにおけるシングルトン」を参照してください。

ListPropertyAssignBehavior

このプラグマを使用すると、QMLドキュメント内で定義されたコンポーネントにおいて、リストプロパティへの代入がどのように処理されるかを定義できます。デフォルトでは、リストプロパティへの代入はリストに要素を追加する形で行われます。 値 `Append` を使用することで、この挙動を明示的に指定できます。あるいは、`Replace` を使用してリストプロパティの内容を常に上書きするように指定したり、`ReplaceIfNotDefault` を使用して、そのプロパティがデフォルトプロパティでない場合にのみ上書きするように指定したりすることもできます。

ドキュメント `Base.qml` 内の基底型を例に考えてみましょう：

pragma ListPropertyAssignBehavior: ReplaceIfNotDefault
import QtQuick

Item {
    objectName: "outer"

    default property list<Item> d: [
        Item { objectName: "inner" }
    ]

    property list<Item> notDefault: [
        Item { objectName: "one" }
    ]
}

この場合、Base から派生させてリストプロパティを変更すると、ListPropertyAssignBehavior が有効になります。この場合：

Base {
    // The new item is appended to the list even though you're assigning.
    // The (default) property "d" now contains "inner" and "inner2".
    d: [
        Item { objectName: "inner2" }
    ]

    // The list is replaced by the list given here.
    // The (non-default) property "notDefault" now contains only "two".
    notDefault: [
        Item { objectName: "two" }
    ]
}

ListPropertyAssignBehavior が指定されていない場合、またはAppend が指定されている場合、「two」オブジェクトは代わりにnotDefault プロパティに追加され、結果として「one」と「two」の両方を含むリストになります。

Replace が指定された場合、デフォルトのプロパティ「d」の内容も置き換えられ、結果として「inner2」のみを含むリストになります。

class MyType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE

    Q_PROPERTY(QQmlListProperty<QObject> a READ a)
    [...]
};

ComponentBehavior

同じ QML ファイル内に複数のコンポーネントを定義することができます。QML ファイルのルートスコープはコンポーネントであり、さらに、QQmlComponent 型の要素、明示的または暗黙的にプロパティとして作成された要素、あるいはインラインコンポーネントが存在する場合があります。これらのコンポーネントはネストされています。各内部コンポーネントは、特定の 1 つの外部コンポーネント内に存在します。 ほとんどの場合、外側のコンポーネントで定義されたIDは、そのネストされたすべての内部コンポーネントからアクセス可能です。ただし、コンポーネントから、利用可能なIDが異なる別のコンテキストで要素を作成することもできます。そうすると、外側のIDが利用可能であるという前提が破られます。 したがって、エンジンおよびQMLツールは、一般的に、実行時にそのようなIDがどのような型に解決されるか（もし解決されるとしても）を事前に把握することはできません。

ComponentBehavior プラグマを使用すると、ファイル内で定義されたすべての内部コンポーネントが、元のコンテキスト内でのみオブジェクトを作成するように制限できます。コンポーネントがそのコンテキストにバインドされている場合、同じファイル内の外部コンポーネントの ID をそのコンポーネント内で安全に使用できます。その場合、QML ツールは、特定の型を持つ外部 ID が利用可能であると想定します。

コンポーネントをそのコンテキストにバインドするには、Bound 引数を指定します：

pragma ComponentBehavior: Bound

これは、名前が競合する場合、バインドされたコンポーネントの外で定義されたIDが、そのコンポーネントから作成されたオブジェクトのローカルプロパティよりも優先されることを意味します。 そうでなければ、モジュールの新しいバージョンでコンポーネントにプロパティが追加される可能性があるため、IDを使用することは実際には安全ではありません。コンポーネントがバインドされていない場合、ローカルプロパティはコンポーネントの外で定義されたIDよりも優先されますが、コンポーネント内で定義されたIDについては優先されません。

以下の例では、矩形の色（color）のrプロパティではなく、id がcolor であるListView オブジェクトのrプロパティが出力されます。

pragma ComponentBehavior: Bound
import QtQuick

ListView {
 id: color
 property int r: 12
 model: 1

 delegate: Rectangle {
  Component.onCompleted: console.log(color.r)
 }
}

ComponentBehavior のデフォルト値はUnbound です。これを明示的に指定することも可能です。将来のQtバージョンでは、デフォルト値がBound に変更される予定です。

コンテキストにバインドされたデリゲートコンポーネントは、インスタンス化時に独自のプライベートコンテキストを受け取りません。つまり、この場合、モデルデータは必須プロパティを介してのみ渡すことができます。コンテキストプロパティを介してモデルデータを渡すことはできません。これは、例えばInstantiator 、Repeater 、ListView 、TableView 、GridView 、TreeView へのデリゲート、および一般的に内部で `DelegateModel ` を使用するすべてのコンポーネントに関係します。

たとえば、次のような記述は機能しません：

pragma ComponentBehavior: Bound
import QtQuick

ListView {
 delegate: Rectangle {
     color: model.myColor
 }
}

ListView のdelegate プロパティはコンポーネントです。したがって、ここではRectangle の周囲にComponent が暗黙的に作成されます。そのコンポーネントはそのコンテキストにバインドされています。ListView によって提供されるcontextプロパティmodel を受け取りません。これを機能させるには、次のように記述する必要があります：

pragma ComponentBehavior: Bound
import QtQuick

ListView {
 delegate: Rectangle {
     required property color myColor
     color: myColor
 }
}

QMLファイル内ではコンポーネントをネストすることができます。このプラグマは、ネストの深さに関わらず、ファイル内のすべてのコンポーネントに適用されます。

FunctionSignatureBehavior

このプラグマを使用すると、関数の型注釈の処理方法を変更できます。Qt 6.7 以降、関数の呼び出し時に型注釈が強制されるようになりました。以前は、QML スクリプトコンパイラのみが型注釈を強制しており、インタプリタおよび JIT コンパイラはそれらを無視していました。 型注釈を常に強制することは、以前のバージョンと比較して動作の変更となります。以前のバージョンでは、引数が一致しない関数を呼び出すことが可能だったからです。

値として `Ignored ` を指定すると、QMLエンジンとQMLスクリプトコンパイラは型アノテーションをすべて無視するようになり、これによりインタプリタとJITの6.7以前の挙動が復元されます。その結果、事前にC++へコンパイルされるコード量が減り、より多くのコードがインタプリタ処理またはJITコンパイルされることになります。

Enforced を値として指定すると、デフォルト設定が明示的に指定されます。つまり、型注釈は常に強制されます。

NativeMethodBehavior

歴史的な理由により、取得元とは異なるthis オブジェクトを使用してC++メソッドを呼び出すと、正常に動作しません。元のオブジェクトがthis オブジェクトとして使用されます。pragma NativeMethodBehavior: AcceptThisObject を設定することで、指定されたthis オブジェクトの使用を許可できます。RejectThisObject を指定すると、従来の挙動が維持されます。

この例については、「C++ メソッドと『this』オブジェクト」のセクションを参照してください。

ValueTypeBehavior

このプラグマを使用すると、値型およびシーケンスの処理方法を変更できます。

通常、JavaScript コードでは小文字の名前を型名として使用することはできません。値型の名前は小文字であるため、これは問題となります。 このプラガマの値として `Addressable ` を指定することで、この動作を変更できます。`Addressable ` を指定すると、JavaScript の値を特定の名前付き値型に明示的に強制変換することができます。これは、オブジェクト型の場合と同様に、as 演算子を使用して行います。さらに、instanceof 演算子を使用して値型をチェックすることもできます。

pragma ValueTypeBehavior: Addressable
import QtQml

QtObject {
 property var a
 property real b: (a as rect).x
 property bool c: a instanceof rect

 property var rect // inaccessible. "rect" is a type name.
}

上記の例では、rect が型名となっているため、rect という名前のプロパティはすべて隠蔽されます。

目的の型への明示的なキャストは、ツールの動作を助けます。これにより、Qt Quick コンパイラは、そうでなければ生成できなかったであろう効率的なコードを生成できるようになります。qmllintを使用すると、そのような箇所を見つけることができます。

また、デフォルトの挙動を明示的に指定するために使用できるInaddressable 値もあります。

ValueTypeBehavior プラグマには、Qt 6.8で導入されたAssertable という別の属性もあります。Qt 6.6および6.7における誤りのため、上記のa as rect は、a がrect であるかどうかを検証するだけでなく、a が互換性のある型である場合にrect を構築してしまいます。これは明らかに、型アサーションがすべきことではありません。Assertable を指定することで、この挙動を防ぎ、値型に対する型アサーションを単に型の一致確認のみに制限できます。as と組み合わせて値型を使用する場合は、常にこれを指定する必要があります。いずれにせよ、値型の型アサーションが失敗した場合、結果はundefined となります。

instanceof は、すべての可能な型変換ではなく、継承のみをチェックするため、この問題はありません。

値型およびシーケンスは、一般的に参照として扱われます。つまり、プロパティから値型のインスタンスを取得してローカル変数に代入し、そのローカル変数を変更すると、元のプロパティも変更されます。さらに、元のプロパティを明示的に書き換えると、ローカル変数も更新されます。 この挙動は多くの場面で直感に反するため、これに依存すべきではありません。ValueTypeBehavior プラグマのCopy およびReference の値は、この挙動を変更するための実験的なオプションです。これらを使用すべきではありません。Copy を指定すると、すべての値型が実際のコピーとして扱われます。Reference を指定すると、デフォルトの挙動が明示的に指定されます。

Copy を使用するのではなく、副作用の影響を受けた可能性がある場合はいつでも、値型やシーケンスへの参照を明示的に再読み込みする必要があります。 副作用は、関数を呼び出したり、プロパティを命令的に設定したりするたびに発生する可能性があります。qmllintはこの点に関するガイダンスを提供しています。たとえば、次のコードでは、width を書き込んだ後、変数f が副作用の影響を受けます。これは、width が変更された際に、派生型またはBinding 要素内のバインディングによってfont が更新される可能性があるためです。

import QtQuick
Text {
 function a() : real {
     var f = font;
     width = f.pixelSize;
     return f.pointSize;
 }
}

この問題に対処するには、width への書き込み操作中にf を保持しないようにします：

import QtQuick
Text {
 function a() : real {
     var f = font;
     width = f.pixelSize;
     f = font;
     return f.pointSize;
 }
}

これは、次のように短縮できます：

import QtQuick
Text {
 function a() : real {
     width = font.pixelSize;
     return font.pointSize;
 }
}

font プロパティを再度取得することはコストがかかると思われるかもしれませんが、実際には QML エンジンは値型参照から読み取るたびに自動的にその値を更新します。したがって、これは最初のバージョンよりもコストがかかるわけではなく、同じ操作をより明確に表現する方法です。

翻訳者

このプラグマを使用すると、ファイル内の翻訳のコンテキストを設定できます。

pragma Translator: myTranslationContext

pragma Translator: "myTranslationContext"

QML での国際化に関する詳細については、「QML での翻訳用ソースコードの記述」を参照してください。

インポート

ドキュメントは、エンジンがドキュメント内で参照される QML オブジェクト型をロードできるように、必要なモジュールまたは型名前空間をインポートする必要があります。 デフォルトでは、ドキュメントは、同じディレクトリにある.qml ファイルを通じて定義されたすべてのQMLオブジェクトタイプにアクセスできます。ドキュメントで他のオブジェクトタイプを参照する必要がある場合は、それらのタイプが登録されているタイプネームスペースをインポートする必要があります。

QML には、C や C++ とは異なり、QML engine に提示する前にドキュメントを変更するプリプロセッサはありません。import ステートメントは、ドキュメント内のコードをコピーして先頭に追加するのではなく、ドキュメント内に見つかった型参照をどのように解決するかを QML エンジンに指示します。 QMLドキュメント内に存在するあらゆる型参照（Rectangle やListView など）は、JavaScriptブロック内やプロパティバインディング内で指定されたものを含め、すべてimport文に基づいてのみ解決されます。import QtQuick 2.0 のようなimport 文が少なくとも1つ存在する必要があります。

QMLのインポートに関する詳細については、『QML構文 - インポート文』のドキュメントを参照してください。

ルートオブジェクトの宣言

QMLドキュメントは、インスタンス化可能なオブジェクトの階層構造を記述します。各オブジェクト定義には特定の構造があり、型を持ち、IDやオブジェクト名、プロパティ、メソッド、シグナル、およびシグナルハンドラを持つことができます。

QMLファイルには、単一のルートオブジェクト定義のみを含める必要があります。以下は不正な記述であり、エラーが発生します：

// MyQmlFile.qml
import QtQuick 2.0

Rectangle { width: 200; height: 200; color: "red" }
Rectangle { width: 200; height: 200; color: "blue" }    // invalid!

これは、.qml ファイルが自動的に QML 型を定義し、その型が単一のQML オブジェクト定義をカプセル化するためです。これについては、「ドキュメントとしての QML オブジェクト型定義」でさらに詳しく説明しています。