QML 编码规范

本文档包含我们在文档和示例中遵循的 QML 编码规范，并建议其他人也遵循这些规范。

QML 对象声明

在我们的文档和示例中，QML 对象的属性始终按以下顺序排列：

id
属性声明
信号声明
JavaScript 函数
对象属性
子对象

为了提高可读性，我们用空行将这些不同的部分分隔开来。

例如，一个假设的photoQML 对象将如下所示：

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

未限定访问

为了提高可读性和性能，请始终通过 ID 显式引用父级组件的属性：

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

必填属性

当需要使用组件外部定义的数据时，请通过“必需属性”明确指定。必需属性必须被设置，否则组件的创建将失败。与未限定的查找相比，这种方式更可取，因为它性能更优，并且既允许用户，也允许开发工具推断外部属性的类型。此外，它们还消除了组件原本必须对其创建环境做出的各种假设。

信号处理程序

在信号处理程序中处理参数时，请使用显式命名参数的函数：

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

另请注意，建议为函数添加类型注解，以便更轻松地理解和重构应用程序，因为参数和返回类型均可从函数签名中直接看出。

对于较长的脚本，我们会将函数放在单独的 JavaScript 文件中，并像这样导入：

import "myscript.js" as Script

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

如果代码超过一行（即属于一个代码块），我们会使用分号来标记每条语句的结尾：

MouseArea {
    anchors.fill: parent
    onClicked: event => {
        var scenePos = mapToItem(null, event.x, event.y);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}

QML和Qt Quick 的最佳实践可扩展性

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.