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