Импорт 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 будут применяться стандартные правила преобразования типов данных.

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

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

Из-за возможности 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.js
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

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

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