Класс QQmlComponent

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

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

Типы публичного доступа

Свойства

• progress : const qreal
• status : const Status
• url : const QUrl

Функции публичного доступа

Свойства доступа

Сигналы

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

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

Экземпляр QQmlComponent может быть создан из файла QML. Например, если существует main.qml файл такого вида:

import QtQuick 2.0

Item {
    width: 200
    height: 200
}

Следующий код загружает этот файл QML как компонент, создаёт экземпляр этого компонента с помощью create(), а затем получает значение свойства Item's width:

QQmlEngine *engine = new QQmlEngine;
QQmlComponent component(engine, QUrl::fromLocalFile("main.qml"));

QObject *myObject = component.create();
QQuickItem *item = qobject_cast<QQuickItem*>(myObject);
int width = item->width();  // width = 200

Для создания экземпляров компонента в коде, где отсутствует экземпляр QQmlEngine, можно использовать qmlContext() или qmlEngine(). Например, в сценарии ниже дочерние элементы создаются в подклассе QQuickItem:

void MyCppItem::init()
{
    QQmlEngine *engine = qmlEngine(this);
    // Or:
    // QQmlEngine *engine = qmlContext(this)->engine();
    QQmlComponent component(engine, QUrl::fromLocalFile("MyItem.qml"));
    QQuickItem *childItem = qobject_cast<QQuickItem*>(component.create());
    childItem->setParentItem(this);
}

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

Компоненты сети

Если URL, переданный в QQmlComponent, является сетевым ресурсом или если документ QML ссылается на сетевой ресурс, QQmlComponent должен извлечь сетевые данные, прежде чем сможет создать объекты. В этом случае у QQmlComponent будет статус Loading status. Приложение должно подождать, пока компонент не станет Ready, прежде чем вызывать QQmlComponent::create().

Следующий пример демонстрирует, как загрузить файл QML из сетевого ресурса. После создания QQmlComponent, он проверяет, загружается ли компонент. Если загружается, он подключается к сигналу QQmlComponent::statusChanged(), в противном случае вызывает метод continueLoading() напрямую. Обратите внимание, что QQmlComponent::isLoading() может быть ложью для сетевого компонента, если компонент был кэширован и сразу готов.

MyApplication::MyApplication()
{
    // ...
    component = new QQmlComponent(engine, QUrl("http://www.example.com/main.qml"));
    if (component->isLoading()) {
        QObject::connect(component, &QQmlComponent::statusChanged,
                         this, &MyApplication::continueLoading);
    } else {
        continueLoading();
    }
}

void MyApplication::continueLoading()
{
    if (component->isError()) {
        qWarning() << component->errors();
    } else {
        QObject *myObject = component->create();
    }
}

Документация по типам членов

Перечисление QQmlComponent::CompilationMode

Указывает, должен ли QQmlComponent загрузить компонент сразу или асинхронно.

Перечисление QQmlComponent::Status

Указывает статус загрузки QQmlComponent.

Документация по членам-функциям

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Создает QQmlComponent из заданного url, задавая указанные parent и engine. Если mode равен Asynchronous, компонент будет загружаться и компилироваться асинхронно.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который является текущей рабочей директорией, если не указано иное.

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

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

Создает QQmlComponent из заданного url, задавая указанные parent и engine.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который является текущей рабочей директорией, если не указано иное.

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

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Создает QQmlComponent из заданного fileName, задавая указанные parent и engine. Если mode равен Asynchronous, компонент будет загружаться и компилироваться асинхронно.

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

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

Создает QQmlComponent из заданного fileName, задавая указанные parent и engine.

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

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

Создаёт QQmlComponent без данных, задавая указанные engine и parent. Установите данные с помощью setData().

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

Загружает QQmlComponent из предоставленного url. Если mode равен Asynchronous, компонент будет загружен и скомпилирован асинхронно.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который является текущей рабочей директорией, если не указано иное.

[slot] void QQmlComponent::loadUrl(const QUrl &url)

Загружает QQmlComponent из предоставленного url.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который является текущей рабочей директорией, если не указано иное.

[signal] void QQmlComponent::progressChanged(qreal progress)

Используется, когда меняется уровень загрузки компонента. progress – текущий уровень выполнения между 0.0 (ничего не загружено) и 1.0 (загрузка завершена).

Примечание: Сигнал уведомления для свойства progress.

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

Устанавливает для QQmlComponent указанные данные QML. Если url предоставлен, он используется для задания имени компонента и для предоставления базового пути для элементов, разрешённых этим компонентом.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

Вызывается, когда меняется состояние компонента. status – новое состояние.

Примечание: Сигнал уведомления для свойства status.

[override virtual] QQmlComponent::~QQmlComponent()

Уничтожает QQmlComponent.

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *context)

Создает экземпляр объекта из этого компонента в заданном context. Возвращает nullptr если создание не удалось.

Когда QQmlComponent создаёт экземпляр, это происходит в три этапа:

1. Создаётся иерархия объектов, и присваиваются константные значения.
2. Впервые оцениваются связи свойств.
3. Если применимо, вызывается QQmlParserStatus::componentComplete() для объектов.

QQmlComponent::beginCreate() отличается от QQmlComponent::create() тем, что выполняет только шаг 1. Для завершения шагов 2 и 3 необходимо вызвать QQmlComponent::completeCreate().

Эта точка разрыва иногда полезна при использовании присоединённых свойств для передачи информации создаваемому компоненту, поскольку она позволяет настроить их начальные значения до применения связей свойств.

Владение возвращённым экземпляром объекта передаётся вызывающей стороне.

См. также completeCreate() и QQmlEngine::ObjectOwnership.

[virtual] void QQmlComponent::completeCreate()

Этот метод предоставляет расширенный контроль над созданием экземпляра компонента. В общем случае программисты должны использовать QQmlComponent::create() для создания компонента.

Эта функция завершает создание компонента, начатое с QQmlComponent::beginCreate(), и должна вызываться после неё.

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

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

Создаёт экземпляр объекта из этого компонента в указанном context. Возвращает nullptr в случае неудачи.

Если context равен nullptr (значение по умолчанию), он создаст экземпляр в корневом контексте (root context) движка.

Владение возвращённым экземпляром объекта переходит к вызывающей стороне.

Если объект, создаваемый из этого компонента, является визуальным элементом, он должен иметь визуального родителя, который можно установить, вызвав QQuickItem::setParentItem(). Подробнее см. Концепции - Визуальный родитель в Qt Quick.

См. также QQmlEngine::ObjectOwnership.

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

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

Если context равен nullptr (значение по умолчанию), он создаст экземпляр в корневом контексте (root context) движка.

forContext задаёт контекст, от которого зависит создание этого объекта. Если forContext создаётся асинхронно, и QQmlIncubator::IncubationMode имеет значение QQmlIncubator::AsynchronousIfNested, этот объект также будет создан асинхронно. Если forContext равен nullptr (значение по умолчанию), для этого решения будет использован context.

Созданный объект и его статус доступны через incubator.

См. также QQmlIncubator.

[since 5.14] QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

Создаёт экземпляр объекта этого компонента в указанном context и инициализирует его свойства верхнего уровня значениями из initialProperties.

Если какое-либо из initialProperties не может быть установлено, isError() вернёт true, а функция errors() может быть использована для получения подробной информации об ошибке(ах).

Данная функция была добавлена в Qt 5.14.

См. также QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

Возвращает QQmlContext, в котором был создан компонент. Это верно только для компонентов, созданных непосредственно из QML.

[since 5.12] QQmlEngine *QQmlComponent::engine() const

Возвращает QQmlEngine этого компонента.

Данная функция была добавлена в Qt 5.12.

QList<QQmlError> QQmlComponent::errors() const

Возвращает список ошибок, возникших во время последней операции компиляции или создания. Возвращает пустой список, если isError() не установлено.

bool QQmlComponent::isError() const

Возвращает true, если status() == QQmlComponent::Error.

bool QQmlComponent::isLoading() const

Возвращает true, если status() == QQmlComponent::Loading.

bool QQmlComponent::isNull() const

Возвращает true, если status() == QQmlComponent::Null.

bool QQmlComponent::isReady() const

Возвращает true, если status() == QQmlComponent::Ready.

[since 5.14] void QQmlComponent::setInitialProperties(QObject *component, const QVariantMap &properties)

Устанавливает свойства верхнего уровня properties компонента component.

Этот метод предоставляет расширенный контроль над созданием экземпляра компонента. В общем случае программисты должны использовать QQmlComponent::createWithInitialProperties для создания компонента.

Используйте этот метод после beginCreate и перед completeCreate. Если предоставленное свойство не существует, выводится предупреждение.

Данная функция была добавлена в Qt 5.14.