Класс QQmlComponent

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

Этот класс был представлен в Qt 5.0.

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

Общие типы

Свойства

• 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 будет статус Загрузка status. Приложение должно дождаться, пока компонент не станет Готов, перед вызовом 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.

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

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

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

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

QQmlContext *QQmlComponent::creationContext() const

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

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.

void QQmlComponent::setInitialProperties(QObject *component, const QVariantMap &properties)

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

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

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

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