QML 編碼約定

此文檔包含我們在文檔編製和範例中遵循的 QML 編碼約定，並推薦其它人遵循。

QML 對象聲明

縱觀文檔編製和範例， QML 對象屬性始終按以下次序被構造化：

id
特性聲明
信號聲明
JavaScript 函數
對象特性
子級對象

為提高可讀性，我們采用空行分隔這些不同部分。

例如，假設 photo 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 }
}

Unqualified access

In order to improve readability and performance always reference properties of parent components by their id explicitly:

Item {
    id: root
    property int rectangleWidth: 50
    Rectangle {
        width: root.rectangleWidth
    }
}

Required properties

When requiring data defined outside the component, make this explicit by using Required Properties . Required properties must be set or else the creation of the component will fail. These are preferable to unqualified lookups because they are more performant and allow for both users and tooling to reason about an external property's type. Additionally they remove assumptions that a component otherwise has to make about the environment in which it is created.

信號處理程序

When handling parameters in signal handlers use functions which name them explicitly:

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

Also note that is recommended to add type annotations to your function in order to more easily reason about and refactor your application since both parameter and return types are immediately visible from the function signature.

對於長腳本，將函數放入 JavaScript 文件並像這樣 import 它：

import "myscript.js" as Script
Rectangle { color: "blue"; width: Script.calculateWidth(parent) }

若代碼長於一行並因此在塊中，使用分號指示每條語句結束：

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

最佳 QML 和 Qt Quick 實踐