Основы синтаксиса 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"
}

Это объявляет объект типа Прямоугольник, за которым следуют фигурные скобки, содержащие атрибуты, определённые для этого объекта. Тип Прямоугольник предоставляется модулем QtQuick, а атрибуты, определённые в данном случае, — значения свойств прямоугольника width, height и color. (Это свойства, предоставляемые типом Прямоугольник, как описано в документации Прямоугольник.)

Движок может загрузить указанный выше объект, если он является частью QML-документа. То есть, если исходный код дополнен инструкцией импорта, которая импортирует модуль QtQuick (чтобы сделать тип Прямоугольник доступным), как показано ниже:

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100
    color: "red"
}

Когда указанный выше код помещается в файл .qml и загружается QML-движком, он создаёт объект Прямоугольник с использованием типа Прямоугольник, предоставленного модулем QtQuick:

Примечание: Если определение объекта содержит небольшое количество свойств, его можно записать на одной строке, разделив свойства точкой с запятой:

Rectangle { width: 100; height: 100; color: "red" }

Очевидно, что объект Прямоугольник, объявленный в этом примере, очень прост, поскольку он определяет лишь несколько значений свойств. Для создания более полезных объектов объявление объекта может определять множество других типов атрибутов. Эти атрибуты обсуждаются в документации Атрибуты QML-объектов. Кроме того, объявление объекта может определять дочерние объекты, как описано ниже.

Дочерние объекты

Любое объявление объекта может определять дочерние объекты с помощью вложенных объявлений объектов. Таким образом, любое объявление объекта неявно объявляет дерево объектов, которое может содержать любое количество дочерних объектов.

Например, нижеприведённое объявление объекта Прямоугольник включает объявление объекта Градиент, которое, в свою очередь, содержит два объявления ГрадиентСтоп:

import QtQuick 2.0

Rectangle {
    width: 100
    height: 100

    gradient: Gradient {
        GradientStop { position: 0.0; color: "yellow" }
        GradientStop { position: 1.0; color: "green" }
    }
}

При загрузке этого кода движком он создаёт дерево объектов с объектом Прямоугольник в корне; этот объект имеет дочерний объект Градиент, который, в свою очередь, имеет два дочерних объекта ГрадиентСтоп.

Однако обратите внимание, что это отношение родитель-дочерний в контексте QML-дерева объектов, а не в контексте визуальной сцены. Понятие родительско-дочернего отношения в визуальной сцене предоставляется типом Элемент из модуля QtQuick, который является базовым типом для большинства QML-типов, поскольку большинство QML-объектов предназначены для визуального отображения. Например, Прямоугольник и Текст — оба типы на основе Элемент, и ниже объект Текст был объявлен как визуальный дочерний объект объекта Прямоугольник:

import QtQuick 2.0

Rectangle {
    width: 200
    height: 200
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, QML!"
    }
}

Когда объект Текст ссылается на своё значение родитель в вышеприведённом коде, он ссылается на своего визуального родителя, а не на родителя в дереве объектов. В данном случае они совпадают: объект Прямоугольник является родителем объекта Текст как в контексте QML-дерева объектов, так и в контексте визуальной сцены. Однако, хотя свойство родитель можно изменить, чтобы изменить визуального родителя, родителя объекта в контексте дерева объектов нельзя изменить из QML.

(Кроме того, обратите внимание, что объект Текст был объявлен без присвоения его свойству объекта Прямоугольник, в отличие от предыдущего примера, который назначил объект Градиент свойству прямоугольника gradient. Это связано с тем, что свойство детей типа Элемент установлено в качестве его свойства по умолчанию, чтобы обеспечить этот более удобный синтаксис.)

Для получения дополнительной информации о понятии визуального родительства с типом Элемент см. документацию визуальный родитель.

Комментарии

Синтаксис комментариев в 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
}

В вышеприведённом примере объект Текст будет иметь обычную непрозрачность, так как строка opacity: 0.5 была преобразована в комментарий.