Структура QML-файла и базовые элементы

Введение

QML (Qt Modeling Language) — это декларативный язык описания пользовательского интерфейса, используемый в технологии Qt Quick. В отличие от классического Qt Widgets, где интерфейс создаётся пошагово через C++, QML описывает структуру сцены, свойства элементов и связи между ними.

Чтобы уверенно работать с QML, необходимо чётко понимать:

• из чего состоит QML-файл;
• как формируется дерево объектов;
• какие элементы являются базовыми;
• как они взаимодействуют друг с другом.

Эта статья посвящена именно этим фундаментальным вопросам.

QML-файл как компонент

Что такое QML-файл

Каждый .qml-файл — это самостоятельный компонент, который:

• имеет один корневой объект;
• может быть переиспользован;
• может иметь собственные свойства, сигналы и методы.

Простейший QML-файл:

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

Даже такой минимальный файл уже является полноценным UI-компонентом.

Связь имени файла и типа

Если файл называется MyItem.qml, то внутри QML он используется как тип:

MyItem {
}

Это ключевая концепция: QML = система компонентов.

Импорты (import)

Назначение импортов

В начале QML-файла указываются импорты — они определяют, какие типы и модули доступны.

Пример:

import QtQuick 2.15
import QtQuick.Controls 2.15

Без импорта объект просто не будет распознан.

Основные модули

Модуль	Назначение
QtQuick	Базовые визуальные элементы
QtQuick.Controls	Готовые элементы управления
QtQuick.Layouts	Layout-системы
QtQuick.Window	Окна
QtQml	Логика, свойства, сигналы

Версии модулей

import QtQuick 2.15

Версия:

• фиксирует API;
• повышает предсказуемость поведения;
• рекомендуется указывать всегда.

---

Корневой объект

Строго один корневой элемент

Каждый QML-файл обязан иметь ровно один корневой объект.

❌ Неверно:

Rectangle { }
Text { }

✅ Верно:

Item {
    Rectangle { }
    Text { }
}

Назначение корневого объекта

Корневой объект:

• задаёт геометрию сцены;
• управляет жизненным циклом;
• является родителем для всех вложенных элементов.

Часто используемые корневые типы:

• Window
• Item
• Rectangle
• ApplicationWindow

---

Дерево объектов (Object Tree)

Иерархия элементов

QML строит иерархическое дерево объектов:

Rectangle {
    Text { }
    Image { }
}

Здесь:

• Rectangle — родитель;
• Text и Image — дочерние элементы.

Что даёт иерархия

• Наследование координат
• Управление видимостью
• Совместное позиционирование
• Управление событиями

Пример:

Item {
    visible: false

    Text {
        text: "Меня тоже не видно"
    }
}

Базовые визуальные элементы Qt Quick

Item — базовый контейнер

Item — фундаментальный элемент Qt Quick.

Характеристики:

• не имеет визуального представления;
• используется как контейнер;
• поддерживает позиционирование и события.

Item {
    width: 200
    height: 200
}

Используется:

• для группировки элементов;
• как логический блок;
• как базовый класс.

---

Rectangle — основной визуальный блок

Rectangle — самый часто используемый визуальный элемент.

Rectangle {
    width: 150
    height: 80
    color: "#3498db"
    radius: 8
}

Поддерживает:

• цвет (color);
• скругление (radius);
• границу (border).

border.color: "black"
border.width: 1

Text — отображение текста

Text {
    text: "Hello QML"
    font.pixelSize: 20
    color: "white"
}

Ключевые свойства:

• text
• font
• color
• wrapMode
• horizontalAlignment

Пример переноса строк:

wrapMode: Text.WordWrap
width: 200

Image — изображения

Image {
    source: "qrc:/icons/logo.png"
    fillMode: Image.PreserveAspectFit
}

Основные режимы:

• Stretch
• PreserveAspectFit
• PreserveAspectCrop
• Tile

---

MouseArea — пользовательский ввод

MouseArea — основной элемент для обработки ввода мыши и тача.

MouseArea {
    anchors.fill: parent
    onClicked: console.log("Clicked")
}

Поддерживает:

• клики;
• двойные клики;
• удержание;
• позицию курсора.

---

Свойства объектов

Что такое свойства

Каждый QML-объект — это набор типизированных свойств:

width: 100
height: 50
visible: true

Свойства:

• автоматически отслеживают изменения;
• могут быть связаны выражениями;
• могут быть переопределены.

---

Пользовательские свойства

property int counter: 0
property string title: "Заголовок"

Используются для:

• параметризации компонентов;
• передачи данных;
• управления состоянием.

---

Идентификаторы (id)

Назначение id

id — это локальное имя объекта внутри файла.

Rectangle {
    id: root

    Text {
        text: root.width
    }
}

Особенности:

• доступен только в текущем QML-файле;
• не является свойством;
• используется для ссылок и биндингов.

---

Anchors — базовое позиционирование

Привязки (anchors)

Anchors позволяют описывать относительное положение элементов.

anchors.centerIn: parent

Другие варианты:

• anchors.fill
• anchors.left
• anchors.top
• anchors.margins

Пример:

Text {
    anchors.bottom: parent.bottom
    anchors.horizontalCenter: parent.horizontalCenter
    anchors.bottomMargin: 10
}

Комментарии в QML

Однострочные комментарии

// Это комментарий

Многострочные комментарии

/*
  Блок комментариев
*/

Используются для:

• пояснений;
• временного отключения кода;
• документирования компонентов.

---

Типичная структура простого QML-файла

import QtQuick 2.15
import QtQuick.Controls 2.15

Rectangle {
    id: root
    width: 400
    height: 300
    color: "#2c3e50"

    Text {
        text: "Структура QML"
        anchors.centerIn: parent
        color: "white"
        font.pixelSize: 24
    }
}

Заключение

Понимание структуры QML-файла — это фундамент для всей дальнейшей работы с Qt Quick. Ключевые идеи, которые необходимо усвоить:

1. Каждый QML-файл — компонент
2. Всегда один корневой объект
3. Интерфейс — это дерево объектов
4. Всё строится на свойствах и их связях
5. Item и Rectangle — основа
6. MouseArea — ключ к интерактивности