Qt官方教程翻译——QML Coding Conventions

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

QML Coding Conventions

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

QML Object Declarations

在我们的文档和例子中，QML object attributes总是像下面这样的结构：

id

property declarations

signal declarations

JavaScript functions

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

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

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

Qt官方教程翻译——QML Coding Conventions