QML 編碼約定

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

This page assumes that you are already familiar with the QML language. If you need an introduction to the language, please read the QML introduction 首先。

QML Objects

Through our documentation and examples, QML objects are always structured in the following order:

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; y: 20; height: 150                               // try to group related properties together
    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 }
    }
}

分組特性

If using multiple properties from a group of properties, we use the 組錶示法 rather than the 點錶示法 to improve readability.

例如，這樣：

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
}

can be written like this:

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

Private Properties

QML and JavaScript do not enforce private properties like C++. There is a need to hide these private properties, for example, when the properties are part of the implementation. To effectively gain private properties in a QML Item, the convention is to add a QtObject {} child to contain the properties. This shields them from being accessed outside the file in QML and JavaScript. As it involves the creation of another object, it is more expensive than just creating a property. To minimize the performance cost, try to group all private properties in one file into the same QtObject .

Item {
    id: component
    width: 40; height: 50
    QtObject {
        id: d
        property real area: width * height * 0.5    //not meant for outside use
    }
}

列錶

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