QMLのコーディング規約

このドキュメントには、当社のドキュメントやサンプルで採用している、また他の方にも遵守を推奨するQMLのコーディング規約が記載されています。

QML オブジェクトの宣言

当ドキュメントおよびサンプル全体を通じて、QML オブジェクトの属性は常に以下の順序で記述されています：

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

可読性を高めるため、これらの異なる部分を空行で区切ります。

たとえば、架空のphotoQML オブジェクトは次のようになります:

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
    }
}

必須プロパティ

コンポーネントの外部で定義されたデータが必要な場合は、「必須プロパティ」を使用してこれを明示してください。必須プロパティは設定されていなければならず、そうでない場合、コンポーネントの作成は失敗します。これらは、パフォーマンスが高く、ユーザーやツールが外部プロパティの型を推論できるため、修飾なしのルックアップよりも推奨されます。さらに、これにより、コンポーネントが作成される環境について、コンポーネント側が本来行わなければならない仮定を取り除くことができます。

シグナルハンドラ

シグナルハンドラでパラメータを処理する際は、パラメータ名を明示的に指定した関数を使用してください：

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;
    }
}

スクリプトが数行を超える場合や、異なるオブジェクトから使用される可能性がある場合は、関数を作成し、次のように呼び出すことを推奨します：

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 のベストプラクティススケーラビリティ

© 2026 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.