1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-javascript-imports.html
5\title Importing JavaScript Resources in QML
6\brief Description of how to import and use JavaScript resources in QML documents
8\l{qtqml-javascript-resources.html}{JavaScript resources} may be imported by
9QML documents and other JavaScript resources. JavaScript resources may be
10imported via either relative or absolute URLs. In the case of a relative URL,
11the location is resolved relative to the location of the \l {QML Documents}{QML document} or
12\l{qtqml-javascript-resources.html}{JavaScript Resource} that contains the
13import. If the script file is not accessible, an error will occur. If the
14JavaScript needs to be fetched from a network resource, the component's
15\l {QQmlComponent::status()}{status} is set to "Loading" until the script has
18JavaScript resources may also import QML modules and other JavaScript
19resources. The syntax of an import statement within a JavaScript resource
20differs slightly from an import statement within a QML document, which is
21documented thoroughly below.
23\section1 Importing a JavaScript Resource from a QML Document
25A QML document may import a JavaScript resource with the following syntax:
27import "ResourceURL" as Qualifier
31import "jsfile.js" as Logic
34Imported JavaScript resources are always qualified using the "as" keyword. The
35qualifier for JavaScript resources must start with an uppercase letter, and must
36be unique, so there is always a one-to-one mapping between qualifiers and JavaScript
37files. (This also means qualifiers cannot be named the same as built-in JavaScript
38objects such as \c Date and \c Math).
40The functions defined in an imported JavaScript file are available to objects
41defined in the importing QML document, via the
42\c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources
43may take parameters whose types can be any QML value types or
44object types, as well as normal JavaScript types. The normal
45\l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to
46parameters and return values when calling such functions from QML.
48\section1 Imports Within JavaScript Resources
50In \c {QtQuick 2.0}, support has been added to allow JavaScript resources to import
51other JavaScript resources and also QML type namespaces using a variation of
52the standard QML import syntax (where all of the previously described rules and
55Due to the ability of a JavaScript resource to import another script or QML
56module in this fashion in \c {QtQuick 2.0}, some extra semantics are defined:
58\li a script with imports will not inherit imports from the QML document which imported it (so accessing Component.errorString will fail, for example)
59\li a script without imports will inherit imports from the QML document which imported it (so accessing Component.errorString will succeed, for example)
60\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML document even if it imports no other scripts or modules
63The first semantic is conceptually correct, given that a particular script
64might be imported by any number of QML files. The second semantic is retained
65for the purposes of backwards-compatibility. The third semantic remains
66unchanged from the current semantics for shared scripts, but is clarified here
67in respect to the newly possible case (where the script imports other scripts
70\section2 Importing a JavaScript Resource from Another JavaScript Resource
72A JavaScript resource may import another in the following fashion:
74import * as MathFunctions from "factorial.mjs";
78.import "filename.js" as Qualifier
81The former is standard ECMAScript syntax for importing ECMAScript modules, and
82only works from within ECMAScript modules as denoted by the \c mjs file
83extension. The latter is an extension to JavaScript provided by the \c QML
84engine and will work also with non-modules. As an extension superseded by the
85ECMAScript standard, its usage is discouraged.
87When a JavaScript file is imported this way, it is imported with a qualifier.
88The functions in that file are then accessible from the importing script via the
89qualifier (that is, as \tt{Qualifier.functionName(params)}).
91Sometimes it is desirable to have the functions made available in the importing
92context without needing to qualify them. In this case ECMAScript modules and the
93JavaScript \c import statement should be used without the \c as qualifier.
95For example, the QML code below left calls \c showCalculations() in \c script.mjs,
96which in turn can call \c factorial() in \c factorial.mjs, as it has included
97\c factorial.mjs using \c import.
101\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
102\li \snippet qml/integrating-javascript/includejs/script.mjs 0
104\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0
107The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript
108file from another without using ECMAScript modules and without qualifying the
109import. It makes all functions and variables from the other file available in
110the current file's namespace, but ignores all pragmas and imports defined in
111that file. This is not a good idea as a function call should never modify the
114\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It
115will be removed in a future version of Qt.
117\section2 Importing a QML Module from a JavaScript Resource
119A JavaScript resource may import a QML module in the following fashion:
121.import TypeNamespace MajorVersion.MinorVersion as Qualifier
124Below you can see an example that also shows how to use the QML types from a
125module imported in javascript:
128.import Qt.test 1.0 as JsQtTest
130var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3
133In particular, this may be useful in order to access functionality provided
134via a singleton type; see QML_SINGLETON for more information.
136Your JavaScript resource by default can access all imports of the component
137that imports the resource. It does not have access to the componpents's imports
138if it is declared as a stateless library (using \c{.pragma library}) or contains
139an explicit \c{.import} statment.
141\note The .import syntax doesn't work for scripts used in \l {WorkerScript}
143\sa {Defining JavaScript Resources in QML}