Конвенции кодирования QML

В этом документе содержатся конвенции кодирования QML, которые мы используем в нашей документации и примерах, и рекомендуем следовать им.

Объявления QML-объектов

Во всей нашей документации и примерах атрибуты QML-объектов всегда структурированы в следующем порядке:

• id
• объявления свойств
• объявления сигналов
• функции JavaScript
• свойства объекта
• дочерние объекты

Для лучшей читаемости мы разделяем эти различные части пустой строкой.

Например, гипотетический QML-объект photo будет выглядеть так:

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: {
        var scenePos = mapToItem(null, mouseX, mouseY);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}

Связанная информация

• Рекомендованные практики для QML и Qt Quick