QMLコーディング規約

このドキュメントでは、QML のコーディング規約について説明します。

QML オブジェクトの宣言

QML オブジェクトの属性は、文書やサンプルを通して、常に以下の順序で記述されています：

id
プロパティ宣言
シグナル宣言
JavaScript の関数
オブジェクトのプロパティ
子オブジェクト

読みやすくするために、これらの異なる部分を空行で区切ります。

例えば、仮想的な写真のQMLオブジェクトは次のようになります：

Rectangle {
    id: photo                                               // id on the first line makes it easy to find an object

    property bool thumbnail: false                          // property declarations
    property alias image: photoImage.source

    signal clicked                                          // signal declarations

    function doSomething(x)                                 // javascript functions
    {
        return x + photoImage.width;
    }

    color: "gray"                                           // object properties
    x: 20                                                   // try to group related properties together
    y: 20
    height: 150
    width: {                                                // large bindings
        if (photoImage.width > 200) {
            photoImage.width;
        } else {
            200;
        }
    }

    states: [
        State {
            name: "selected"
            PropertyChanges { target: border; color: "red" }
        }
    ]

    transitions: [
        Transition {
            from: ""
            to: "selected"
            ColorAnimation { target: border; duration: 200 }
        }
    ]

    Rectangle {                                             // child objects
        id: border
        anchors.centerIn: parent
        color: "white"

        Image {
            id: photoImage
            anchors.centerIn: parent
        }
    }
}

グループ化されたプロパティ

複数のプロパティをグループ化して使用する場合、読みやすさが向上するのであれば、ドット記法の代わりにグループ記法を使用することを検討してください。

例えば

Rectangle {
    anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
}

Text {
    text: "hello"
    font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
}

はこのように書くことができます：

Rectangle {
    anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
}

Text {
    text: "hello"
    font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
}

非限定アクセス

可読性とパフォーマンスを向上させるためには、常に親コンポーネントのプロパティをidで明示的に参照すること：

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

必須プロパティ

コンポーネントの外部で定義されたデータが必要な場合は、Required Propertiesを使用して明示的に指定します。Requiredプロパティを設定しないと、コンポーネントの作成に失敗します。これらは、非限定的なルックアップよりもパフォーマンスが高く、ユーザーとツールの両方が外部プロパティの型を推論できるため、好ましい。さらに、これらのルックアップは、コンポーネントが作成される環境について、コンポーネントが行わなければならない仮定を取り除きます。

シグナルハンドラ

シグナルハンドラでパラメータを処理する場合は、明示的に名前を付ける関数を使用します：

MouseArea {
    onClicked: event => { console.log(`${event.x},${event.y}`); }
}

JavaScriptコード

スクリプトが単一の式の場合は、インラインで記述することを推奨します：

Rectangle { color: "blue"; width: parent.width / 3 }

スクリプトが数行しかない場合は、通常ブロックを使用します：

Rectangle {
    color: "blue"
    width: {
        var w = parent.width / 3;
        console.debug(w);
        return w;
    }
}

スクリプトが2、3行以上の場合や、異なるオブジェクトで使用できる場合は、このように関数を作成し、それを呼び出すことをお勧めします：

function calculateWidth(object : Item) : double
{
    var w = object.width / 3;
    // ...
    // more javascript code
    // ...
    console.debug(w);
    return w;
}

Rectangle { color: "blue"; width: calculateWidth(parent) }

また、アプリケーションの推論やリファクタリングをより簡単に行うために、関数に型アノテーションを追加することをお勧めします。

長いスクリプトの場合は、関数を独自のJavaScriptファイルに入れて、次のようにインポートします：

import "myscript.js" as Script

Rectangle { color: "blue"; width: Script.calculateWidth(parent) }

コードが1行より長く、ブロック内にある場合は、セミコロンを使って各ステートメントの終わりを示します：

MouseArea {
    anchors.fill: parent
    onClicked: event => {
        var scenePos = mapToItem(null, event.x, event.y);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}

QMLのベストプラクティスQt Quick

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.