Конвенции кодирования 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 }
}

Код 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)
{
    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