Класс 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 будет статус Loading status. Приложение должно подождать, пока компонент не станет Ready, прежде чем вызывать QQmlComponent::create().

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

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 (по умолчанию), он создаст экземпляр в корневом контексте корневого контекста движка.

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

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

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.