diff options
Diffstat (limited to 'src/qml/doc/src/javascript/imports.qdoc')
| -rw-r--r-- | src/qml/doc/src/javascript/imports.qdoc | 113 |
1 files changed, 54 insertions, 59 deletions
diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 7da2cd22fe..ef5376cb54 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-imports.html \title Importing JavaScript Resources in QML @@ -64,7 +40,7 @@ objects such as \c Date and \c Math). The functions defined in an imported JavaScript file are available to objects defined in the importing QML document, via the \c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources -may take parameters whose type can be any of the supported QML basic types or +may take parameters whose types can be any QML value types or object types, as well as normal JavaScript types. The normal \l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to parameters and return values when calling such functions from QML. @@ -95,13 +71,49 @@ or modules). A JavaScript resource may import another in the following fashion: \code -.import "filename.js" as Qualifier +import * as MathFunctions from "factorial.mjs"; \endcode -For example: +Or: \code -.import "factorial.js" as MathFunctions +.import "filename.js" as Qualifier \endcode +The former is standard ECMAScript syntax for importing ECMAScript modules, and +only works from within ECMAScript modules as denoted by the \c mjs file +extension. The latter is an extension to JavaScript provided by the \c QML +engine and will work also with non-modules. As an extension superseded by the +ECMAScript standard, its usage is discouraged. + +When a JavaScript file is imported this way, it is imported with a qualifier. +The functions in that file are then accessible from the importing script via the +qualifier (that is, as \tt{Qualifier.functionName(params)}). + +Sometimes it is desirable to have the functions made available in the importing +context without needing to qualify them. In this case ECMAScript modules and the +JavaScript \c import statement should be used without the \c as qualifier. + +For example, the QML code below left calls \c showCalculations() in \c script.mjs, +which in turn can call \c factorial() in \c factorial.mjs, as it has included +\c factorial.mjs using \c import. + +\table +\row +\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 +\li \snippet qml/integrating-javascript/includejs/script.mjs 0 +\row +\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0 +\endtable + +The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript +file from another without using ECMAScript modules and without qualifying the +import. It makes all functions and variables from the other file available in +the current file's namespace, but ignores all pragmas and imports defined in +that file. This is not a good idea as a function call should never modify the +caller's context. + +\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It +will be removed in a future version of Qt. + \section2 Importing a QML Module from a JavaScript Resource A JavaScript resource may import a QML module in the following fashion: @@ -109,42 +121,25 @@ A JavaScript resource may import a QML module in the following fashion: .import TypeNamespace MajorVersion.MinorVersion as Qualifier \endcode -For example: +Below you can see an example that also shows how to use the QML types from a +module imported in javascript: + \code .import Qt.test 1.0 as JsQtTest + +var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3 \endcode In particular, this may be useful in order to access functionality provided -via a singleton type; see qmlRegisterSingletonType() for more information. - -\note The .import syntax doesn't work for scripts used in the \l {WorkerScript} - -\section1 Including a JavaScript Resource from Another JavaScript Resource - -When a JavaScript file is imported, it must be imported with a qualifier. The -functions in that file are then accessible from the importing script via the -qualifier (that is, as \tt{Qualifier.functionName(params)}). Sometimes it is -desirable to have the functions made available in the importing context without -needing to qualify them, and in this circumstance the \l{QtQml::Qt::include()} -{Qt.include()} function may be used to include one JavaScript file from another. -This copies all functions from the other file into the current file's -namespace, but ignores all pragmas and imports defined in that file. +via a singleton type; see QML_SINGLETON for more information. -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QtQml::Qt::include()}{Qt.include()}. - -\table -\row -\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 -\li \snippet qml/integrating-javascript/includejs/script.js 0 -\row -\li \snippet qml/integrating-javascript/includejs/factorial.js 0 -\endtable +Your JavaScript resource by default can access all imports of the component +that imports the resource. It does not have access to the componpents's imports +if it is declared as a stateless library (using \c{.pragma library}) or contains +an explicit \c{.import} statment. -Notice that calling \l {QtQml::Qt::include()}{Qt.include()} copies all functions -from \c factorial.js into the \c MyScript namespace, which means the QML -component can also access \c factorial() directly as \c MyScript.factorial(). +\note The .import syntax doesn't work for scripts used in \l {WorkerScript} +\sa {Defining JavaScript Resources in QML} */ |