Динамическое создание QML-объектов из JavaScript

QML поддерживает динамическое создание объектов из JavaScript. Это полезно для отсрочки инициализации объектов до необходимости, тем самым улучшая время запуска приложения. Это также позволяет динамически создавать визуальные объекты и добавлять их в сцену в ответ на пользовательский ввод или другие события.

См. пример Динамической сцены для демонстрации концепций, обсуждаемых на этой странице.

Динамическое создание объектов

Существует два способа динамического создания объектов из JavaScript. Вы можете либо вызвать Qt.createComponent() для динамического создания объекта Component, либо использовать Qt.createQmlObject() для создания объекта из строки QML. Создание компонента предпочтительнее, если у вас уже определен компонент в документе QML, и вы хотите динамически создавать экземпляры этого компонента. В противном случае создание объекта из строки QML полезно, когда сам QML-объект генерируется во время выполнения.

Динамическое создание компонента

Для динамической загрузки компонента, определенного в файле QML, вызовите функцию Qt.createComponent() в объекте Qt. Эта функция принимает URL-адрес файла QML в качестве единственного аргумента и создает объект Component из этого URL.

После получения объекта Component можно вызвать его метод createObject() для создания экземпляра компонента. Эта функция может принимать один или два аргумента:

• Первый — родительский объект для нового объекта. Родительским объектом может быть графический объект (например, типа Item) или неграфический объект (например, типа QtObject или C++ QObject). Только графические объекты с графическими родительскими объектами будут отображаться на визуальной области Qt Quick. Если вы хотите установить родителя позже, вы можете безопасно передать null в эту функцию.
• Второй аргумент необязателен и представляет собой карту пар свойство-значение, которые определяют начальные значения свойств объекта. Значения свойств, указанные в этом аргументе, применяются к объекту до завершения его создания, что позволяет избежать ошибок привязки, которые могут возникнуть, если определённые свойства должны быть инициализированы для активации других привязок свойств. Кроме того, есть небольшие преимущества производительности по сравнению с определением значений свойств и привязок после создания объекта.

Вот пример. Во-первых, есть Sprite.qml, который определяет простой QML-компонент:

import QtQuick 2.0

Rectangle { width: 80; height: 50; color: "red" }

Наш основной файл приложения, main.qml, импортирует файл JavaScript componentCreation.js, который будет создавать объекты Sprite:

import QtQuick 2.0
import "componentCreation.js" as MyScript

Rectangle {
    id: appWindow
    width: 300; height: 300

    Component.onCompleted: MyScript.createSpriteObjects();
}

Вот componentCreation.js. Обратите внимание, что он проверяет, равен ли статус компонента status Component.Ready, прежде чем вызывать createObject(), на случай, если файл QML загружается через сеть и, следовательно, не готов сразу.

var component;
var sprite;

function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    if (component.status == Component.Ready)
        finishCreation();
    else
        component.statusChanged.connect(finishCreation);
}

function finishCreation() {
    if (component.status == Component.Ready) {
        sprite = component.createObject(appWindow, {"x": 100, "y": 100});
        if (sprite == null) {
            // Error Handling
            console.log("Error creating object");
        }
    } else if (component.status == Component.Error) {
        // Error Handling
        console.log("Error loading component:", component.errorString());
    }
}

Если вы уверены, что загружаемый файл QML — это локальный файл, вы можете опустить функцию finishCreation() и сразу вызвать createObject():

function createSpriteObjects() {
    component = Qt.createComponent("Sprite.qml");
    sprite = component.createObject(appWindow, {"x": 100, "y": 100});

    if (sprite == null) {
        // Error Handling
        console.log("Error creating object");
    }
}

Обратите внимание, что в обоих случаях createObject() вызывается с appWindow в качестве аргумента родителя, поскольку динамически создаваемый объект является визуальным (Qt Quick) объектом. Созданный объект станет дочерним объектом объекта appWindow в main.qml, и появится в сцене.

При использовании файлов с относительными путями путь должен быть относительным к файлу, в котором выполняется Qt.createComponent().

Для подключения сигналов к (или получения сигналов от) динамически созданных объектов используйте метод сигнала connect(). См. Подключение сигналов к методам и сигналам для получения дополнительной информации.

Также возможно создание экземпляров компонентов без блокировки с помощью функции incubateObject().

Создание объекта из строки QML

Если QML не определён до момента выполнения, вы можете создать QML-объект из строки QML, используя функцию Qt.createQmlObject(), как в следующем примере:

var newObject = Qt.createQmlObject('import QtQuick 2.0; Rectangle {color: "red"; width: 20; height: 20}',
                                   parentItem,
                                   "dynamicSnippet1");

Первый аргумент — строка QML для создания. Как и в новом файле, вам необходимо импортировать любые типы, которые вы хотите использовать. Второй аргумент — родительский объект для нового объекта, и семантика аргумента родителя, которая применяется к компонентам, аналогично применимы для createQmlObject(). Третий аргумент — путь к файлу, ассоциируемый с новым объектом; используется для отчётов об ошибках.

Если строка QML импортирует файлы с использованием относительных путей, путь должен быть относительным к файлу, в котором определён родительский объект (второй аргумент метода).

Важно: При создании статических QML-приложений файлы QML сканируются для обнаружения зависимостей импорта. Таким образом, все необходимые плагины и ресурсы разрешаются во время компиляции. Однако учитываются только явные инструкции импорта (те, которые находятся в начале файла QML), а не инструкции импорта, заключенные в строковые литералы. Поэтому для поддержки статических сборок вам необходимо убедиться, что файлы QML, использующие Qt.createQmlObject(), содержат все необходимые импорты в верхней части файла помимо строковых литералов.

Поддержка динамически созданных объектов

При управлении динамически созданными объектами необходимо убедиться, что контекст создания сохраняется дольше, чем созданный объект. В противном случае, если контекст создания будет уничтожен первым, привязки в динамическом объекте больше не будут работать.

Фактический контекст создания зависит от того, как создаётся объект:

• Если используется Qt.createComponent(), контекстом создания является QQmlContext, в котором вызван этот метод.
• Если вызван Qt.createQmlObject(), контекстом создания является контекст родительского объекта, переданного в этот метод.
• Если определён объект Component{}, и вызваны createObject() или incubateObject() на этом объекте, контекстом создания является контекст, в котором определён Component.

Также обратите внимание, что, хотя динамически созданные объекты могут использоваться так же, как и другие объекты, они не имеют идентификатора в QML.

Удаление объектов динамически

Во многих пользовательских интерфейсах достаточно установить непрозрачность визуального объекта в 0 или переместить визуальный объект за пределы экрана вместо его удаления. Однако, если у вас много динамически созданных объектов, вы можете получить заметное улучшение производительности, если неиспользуемые объекты будут удалены.

Обратите внимание, что вы никогда не должны вручную удалять объекты, которые были динамически созданы фабриками QML (такими как Loader и Repeater). Также следует избегать удаления объектов, которые вы не создавали сами.

Объекты можно удалить, используя метод destroy(). Этот метод имеет необязательный аргумент (по умолчанию 0), который определяет приблизительную задержку в миллисекундах до уничтожения объекта.

Вот пример. application.qml создаёт пять экземпляров компонента SelfDestroyingRect.qml. Каждый экземпляр выполняет NumberAnimation, а по окончании анимации вызывает destroy() на корневом объекте, чтобы уничтожить себя:

import QtQuick 2.0

Item {
    id: container
    width: 500; height: 100

    Component.onCompleted: {
        var component = Qt.createComponent("SelfDestroyingRect.qml");
        for (var i=0; i<5; i++) {
            var object = component.createObject(container);
            object.x = (object.width + 10) * i;
        }
    }
}

import QtQuick 2.0

Rectangle {
    id: rect
    width: 80; height: 80
    color: "red"

    NumberAnimation on opacity {
        to: 0
        duration: 1000

        onRunningChanged: {
            if (!running) {
                console.log("Destroying...")
                rect.destroy();
            }
        }
    }
}

В качестве альтернативы, application.qml мог уничтожить созданный объект, вызвав object.destroy().

Обратите внимание, что безопасно вызывать destroy() для объекта внутри этого объекта. Объекты не уничтожаются сразу после вызова destroy(), а очищаются в какой-то момент между окончанием этого блока скрипта и следующим кадром (если не была указана задержка отличная от нуля).

Также обратите внимание, что если экземпляр SelfDestroyingRect был создан статически, как в этом примере:

Item {
    SelfDestroyingRect {
        // ...
    }
}

Это приведёт к ошибке, поскольку объекты могут быть уничтожены только динамически, если они были динамически созданы.

Объекты, созданные с помощью Qt.createQmlObject(), аналогичным образом можно уничтожить, используя destroy():

var newObject = Qt.createQmlObject('import QtQuick 2.0; Rectangle {color: "red"; width: 20; height: 20}',
                                   parentItem,
                                   "dynamicSnippet1");
newObject.destroy(1000);