Основы синтаксиса 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 к свойству rectangle's 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 превращена в комментарий.