imports.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-syntax-imports.html
\title Import Statements
\brief Description of import statements in QML
 
\section1 Syntax of an Import Statement
 
An import statement allows clients to tell the engine which modules, JavaScript
resources and component directories are used within a QML document.  The types
which may be used within a document depends on which modules, resources and
directories are imported by the document.
 
There are three different types of imports.  Each import type has a slightly
different syntax, and different semantics apply to different import types.
 
\section2 Module (Namespace) Imports
 
The most common type of import is a module import.  Clients can import
\l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object
types and JavaScript resources into a given namespace.
 
The generic form of a module import is as follows:
\code
import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]
\endcode
 
\list
  \li The \c <ModuleIdentifier> is an identifier specified in dotted URI
      notation, which uniquely identifies the type namespace provided by the
      module.
  \li The \c <Version.Number> is a version of the form
      \c {MajorVersion.MinorVersion} which specifies which definitions of
      various object types and JavaScript resources will be made available due
      to the import. It can be omitted, in which case the latest version of the
      module is imported. It is also possible to only omit the minor version.
      Then the latest minor version of the given major version is imported.
  \li The \c <Qualifier> is an optional local namespace identifier into which
      the object types and JavaScript resources provided by the module will be
      installed, if given.  If omitted, the object types and JavaScript
      resources provided by the module will be installed into the global
      namespace.
\endlist
 
An example of an unqualified module import is as follows:
\code
import QtQuick
\endcode
 
This import allows the use of all of the types provided by the \c QtQuick
module without needing to specify a qualifier.  For example, the client code to
create a rectangle is as follows:
 
\qml
import QtQuick
 
Rectangle {
    width: 200
    height: 100
    color: "red"
}
\endqml
 
An example of an unqualified import with version would be
\code
import QtQuick 2.10
\endcode
In that case, any types defined in QtQuick 2.11 and higher or in any higher major
version, like 6.0, would not be available to the file.
 
An example of a qualified module import is as follows:
\code
import QtQuick as Quick
\endcode
 
This import allows multiple modules which provide conflicting type names to be
imported at the same time, however since each usage of a type provided by a
module which was imported into a qualified namespace must be preceded by the
qualifier, the conflict is able to be resolved unambiguously by the QML engine.
 
An example of client code which creates a rectangle after using a qualified
module import is as follows:
 
\qml
import QtQuick as Quick
 
Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}
\endqml
 
For more information about qualified imports, see the upcoming section on
\l{Importing Into A Qualified Local Namespace}.
 
Note that if a QML document does not import a module which provides a
particular QML object type, but attempts to use that object type anyway,
an error will occur.  For example, the following QML document does not
import \c QtQuick and thus attempting to use the \c Rectangle type will fail:
 
\qml
Rectangle {
    width: 200
    height: 100
    color: "red"
}
\endqml
 
In this case, the engine will emit an error and refuse to load the file.
 
\section3 C++ Module Imports
 
Usually, C++ types are declared using the QML_ELEMENT and QML_NAMED_ELEMENT()
macros and registered via the build system using QML_IMPORT_NAME and
QML_IMPORT_MAJOR_VERSION. The import name and version given this way form a
module that can be imported to access the types.
 
This is most common in client applications which define their own QML object
types in C++.
 
\section3 Importing into a Qualified Local Namespace
 
The \c import statement may optionally use the \c as keyword to specify that
the types should be imported into a particular document-local namespace. If a
namespace is specified, then any references to the types made available by the
import must be prefixed by the local namespace qualifier.
 
Below, the \c QtQuick module is imported into the namespace "CoreItems". Now, any
references to types from the \c QtQuick module must be prefixed with the
\c CoreItems name:
 
\qml
import QtQuick as CoreItems
 
CoreItems.Rectangle {
    width: 100; height: 100
 
    CoreItems.Text { text: "Hello, world!" }
 
    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}
\endqml
 
A namespace acts as an identifier for a module within the scope of the file.
The namespace does not become an attribute of the root object that can be
referred to externally as can be done with properties, signals and methods.
 
The namespaced import is useful if there is a requirement to use two QML types
that have the same name but are located in different modules. In this case the
two modules can be imported into different namespaces to ensure the code is
referring to the correct type:
 
\qml
import QtQuick as CoreItems
import "../textwidgets" as MyModule
 
CoreItems.Rectangle {
    width: 100; height: 100
 
    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}
\endqml
 
Note that multiple modules can be imported into the same namespace in the same
way that multiple modules can be imported into the global namespace. For example:
 
\snippet qml/imports/merged-named-imports.qml imports
 
\section2 Directory Imports
 
A directory which contains QML documents may also be imported directly in a
QML document.  This provides a simple way for QML types to be segmented into
reusable groupings: directories on the filesystem.
 
The generic form of a directory import is as follows:
\qml
import "<DirectoryPath>" [as <Qualifier>]
\endqml
 
\note Import paths are network transparent: applications can import documents
from remote paths just as simply as documents from local paths. See the general
URL resolution rules for \l{qtqml-documents-networktransparency.html}
{Network Transparency} in QML documents.  If the directory is remote, it must
contain a \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
{directory import listing qmldir file} as the QML engine cannot determine
the contents of a remote directory if that \c qmldir file does not exist.
 
Similar semantics for the \c <Qualifier> apply to directory imports as for
module imports; for more information on the topic, please see the previous
section about \l{Importing into a Qualified Local Namespace}.
 
For more information about directory imports, please see the in-depth
documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}.
 
\section2 JavaScript Resource Imports
 
JavaScript resources may be imported directly in a QML document.  Every
JavaScript resource must have an identifier by which it is accessed.
 
The generic form of a JavaScript resource import is as follows:
\code
import "<JavaScriptFile>" as <Identifier>
\endcode
 
Note that the \c <Identifier> must be unique within a QML document, unlike the
local namespace qualifier which can be applied to module imports.
 
\section3 JavaScript Resources from Modules
 
Javascript files can be provided by modules, by adding identifier
definitions to the \c qmldir file which specifies the module.
 
For example, if the \c projects.MyQMLProject.MyFunctions module is specified
with the following \c qmldir file, and installed into the QML import path:
\code
module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js
\endcode
 
a client application is able to import the JavaScript resources declared in the
module by importing the module and using the identifier associated with a
declared resource:
 
\qml
import QtQuick
import projects.MyQMLProject.MyFunctions
 
Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}
\endqml
 
If the module was imported into a document-local namespace, the JavaScript
resource identifiers must be prefixed with the namespace qualifier in order
to be used:
 
\qml
import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs
 
Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}
\endqml
 
\section3 Further Information
 
For more information about JavaScript resources, please see the documentation
about \l{qtqml-javascript-resources.html}
{defining JavaScript resources in QML}, and for more information about how
to import JavaScript resources, and how imports can be used from within
JavaScript resources, please see the in-depth documentation about
\l{qtqml-javascript-imports.html}{importing JavaScript resources in QML}.
 
 
\section1 QML Import Path
 
When an \l{Identified Modules}{identified module} is imported,
the QML engine searches the \e{import path} for a matching module.
 
This import path, as returned by QQmlEngine::importPathList(), defines the
default locations to be searched by the engine. By default, this list contains:
 
\list
\li The directory of the current file
\li The location specified by QLibraryInfo::QmlImportsPath
\li Paths specified by the \c QML_IMPORT_PATH environment variable
\li The qrc:/qt-project.org/imports path inside the resources.
\li The qrc:/qt/qml path inside the resources (since Qt 6.5).
\endlist
 
Additional import paths can be added through QQmlEngine::addImportPath() or the
\c QML_IMPORT_PATH environment variable. When running the
\l {Prototyping with the QML Runtime Tool}{qml tool}, you can also use the
\c -I option to add an import path.
 
You can specify multiple import paths in the \c QML_IMPORT_PATH environment
variable by joining them using the path separator. On Windows the path separator
is a semicolon (;), on other platforms it is a colon (:). This means that you
cannot specify resource paths or URLs in QML_IMPORT_PATH, as they contain
colons themselves. However, you can add resource paths and URLs by calling
QQmlEngine::addImportPath() programatically.
 
\note It is recommended that applications and libraries put their modules
under "qrc:/qt/qml". This happens by default when the module is created
with  \l{qt_add_qml_module}{qt_add_qml_module()} and \l{QTP0001} is
enabled.
 
 
\section1 Debugging
 
The \c QML_IMPORT_TRACE environment variable can be useful for debugging
when there are problems with finding and loading modules. See
\l{Debugging module imports} for more information.
 
*/