Импорт ресурсов JavaScript в QML

Ресурсы JavaScript могут быть импортированы документами QML и другими ресурсами JavaScript. Ресурсы JavaScript могут быть импортированы с помощью относительных или абсолютных URL-адресов. В случае относительного URL-адреса расположение определяется относительно расположения документа QML или ресурса JavaScript, который содержит импорт. Если файл скрипта недоступен, произойдет ошибка. Если JavaScript необходимо получить из сетевого ресурса, статус компонента status устанавливается в "Loading" до тех пор, пока скрипт не будет загружен.

Ресурсы JavaScript также могут импортировать модули QML и другие ресурсы JavaScript. Синтаксис инструкции импорта внутри ресурса JavaScript немного отличается от инструкции импорта внутри документа QML, что подробно описано ниже.

Импорт ресурса JavaScript из документа QML

Документ QML может импортировать ресурс JavaScript с помощью следующего синтаксиса:

import "ResourceURL" as Qualifier

Например:

import "jsfile.js" as Logic

Импортируемые ресурсы JavaScript всегда квалифицируются с помощью ключевого слова "as". Квалификатор для ресурсов JavaScript должен начинаться с заглавной буквы и быть уникальным, поэтому всегда существует взаимно-однозначное соответствие между квалификаторами и файлами JavaScript. (Это также означает, что квалификаторы не могут иметь то же имя, что и встроенные объекты JavaScript, такие как Date и Math).

Функции, определенные в импортированном файле JavaScript, доступны объектам, определенным в импортирующем документе QML, с помощью синтаксиса "Qualifier.functionName(params)". Функции в ресурсах JavaScript могут принимать параметры, тип которых может быть любым из поддерживаемых основных типов QML или типов объектов, а также обычными типами JavaScript. При вызове таких функций из QML будут применяться стандартные правила преобразования типов данных.

Импорты внутри ресурсов JavaScript

В QtQuick 2.0, была добавлена поддержка, позволяющая ресурсам JavaScript импортировать другие ресурсы JavaScript, а также пространства имен типов QML с использованием варианта стандартного синтаксиса импорта QML (где все описанные выше правила и квалификации применяются).

Из-за возможности импорта ресурса JavaScript или модуля QML в QtQuick 2.0 были определены дополнительные семантические правила:

• скрипт с импортами не будет наследовать импорты из документа QML, который его импортировал (например, обращение к Component.errorString завершится ошибкой)
• скрипт без импортов будет наследовать импорты из документа QML, который его импортировал (например, обращение к Component.errorString будет успешным)
• совместно используемый скрипт (т. е. определенный как .pragma library) не наследует импорты ни от одного документа QML, даже если он не импортирует другие скрипты или модули

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

Импорт ресурса JavaScript из другого ресурса JavaScript

Ресурс JavaScript может импортировать другой следующим образом:

.import "filename.js" as Qualifier

Например:

import * as MathFunctions from "factorial.mjs";

Последний вариант – это стандартный синтаксис ECMAScript для импорта модулей ECMAScript и работает только внутри модулей ECMAScript, как обозначено расширением файла mjs. Первый вариант – это расширение JavaScript, предоставляемое движком QML и также будет работать с немодульными файлами.

Когда файл JavaScript импортируется таким образом, он импортируется с квалификатором. Функции в этом файле затем доступны из импортирующего скрипта через квалификатор (т. е. как Qualifier.functionName(params)).

Иногда желательно, чтобы функции были доступны в контексте импорта без необходимости их квалификации. В этом случае следует использовать модули ECMAScript и оператор JavaScript import без квалификатора as.

Например, код QML ниже слева вызывает showCalculations() в script.mjs, который, в свою очередь, может вызывать factorial() в factorial.mjs, так как он включил factorial.mjs с помощью import.

import QtQuick 2.0
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}

// script.mjs
import { factorial } from "factorial.mjs"

function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}

// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}

Функция Qt.include() включает один файл JavaScript из другого без использования модулей ECMAScript и без квалификации импорта. Она делает все функции и переменные из другого файла доступными в текущем пространстве имен, но игнорирует все псевдонимы и импорты, определенные в этом файле. Это не лучшая практика, так как вызов функции никогда не должен изменять контекст вызывающего.

Qt.include() устарела и следует избегать ее использования. Она будет удалена в будущих версиях Qt.

Импорт модуля QML из ресурса JavaScript

Ресурс JavaScript может импортировать модуль QML следующим образом:

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

Ниже приведен пример, который также демонстрирует, как использовать типы QML из модуля, импортированного в JavaScript:

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

Это может быть полезно для доступа к функциональности, предоставляемой через тип синглтона; см. QML_SINGLETON для получения дополнительной информации.

Примечание: Синтаксис .import не работает для скриптов, используемых в WorkerScript