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

分组特性

若使用来自一组特性中的多个特性，考虑使用 组表示法 而不是 点表示法 若它能改进可读性。

例如，这样：

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

Unqualified access

In order to improve readability and performance always reference properties of parent components by their id explicitly:

Item {
    id: root
    property int rectangleWidth: 50
    Rectangle {
        width: root.rectangleWidth
    }
}

Required properties

When requiring data defined outside the component, make this explicit by using Required Properties . Required properties must be set or else the creation of the component will fail. These are preferable to unqualified lookups because they are more performant and allow for both users and tooling to reason about an external property's type. Additionally they remove assumptions that a component otherwise has to make about the environment in which it is created.

信号处理程序

When handling parameters in signal handlers use functions which name them explicitly:

MouseArea {
    onClicked: (event) => { console.log(`${event.x},${event.y}`); }
}

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

Also note that is recommended to add type annotations to your function in order to more easily reason about and refactor your application since both parameter and return types are immediately visible from the function signature.

对于长脚本，将函数放入 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 实践