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