Основы синтаксиса 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 была преобразована в комментарий.