Класс 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, SIGNAL(statusChanged(QQmlComponent::Status)),
                         this, SLOT(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-данных data. Если url указан, он используется для установки имени компонента и предоставления базового пути для элементов, разрешённых этим компонентом.

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

Издаётся, когда меняется статус компонента. status будет новым статусом.

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

[override virtual] QQmlComponent::~QQmlComponent()

Деструктор QQmlComponent.

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

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

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

При создании экземпляра 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)

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

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

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

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

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

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

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

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

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

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

См. также QQmlIncubator.

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

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

Если какое-либо из 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.