Определение JavaScript-ресурсов в QML

Логика программы для приложения QML может быть определена на JavaScript. JavaScript-код может быть определён непосредственно в документах QML или отделён в файлы JavaScript (известные как JavaScript Resources в QML).

В QML поддерживаются два разных вида JavaScript-ресурсов: файлы реализации «за кулисами» и общие (библиотечные) файлы. Оба вида JavaScript-ресурсов могут быть импортированы другими JavaScript-ресурсами или включены в QML-модули.

Ресурс реализации «за кулисами»

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

По умолчанию, при импорте JavaScript-файлов создаётся уникальная, изолированная копия для каждого экземпляра QML-компонента. Если этот JavaScript-файл не импортирует какие-либо ресурсы или модули с инструкцией .import, его код будет выполняться в том же контексте, что и экземпляр QML-компонента, и, следовательно, он сможет получить доступ к и манипулировать объектами и свойствами, объявленными в этом QML-компоненте. В противном случае у него будет свой уникальный контекст, и объекты и свойства QML-компонента должны передаваться функциям JavaScript-файла в качестве параметров, если они необходимы.

Пример ресурса реализации «за кулисами» приведён ниже:

// MyButton.qml
import QtQuick 2.0
import "my_button_impl.js" as Logic // a new instance of this JavaScript resource is loaded for each instance of Button.qml

Rectangle {
    id: rect
    width: 200
    height: 100
    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
        onClicked: Logic.onClicked(rect)
    }
}

// my_button_impl.js
var clickCount = 0;   // this state is separate for each instance of MyButton
function onClicked(button) {
    clickCount += 1;
    if ((clickCount % 5) == 0) {
        button.color = Qt.rgba(1,0,0,1);
    } else {
        button.color = Qt.rgba(0,1,0,1);
    }
}

В общем случае, простая логика должна определяться непосредственно в QML-файле, но более сложная логика должна быть отделена в ресурсы реализации «за кулисами» для обеспечения поддерживаемости и читаемости.

Общие JavaScript-ресурсы (библиотеки)

Некоторые JavaScript-файлы ведут себя как библиотеки — они предоставляют набор вспомогательных функций, которые принимают входные данные и вычисляют выходные, но никогда не изменяют экземпляры QML-компонентов напрямую.

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

// factorial.js
.pragma library

var factorialCount = 0;

function factorial(a) {
    a = parseInt(a);

    // factorial recursion
    if (a > 0)
        return a * factorial(a - 1);

    // shared state
    factorialCount += 1;

    // recursion base-case.
    return 1;
}

function factorialCallCount() {
    return factorialCount;
}

Декларация пragma должна появляться перед любым JavaScript-кодом, за исключением комментариев.

Обратите внимание, что несколько QML-документов могут импортировать "factorial.js" и вызывать предоставляемые им функции factorial и factorialCallCount. Состояние JavaScript-импорта разделяется между QML-документами, которые его импортируют, и поэтому возвращаемое значение функции factorialCallCount может быть ненулевым, когда она вызывается в QML-документе, который никогда не вызывал функцию factorial.

Например:

// Calculator.qml
import QtQuick 2.0
import "factorial.js" as FactorialCalculator // this JavaScript resource is only ever loaded once by the engine, even if multiple instances of Calculator.qml are created

Text {
    width: 500
    height: 100
    property int input: 17
    text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
}

Поскольку они общие, файлы .pragma library не могут напрямую обращаться к объектам или свойствам экземпляров QML-компонентов, хотя значения QML могут передаваться как параметры функций.