1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-syntax-imports.html
\title Import Statements
\brief Description of import statements in QML
\section1 Syntax of an Import Statement
The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file.
The syntax for the \c import statement is:
\code
import <module> <major version>.<minor version> [as <namespace>]
\endcode
When a QML file is loaded by the engine, the only QML types that are automatically made available to that file are those that are \l{Defining Object Types through QML Documents}{defined by .qml files} within the same directory. Any types defined elsewhere are not accessible unless an \c import statement has imported the module that contains the required type. For example, the \c QtQuick module must be imported in order to use any of its QML types:
\qml
import QtQuick 2.0
Rectangle {} // won't work if import line is missing, engine will refuse to load the file
\endqml
The \c <module> can be either a filesystem path to the module, or an identifier for the module if it is accessible to the import path. For example:
\code
import "../relative/path/to/module"
import "/absolute/path/to/module"
import com.company.module
\endcode
(See \l {QML Modules} for more information on defining and importing located and installed modules.)
\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.
\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.
\section1 QML Import Path
When an \l{qtqml-modules-installedmodules.html}{installed 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::ImportsPath
\li Paths specified by the \c QML_IMPORT_PATH environment variable
\endlist
Additional import paths can be added through QQmlEngine::addImportPath() or the
\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}{qmlscene}
tool, you can also use the \c -I option to add an import path.
\section1 Namespaced Imports
The \c import statement may optionally use the \c as keyword to specify that the module should be imported into a particular namespace. If a namespace is specified, then any references to the types made available by the module must be prefixed by the namespace qualifier.
Below, the 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 2.0 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 2.0 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 QtQuick!" }
}
\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
\section1 Relative Directory Imports
\section1 JavaScript File Imports
JavaScript files must always be imported with a named import:
\qml
import "somescript.js" as MyScript
Item {
//...
Component.onCompleted: MyScript.doSomething()
}
\endqml
The qualifier ("MyScript" in the above example) must be unique within the QML document.
Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
Javascript files can be provided by modules, by adding Namespace definitions to the
\l{Adding Module Metadata with a qmldir file}{qmldir file} for the module. For example:
\code
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js
\endcode
Javascript can be imported from a module, where they will have the namespace defined
for them in the module's \c qmldir file:
\qml
import projects.MyQMLProject.MyFunctions 1.0
Window {
Component.onCompleted: { SystemFunctions.cleanUp(); }
}
\endqml
Javascript provided by modules can also be imported into namespaces:
\qml
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
import org.example.Functions 1.0 as TheirFuncs
Window {
Component.onCompleted: {
MyFuncs.SystemFunctions.cleanUp();
TheirFuncs.SystemFunctions.shutdown();
}
}
\endqml
\section1 Version Specification
\section1 Import Qualifier
*/
|
