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

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

JavaScript-ресурсы также могут импортировать QML-модули и другие JavaScript-ресурсы. Синтаксис инструкции import в JavaScript-ресурсе немного отличается от инструкции import в документе 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 будут применяться обычные правила преобразования типов данных data type conversion rules к параметрам и возвращаемым значениям.

Импорты внутри 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 * as MathFunctions from "factorial.mjs";

Или:

.import "filename.js" as Qualifier

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

Когда 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"
export { factorial }

export 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

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