Основы синтаксиса 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 ссылается на своё значение parent в приведенном выше коде, он ссылается на своего визуального родителя, а не на родителя в дереве объектов. В этом случае они совпадают: объект 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 была преобразована в комментарий.