Основы синтаксиса QML

QML — многопарадигменый язык, позволяющий определять объекты в терминах их атрибутов и способов взаимодействия и реагирования на изменения в других объектах. В отличие от чисто императивного кода, где изменения атрибутов и поведения выражаются через последовательность инструкций, обрабатываемых пошагово, декларативный синтаксис QML интегрирует изменения атрибутов и поведения непосредственно в определения отдельных объектов. Эти определения атрибутов могут затем включать императивный код в случае необходимости сложного пользовательского поведения приложения.

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

Заявления об импорте

Документ QML может содержать один или несколько импортов вверху файла. Импорт может быть любым из:

• пространство имён с версией, в которое зарегистрированы типы (например, плагином)
• относительный каталог, содержащий определения типов в виде документов QML
• файл JavaScript

Импорты файлов JavaScript должны быть квалифицированными при импорте, чтобы можно было получить доступ к предоставляемым ими свойствам и методам.

Общая форма различных импортов следующая:

• import Namespace VersionMajor.VersionMinor
• import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier
• import "directory"
• import "file.js" as ScriptIdentifier

Примеры:

• import QtQuick 2.0
• import QtQuick.LocalStorage 2.0 as Database
• import "../privateComponents"
• import "somefile.js" as Script

Для получения подробной информации об импортах QML см. документацию Синтаксис QML — Заявления об импорте.

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

Синтаксически блок кода QML определяет дерево создаваемых объектов QML. Объекты определяются с помощью объявлений объектов, описывающих тип создаваемого объекта и атрибуты, которые должны быть присвоены объекту. Каждый объект также может объявлять дочерние объекты с помощью вложенных объявлений объектов.

Объявление объекта состоит из имени типа объекта, за которым следует набор фигурных скобок. Все атрибуты и дочерние объекты объявляются внутри этих скобок.

Вот простое объявление объекта:

Rectangle {
    width: 100
    height: 100
    color: "red"
}

Это объявляет объект типа Rectangle, за которым следует набор фигурных скобок, содержащий атрибуты, определённые для этого объекта. Тип Rectangle предоставляется модулем QtQuick, а определённые в данном случае атрибуты — значения свойств прямоугольника width, height и color. (Это свойства, предоставляемые типом Rectangle, как описано в документации Rectangle.)

Двигатель может загрузить указанный выше объект, если он является частью документа QML. То есть, если исходный код дополняется заявлением об импорте, импортирующим модуль QtQuick (чтобы тип Rectangle был доступен), как показано ниже:

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100
    color: "red"
}

При размещении в файле .qml и загрузке движком QML указанный выше код создаёт объект Rectangle с помощью типа Rectangle, предоставленного модулем QtQuick:

Примечание: Если определение объекта имеет небольшое количество свойств, его можно записать в одну строку, разделяя свойства точкой с запятой:

Rectangle { width: 100; height: 100; color: "red" }

Очевидно, что объект Rectangle, объявленный в этом примере, очень прост, так как он определяет не более нескольких значений свойств. Для создания более полезных объектов объявление объекта может определять множество других типов атрибутов. Они обсуждаются в документации Атрибуты объектов QML. Кроме того, объявление объекта может определять дочерние объекты, как обсуждается ниже.

Дочерние объекты

Любое объявление объекта может определять дочерние объекты с помощью вложенных объявлений объектов. Таким образом, любое объявление объекта подразумевает объявление дерева объектов, которое может содержать любое количество дочерних объектов.

Например, объявление объекта Rectangle ниже включает объявление объекта Gradient, которое, в свою очередь, содержит два объявления GradientStop:

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100

    gradient: Gradient {
        GradientStop { position: 0.0; color: "yellow" }
        GradientStop { position: 1.0; color: "green" }
    }
}

При загрузке этого кода движком он создаёт дерево объектов с объектом Rectangle в корне; этот объект имеет дочерний объект Gradient, который, в свою очередь, имеет два дочерних объекта GradientStop.

Однако это отношение «родитель-ребёнок» в контексте дерева объектов QML, а не в контексте визуальной сцены. Концепция отношения «родитель-ребёнок» в визуальной сцене обеспечивается типом Item из модуля QtQuick, который является базовым типом для большинства типов QML, так как большинство объектов QML предназначены для визуального отображения. Например, Rectangle и Text — оба типы на основе Item, и ниже объект Text объявлен как визуальный дочерний элемент объекта Rectangle:

import QtQuick 2.0

Rectangle {
    width: 200
    height: 200
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, QML!"
    }
}

Когда объект Text обращается к своему значению родитель в приведенном выше коде, он обращается к своему визуальному родителю, а не к родителю в дереве объектов. В этом случае они совпадают: объект Rectangle является родителем объекта Text как в контексте дерева объектов QML, так и в контексте визуальной сцены. Однако, хотя свойство родитель можно изменить для изменения визуального родителя, родителя объекта в контексте дерева объектов изменить из QML нельзя.

(Кроме того, обратите внимание, что объект Text объявлен без присвоения его свойству объекта Rectangle, в отличие от предыдущего примера, который присвоил объект Gradient свойству прямоугольника gradient. Это происходит потому, что свойство children типа Item установлено в качестве его свойства по умолчанию для активации более удобного синтаксиса.)

Дополнительную информацию о концепции визуального родителя с типом Item см. в документации визуальный родитель.

Комментарии

Синтаксис комментирования в QML аналогичен синтаксису JavaScript:

• Комментарии в одну строку начинаются с // и заканчиваются в конце строки.
• Комментарии в несколько строк начинаются с /* и заканчиваются */

Text {
    text: "Hello world!"    //a basic greeting
    /*
        We want this text to stand out from the rest so
        we give it a large size and different font.
     */
    font.family: "Helvetica"
    font.pointSize: 24
}

Комментарии игнорируются движком при обработке кода QML. Они полезны для пояснения того, что делает раздел кода, будь то для ссылки в будущем или для объяснения реализации другим.

Комментарии также можно использовать для предотвращения выполнения кода, что иногда полезно для отладки проблем.

Text {
    text: "Hello world!"
    //opacity: 0.5
}

В приведенном выше примере объект Text будет иметь обычную непрозрачность, так как строка opacity: 0.5 была преобразована в комментарий.