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

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

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-модулей и без квалификации импорта. Она делает все функции и переменные из другого файла доступными в пространстве имён текущего файла, но игнорирует все пragma и импорты, определённые в этом файле. Это не рекомендуется, так как вызов функции никогда не должен изменять контекст вызывающей стороны.

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