Тип 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. Он может быть объявлен в любом объекте. Порядок выполнения обработчиков 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(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().