Класс 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. Необходимо вызвать QQmlComponent::completeCreate() для завершения этапов 2 и 3.

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

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

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

[virtual] void QQmlComponent::completeCreate()

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

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

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

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

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

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

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

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

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

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

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

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

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

Эта функция была добавлена в 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.