QML Reference Guide 07: Import JavaScript Resources into QML

JavaScript resources can be imported from QML documents and other JavaScript resources. JavaScript resources can be imported through relative or absolute URLs. If it is a relative URL, the location is resolved relative to the location that contains the imported QML document or JavaScript resource. If the script file is not accessible, an error will occur. If you need to get JavaScript from a network resource, before downloading the script, the state of the component will be set to "loading".

JavaScript resources can also be imported into QML modules and other JavaScript resources. The syntax of the import statement in the JavaScript resource is slightly different from the import statement in the QML document. The QML document is described in detail below.

Import JavaScript resources from QML documents

QML documents can use the following syntax to import JavaScript resources:

import "ResourceURL" as Qualifier

E.g:

 import "jsfile.js" as Logic

Imported JavaScript resources are always qualified with the "as" keyword. The qualifier of the JavaScript resource must start with a capital letter and must be unique, so there is always a one-to-one mapping between the qualifier and the JavaScript file. (This also means that the name of the qualifier cannot be the same as the built-in JavaScript objects (such as Date and Math)).

Through the "Qualifier.functionName (params)" syntax, the functions defined in the imported JavaScript file can be used to import the objects defined in the QML document. Functions in JavaScript resources can take parameters whose type can be any supported QML basic type or object type as well as ordinary JavaScript types. When calling such functions from QML, the general data type conversion rules will apply to the parameters and return values.

Import in JavaScript resources

In QtQuick 2.0, support was added to allow JavaScript resources to use variants of the standard QML import syntax (applicable to all previously described rules and qualifications) to import other JavaScript resources and QML-type namespaces.

Since JavaScript resources can import another script or QML module in this way, QtQuick 2.0 defines some additional semantics:

A script with an import will not inherit the import of the QML document that imported the script (for example, access to Component.errorString will fail).

Scripts that are not imported will inherit the import of the QML document that imported the script (for example, access to Component.errorString will be successful).

Shared scripts (that is defined as .pragma libraries) will not inherit any QML document imports, even if it does not import other scripts or modules

The first kind of semantics is conceptually correct because a specific script can be imported through any number of QML files. The second semantic is retained for backward compatibility. The third semantics remains the same as the current semantics of shared scripts, but the new possibilities (scripts importing other scripts or modules) are explained here.

Import JavaScript resources from another JavaScript resource

A JavaScript resource can be imported into another resource in the following ways:

 .import "filename.js" as Qualifier

E.g:

 import * as MathFunctions from "factorial.mjs";

The latter is the standard ECMAScript syntax for importing ECMAScript modules, and only works inside the ECMAScript module, as shown by the mjs file extension. The former is an extension of JavaScript provided by the QML engine and can also be used for non-modules.

When importing JavaScript files in this way, they will be imported using qualifiers. You can then access the functions in the file from the import script through the qualifier (that is, as Qualifier.functionName (params)).

Sometimes, you need to make functions available in the import context without qualifying them. In this case, import should use ECMAScript modules and JavaScript statements instead of the as qualifier.

For example, the QML code shown below on the left shows script.mjs in showCalculations (), which in turn can call factorial () in factorial.mjs because it includes factorial.mjs using 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);
}      

The Qt.include () function includes imports from another JavaScript file without using the ECMAScript module and without having to limit it. It makes all functions and variables in another file available in the name space of the current file, but ignores all miscellaneous functions and imports defined in the file. This is not a good idea, because function calls should never modify the caller's context.

Qt.include () is not recommended and should be avoided. It will be removed in a future version of Qt.

Import QML modules from JavaScript resources

JavaScript resources can be imported into QML modules in the following ways:

 .import TypeNamespace MajorVersion.MinorVersion as Qualifier

Below, you can see an example that also shows how to use the QML type in a module imported by javascript:

.import Qt.test 1.0 as JsQtTest
 
var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

In particular, this may be useful for accessing functions provided through singleton types; for more information, see qmlRegisterSingletonType ().

Note: The .import syntax does not apply to the script used in WorkerScript