Определение типов объектов через документы QML

Одна из ключевых особенностей QML заключается в том, что она позволяет легко определять типы объектов QML в лёгкой форме через документы QML, чтобы удовлетворить потребности отдельных приложений QML. Стандартный модуль Qt Quick предоставляет различные типы, такие как Прямоугольник, Текст и Изображение для создания приложения QML; помимо этого, вы можете легко определить собственные типы QML для повторного использования в приложении. Эта возможность создавать собственные типы является основой любого приложения QML.

Определение типа объекта с файлом QML

Для создания типа объекта документ QML должен быть помещён в текстовый файл с именем <TypeName>.qml, где <TypeName> — желаемое имя типа, которое должно состоять из буквенно-цифровых символов или символов подчеркивания и начинаться с заглавной буквы. Этот документ автоматически распознаётся движком как определение типа QML. Кроме того, тип, определённый таким образом, автоматически становится доступным для других файлов QML в той же директории, так как движок ищет в непосредственной директории при разрешении имён типов QML.

Например, ниже приведён документ, который объявляет Прямоугольник с дочерним элементом Область мыши. Документ был сохранён в файле с именем SquareButton.qml:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Поскольку файл называется SquareButton.qml, это теперь можно использовать как тип, названный SquareButton в любом другом файле QML в той же директории. Например, если был файл myapplication.qml в той же директории, он мог бы ссылаться на тип SquareButton:

// myapplication.qml
import QtQuick 2.0

SquareButton {}

Это создаёт 100x100 красный Прямоугольник с внутренним Областью мыши, как определено в SquareButton.qml. Когда этот myapplication.qml документ загружается движком, он загружает документ SquareButton.qml как компонент и создаёт объект SquareButton.

Тип SquareButton encapsulates the tree of QML objects declared in SquareButton.qml. При создании объекта SquareButton из этого типа движок QML создаёт объект из дерева Прямоугольников, описанного в SquareButton.qml.

Примечание: регистр букв в имени файла имеет значение в некоторых файловых системах (особенно UNIX). Рекомендуется, чтобы регистр имени файла точно соответствовал регистру желаемого имени типа QML — например, Box.qml, а не BoX.qml — независимо от платформы, на которую будет развернут тип QML.

Импорт типов, определённых за пределами текущей директории

Если SquareButton.qml не находился в той же директории, что и myapplication.qml, тип SquareButton необходимо было бы сделать доступным через оператор import в myapplication.qml. Его можно импортировать из относительного пути в файловой системе или как установленный модуль; см. модуль для получения дополнительной информации.

Доступные атрибуты пользовательских типов

Определение корневого объекта в файле .qml определяет атрибуты, доступные для типа QML. Все свойства, сигналы и методы, принадлежащие этому корневому объекту — будь то пользовательские объявленные или взятые из типа QML корневого объекта — доступны извне и могут быть прочитаны и изменены для объектов этого типа.

Например, тип корневого объекта в файле SquareButton.qml — Прямоугольник. Это означает, что любые свойства, определённые типом Прямоугольник, могут быть изменены для объекта SquareButton. Код ниже определяет три SquareButton объекта со значениями, настроенными для некоторых свойств корневого объекта Прямоугольника типа SquareButton:

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

К атрибутам, доступным для объектов пользовательского типа QML, относятся все пользовательские свойства, методы и сигналы, которые дополнительно были определены для объекта. Например, предположим, что Прямоугольник в SquareButton.qml был определён следующим образом с дополнительными свойствами, методами и сигналами:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: root.buttonClicked(mouse.x, mouse.y)
    }
}

Любой SquareButton объект может использовать свойство pressed, сигнал buttonClicked и метод randomizeColor(), которые были добавлены к корневому Прямоугольнику:

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

Обратите внимание, что любые значения id , определённые в SquareButton.qml, недоступны для SquareButton объектов, так как значения id доступны только из области видимости компонента, в котором компонент объявлен. Определение объекта SquareButton выше не может ссылаться на mouseArea для ссылки на дочерний элемент Область мыши, и если у него был id root, а не squareButton, это не конфликтовало бы со значением id корневого объекта, определённого в SquareButton.qml, так как они были бы объявлены в разных областях видимости.