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

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

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

Свойства

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

Прикрепленные сигналы

• completed()
• destruction()

Методы

• QtObject createObject(QtObject parent, object properties)
• строка errorString()
• объект incubateObject(QtObject parent, object 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.

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

QtObject createObject(QtObject parent, object 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 соответственно:

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

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

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

строка errorString()

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

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

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

объект incubateObject(QtObject parent, object 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() - Вызов для завершения инкубации синхронно.

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

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

const 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().