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

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

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

Выражения import

Документ QML может содержать один или несколько выражений import в начале файла. Выражение import может быть одним из:

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

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

Общие формы различных выражений import следующие:

• 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 — Выражения import.

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

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

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

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

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

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

Движок может загрузить вышеуказанный объект, если он является частью QML-документа. То есть, если исходный код дополняется выражением import, которое импортирует модуль 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-объектов, так и в контексте визуальной сцены. Однако, хотя свойство parent можно изменить для изменения визуального родителя, родителя объекта в контексте дерева объектов с помощью 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 была превращена в комментарий.