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

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

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

Свойства

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

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

• completed()
• destruction()

Методы

• объект createObject(QtObject parent, объект properties)
• строка errorString()
• объект incubateObject(Item parent, объект properties, перечисление mode)

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

Компоненты — это многократно используемые, инкапсулированные типы 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 может быть объявлен в любом объекте. Порядок выполнения обработчиков не определён.

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

Примечание: Соответствующий обработчик — onCompleted.

destruction()

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

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

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

Примечание: Соответствующий обработчик — onDestruction.

См. также Qt QML.

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

объект createObject(QtObject parent, объект properties)

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

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

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

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

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

Аргумент properties задаётся как карта элементов свойство-значение. Например, код ниже создаёт объект с начальными 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(Item parent, объект properties, перечисление mode)

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

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

Аргумент properties задаётся как карта элементов свойство-значение, которые будут установлены на созданный объект во время его построения. mode может быть 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().