QML官方系列教程——QML Coding Conventions

附网址：http://qt-project.org/doc/qt-5/qml-codingconventions.html

QML Coding Conventions —— QML编码规范

这个文档包含了QML的编码规范，我们将这个规范应用在全部文档和例程当中并推荐大家遵守。

QML Object Declarations

在我们的文档和例子中，QML object对象的属性总是以下面这样的结构排序：

id —— 命名

property declarations —— 属性声明

signal declarations —— 信号声明

JavaScript functions —— JavaScript函数

object properties —— 对象属性

child objects —— 子对象

states —— 状态

transitions —— 转换

为了更好的可读性，我们将这些不同的部分用一个空行分隔开来。

比如，假如有一个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 }
    }
}

·
Grouped Properties —— 属性组

如果使用了一组属性中的多个属性，考虑使用"组符号"代替"点符号"来提高可读性。

例如下面这个例子：

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

·
Lists

如果一个列表只包含一个元素，我们通常应该省略括号。

比如，通常组件只包含一个状态是非常常见的。

那么，我们不应该这样写：

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

·
而应该这样：

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

·
JavaScript Code —— JavaScript代码

如果脚步只包含一个单一的表达式，我们推荐将它写成内联：

Rectangle { color: "blue"; width: parent.width / 3 }

·
如果脚本只有几行，我们通常使用一个块：

Rectangle {
    color: "blue"
    width: {
        var w = parent.width / 3
        console.debug(w)
        return w
    }
}

·

如果脚本有多行并且被多个不同对象所使用，我们推荐创建一个function并像这样调用它：

function calculateWidth(object)
{
    var w = object.width / 3
    // ...
    // more javascript code
    // ...
    console.debug(w)
    return w
}

Rectangle { color: "blue"; width: calculateWidth(parent) }

·
对于很长的脚本，我们将这些functions放在一个单独的JavaScript文件中并像这样进行引入：

import "myscript.js" as Script

Rectangle { color: "blue"; width: Script.calculateWidth(parent) }