Основы синтаксиса 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-объектов, так и в контексте визуальной сцены. Однако, в то время как свойство 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 была преобразована в комментарий.