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;
        }
    }
    Rectangle {                                             // child objects
        id: border
        anchors.centerIn: parent; color: "white"
        Image {
            id: photoImage
            anchors.centerIn: parent
        }
    }
    states: State {                                         // states
        name: "selected"
        PropertyChanges { target: border; color: "red" }
    }
    transitions: Transition {                               // transitions
        from: ""
        to: "selected"
        ColorAnimation { target: border; duration: 200 }
    }
}

分組特性

若使用來自一組特性中的多個特性，考慮使用 組錶示法 而不是 點錶示法 若它能改進可讀性。

例如，這樣：

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

列錶

If a list contains only one element, we generally omit the square brackets.

For example, it is very common for a component to only have one state.

In this case, instead of:

states: [
    State {
        name: "open"
        PropertyChanges { target: container; width: 200 }
    }
]

we will write this:

states: State {
    name: "open"
    PropertyChanges { target: container; width: 200 }
}

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)
{
    var w = object.width / 3
    // ...
    // more javascript code
    // ...
    console.debug(w)
    return w
}
Rectangle { color: "blue"; width: calculateWidth(parent) }

對於長腳本，將函數放入 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 實踐

QML 編碼約定

QML 對象聲明

分組特性

列錶

JavaScript 代碼

相關信息

內容