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

本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。ここで提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の商標です。その他すべての商標は、それぞれの所有者に帰属します。