Тип компонента QML

Инкапсулирует определение компонента QML. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• progress : вещественное число
• status : перечисление
• url : url

Присоединённые сигналы

• completed()
• destruction()

Методы

• объект createObject(родитель, объект свойства)
• строка errorString()
• объект incubateObject(родитель, объект свойства, перечисление режим)

Подробное описание

Компоненты — это многократно используемые, инкапсулированные типы QML с хорошо определёнными интерфейсами.

Компоненты часто определяются файлами компонентов — это файлы .qml. Тип Component фактически позволяет определять компоненты QML встроены, непосредственно в документ QML, вместо отдельного файла QML. Это может быть полезно для повторного использования небольшого компонента в файле QML или для определения компонента, который логически принадлежит другим компонентам QML в одном файле.

Например, вот компонент, используемый несколькими объектами Loader. Он содержит один элемент — Rectangle:

import QtQuick 2.0

Item {
    width: 100; height: 100

    Component {
        id: redSquare

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

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}

Обратите внимание, что хотя Rectangle сам по себе будет автоматически рендериться и отображаться, это не так для прямоугольника выше, потому что он определён внутри Component. Компонент инкапсулирует типы QML внутри, как если бы они были определены в отдельном файле QML, и загружается только по запросу (в этом случае — двумя объектами Loader). Поскольку Component не наследуется от Item, вы не можете привязать что-либо к нему.

Определение Component аналогично определению документа QML. Документ QML имеет один элемент верхнего уровня, который определяет поведение и свойства этого компонента, и не может определить свойства или поведение вне этого элемента верхнего уровня. Аналогично, определение Component содержит один элемент верхнего уровня (который в приведённом примере — Rectangle) и не может определять какие-либо данные за пределами этого элемента, за исключением id (в приведённом примере — redSquare).

Тип Component обычно используется для предоставления графических компонентов для представлений. Например, свойство ListView::delegate требует Component для указания, как отображать каждый элемент списка.

Component объекты также можно создавать динамически с помощью Qt.createComponent().

Контекст создания

Контекст создания компонента соответствует контексту, где компонент был объявлен. Этот контекст используется в качестве родительского контекста (создавая иерархию контекстов компонентов), когда компонент создаётся объектом, таким как ListView или Loader.

В следующем примере comp1 создаётся в корневом контексте MyItem.qml, и любые объекты, созданные из этого компонента, будут иметь доступ к идентификаторам и свойствам в этом контексте, таким как internalSettings.color. Когда comp1 используется в качестве делегата ListView в другом контексте (как в main.qml ниже), он по-прежнему будет иметь доступ к свойствам своего контекста создания (которые в противном случае были бы закрыты для внешних пользователей).

Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

Важно, чтобы срок существования контекста создания превышал срок существования созданных объектов. Дополнительные сведения см. в разделе Поддержание динамически созданных объектов.

Документация по свойствам

progress : вещественное число

Прогресс загрузки компонента, от 0,0 (ничего не загружено) до 1,0 (загрузка завершена).

status : перечисление

Это свойство содержит состояние загрузки компонента. Состояние может быть следующим:

• Component.Null — данные для компонента недоступны
• Component.Ready — компонент загружен и может использоваться для создания экземпляров.
• Component.Loading — компонент в настоящее время загружается
• Component.Error — при загрузке компонента произошла ошибка. Вызов errorString() предоставит удобочитаемое описание любых ошибок.

url : url

URL компонента. Это URL, который использовался для создания компонента.

Документация по присоединённым сигналам

completed()

Вызывается после создания объекта. Это можно использовать для выполнения скриптового кода при запуске, после создания полной среды QML.

Соответствующий обработчик — onCompleted. Он может быть объявлен в любом объекте. Порядок выполнения обработчиков onCompleted не определён.

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

destruction()

Вызывается при начале уничтожения объекта. Это можно использовать для отмены работы, выполненной в ответ на сигнал completed(), или другого императивного кода в вашем приложении.

Соответствующий обработчик — onDestruction. Он может быть объявлен в любом объекте. Порядок выполнения обработчиков onDestruction не определён.

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

См. также Qt QML.

Документация по методам

объект createObject(родитель, объект свойства)

Создаёт и возвращает экземпляр объекта этого компонента, который будет иметь указанного родителя и свойства. Аргумент свойства необязателен. Возвращает null, если создание объекта не удалось.

Объект будет создан в том же контексте, что и контекст создания компонента. Этот метод всегда вернёт null при вызове для компонентов, которые не были созданы в QML.

Если вы хотите создать объект без задания родителя, укажите null в качестве значения родителя. Обратите внимание, что если возвращаемый объект должен быть отображён, вы должны указать действительное значение родителя или установить свойство родителя возвращаемого объекта, в противном случае объект не будет отображаться.

Если родитель не предоставлен методу createObject(), ссылка на возвращённый объект должна быть сохранённой, чтобы он не был уничтожен сборщиком мусора. Это справедливо независимо от того, установлено ли свойство Item::parent впоследствии, так как установка родителя Item не изменяет владения объектом. Изменяется только графический родитель.

Начиная с QtQuick 1.1, этот метод принимает необязательный аргумент свойства, который определяет карту начальных значений свойств для созданного объекта. Эти значения применяются до завершения создания объекта. Это более эффективно, чем установка значений свойств после создания объекта, особенно при определении больших наборов значений свойств, а также позволяет настроить привязки свойств (с помощью Qt.binding) до создания объекта.

Аргумент свойства указывается как карта элементов свойство-значение. Например, код ниже создаёт объект с начальными значениями x и y соответственно 100 и 100:

var component = Qt.createComponent("Button.qml");
if (component.status == Component.Ready)
    component.createObject(parent, {x: 100, y: 100});

Динамически созданные экземпляры можно удалить с помощью метода destroy(). Дополнительные сведения см. в разделе Динамическое создание объектов QML из JavaScript.

См. также incubateObject().

строка errorString()

Возвращает удобочитаемое описание любой ошибки.

Строка включает имя файла, расположение и описание каждой ошибки. Если присутствует несколько ошибок, они разделяются символом новой строки.

Если ошибок нет, возвращается пустая строка.

объект incubateObject(родитель, объект свойства, перечисление режим)

Создаёт инкубатор для экземпляра этого компонента. Инкубаторы позволяют асинхронно создавать новые экземпляры компонентов и не вызывают зависания интерфейса пользователя.

Аргумент родитель определяет родителя создаваемого экземпляра. Пропуск параметра или передача null создаст объект без родителя. В этом случае ссылка на созданный объект должна быть сохранённой, чтобы он не был уничтожен сборщиком мусора.

Аргумент свойства указывается как карта элементов свойство-значение, которые будут установлены на созданном объекте во время его построения. режим может быть Qt.Synchronous или Qt.Asynchronous и управляет тем, создаётся ли экземпляр синхронно или асинхронно. По умолчанию используется асинхронный режим. В некоторых случаях, даже если указан Qt.Synchronous, инкубатор может создать объект асинхронно. Это происходит, если компонент, вызывающий incubateObject(), сам создаётся асинхронно.

Все три аргумента необязательны.

При успешном выполнении метод возвращает инкубатор, в противном случае null. Инкубатор имеет следующие свойства:

• status Статус инкубатора. Допустимые значения: Component.Ready, Component.Loading и Component.Error.
• object Экземпляр созданного объекта. Будет доступен только после того, как инкубатор перейдет в состояние Ready.
• onStatusChanged Указывает функцию обратного вызова, которая будет вызвана при изменении статуса. Статус передается в качестве параметра в функцию обратного вызова.
• forceCompletion() Вызов для синхронной завершения инкубации.

Следующий пример демонстрирует использование инкубатора:

var component = Qt.createComponent("Button.qml");

var incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status != Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status == Component.Ready) {
            print ("Object", incubator.object, "is now ready!");
        }
    }
} else {
    print ("Object", incubator.object, "is ready immediately!");
}

Динамически созданные экземпляры можно удалить с помощью метода destroy(). Более подробную информацию см. в разделе Динамическое создание QML-объектов из JavaScript.

См. такжеcreateObject().