A module is a set of QML content files that can be imported as a unit into a QML application. Modules can be used to organize QML content into independent units, and they can use a versioning mechanism that allows for independent upgradability of the modules.
While QML component files within the same directory are automatically accessible within the global namespace, components defined elsewhere must be imported explicitly using the
import
statement to import them as modules. For example, an
import
statement is required to use:
An
import
statement includes the module name, and possibly a version number. This can be seen in the snippet commonly found at the top of QML files:
import QtQuick 1.0
This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML library itself must be imported to use any of the QML 元素 , as they are not included in the global namespace by default.)
The
Qt
module is an
installed
module; it is found in the
import 路径
. There are two types of QML modules: located modules (defined by a URL) and installed modules (defined by a URI).
Located modules can reside on the local filesystem or a network resource, and are referred to by a quoted location URL that specifies the filesystem or network URL. They allow any directory with QML content to be imported as a module, whether the directory is on the local filesystem or a remote server.
For example, a QML project may have a separate directory for a set of custom UI components. These components can be accessed by importing the directory using a relative or absolute path, like this:
| Directory structure | Contents of application.qml |
MyQMLProject
|- MyComponents
|- CheckBox.qml
|- Slider.qml
|- Window.qml
|- Main
|- application.qml
|
import "../MyComponents" Window { Slider { // ... } CheckBox { // ... } } |
Similarly, if the directory resided on a network source, it could be imported like this:
import "http://www.my-server.com/MyQMLProject/MyComponents" import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0
A located module can also be imported as a network resource if it has a
qmldir 文件
in the directory that specifies the QML files to be made available by the module. For example, if the
MyComponents
directory contained a
qmldir
file defined like this:
Slider 1.0 Slider.qml CheckBox 1.0 CheckBox.qml Window 1.0 Window.qml
若
MyComponents
directory was then hosted as a network resource, it could be imported as a module, like this:
import "http://the-server-name.com/MyQMLProject/MyComponents" Window { Slider { // ... } CheckBox { // ... } }
with an optional "1.0" version specification. Notice the import would fail if a later version was used, as the
qmldir
file specifies that these elements are only available in the 1.0 version.
Note that modules imported as a network resource allow only access to components defined in QML files; components defined by C++ QML extension plugins are not available.
Installed modules are modules that are made available through the QML import path, as defined by QDeclarativeEngine::importPathList (), or modules defined within C++ application code. An installed module is referred to by a URI, which allows the module to be imported from QML code without specifying a complete filesystem path or network resource URL.
When importing an installed module, an un-quoted URI is used, with a mandatory version number:
import QtQuick 1.0 import com.nokia.qml.mymodule 1.0
When a module is imported, the QML engine searches the QML import path for a matching module. The root directory of the module must contain a qmldir 文件 that defines the QML files and/or C++ QML extension plugins that are made available to the module.
Modules that are installed into the import path translate the URI into directory names. For example, the qmldir file of the module
com.nokia.qml.mymodule
must be located in the subpath
com/nokia/qml/mymodule/qmldir
somewhere in the QML import path. In addition it is possible to store different versions of the module in subdirectories of its own. For example, a version 2.1 of the module could be located under
com/nokia/qml/mymodule.2/qmldir
or
com/nokia/qml/mymodule.2.1/qmldir
. The engine will automatically load the module which matches best.
The import path, as returned by QDeclarativeEngine::importPathList (), defines the default locations to be searched by the QML engine for a matching module. By default, this list contains:
QML_IMPORT_PATH
环境变量
Additional import paths can be added through
QDeclarativeEngine::addImportPath
() 或
QML_IMPORT_PATH
environment variable. When running the
QML 查看器
, you can also use the
-I
option to add an import path.
As an example, suppose the
MyQMLProject
directory in the
previous example
was located on the local filesystem at
C:\qml\projects\MyQMLProject
。
MyComponents
subdirectory could be made available as an installed module by adding a
qmldir 文件
到
MyComponents
directory that looked like this:
Slider 1.0 Slider.qml CheckBox 1.0 CheckBox.qml Window 1.0 Window.qml
Providing the path
C:\qml
is added to the QML import path using any of the methods listed previously, a QML file located anywhere on the local filesystem can then import the module as shown below, without referring to the module's absolute filesystem location:
import projects.MyQMLProject.MyComponents 1.0 Window { Slider { // ... } CheckBox { // ... } }
Installed modules are also accessible as a network resource. If the
C:\qml
directory was hosted as
http://www.some-server.com/qml
and this URL was added to the QML import path, the above QML code would work just the same.
Note that modules imported as a network resource allow only access to components defined in QML files; components defined by C++ QML extension plugins are not available.
C++ applications can define installed modules directly within the application using
qmlRegisterType
()。例如，
Writing QML extensions with C++ tutorial
defines a C++ class named
PieChart
and makes this type available to QML by calling
qmlRegisterType
():
qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
This allows the application's QML files to use the
PieChart
type by importing the declared
Charts
模块：
import Charts 1.0
For
QML 插件
, the module URI is automatically passed to
QDeclarativeExtensionPlugin::registerTypes
(). This method can be reimplemented by the developer to register the necessary types for the module. Below is the
registerTypes()
implementation from the
QML 插件
范例：
class QExampleQmlPlugin : public QDeclarativeExtensionPlugin { Q_OBJECT public: void registerTypes(const char *uri) { Q_ASSERT(uri == QLatin1String("org.qtproject.TimeExample")); qmlRegisterType<TimeModel>(uri, 1, 0, "Time"); } };
Once the plugin is built and installed, and includes a qmldir 文件 , the module can be imported from QML, like this:
import com.nokia.TimeExample 1.0
Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by a module that is imported as a network resource.
By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.
To import a module into a specific namespace, use the as keyword:
import QtQuick 1.0 as QtLibrary import "../MyComponents" as MyComponents import com.nokia.qml.mymodule 1.0 as MyModule
Types from these modules can then only be used when qualified by the namespace:
QtLibrary.Rectangle { // ... } MyComponents.Slider { // ... } MyModule.SomeComponent { // ... }
Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
import QtQuick 1.0 as Nokia import Ovi 1.0 as Nokia
JavaScript files must always be imported with a named import:
import "somescript.js" as MyScript Item { //... Component.onCompleted: MyScript.doSomething() }
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.
A
qmldir
file is a metadata file for a module that maps all type names in the module to versioned QML files. It is required for installed modules, and located modules that are loaded from a network source.
It is defined by a plain text file named "qmldir" that contains one or more lines of the form:
# <Comment> <TypeName> [<InitialVersion>] <File> internal <TypeName> <File> plugin <Name> [<Path>] typeinfo <File>
# <Comment> lines are used for comments. They are ignored by the QML engine.
<TypeName> [<InitialVersion>] <File> lines are used to add QML files as types. <TypeName> is the type being made available, the optional <InitialVersion> is a version number, and <File> is the (relative) file name of the QML file defining the type.
Installed files do not need to import the module of which they are a part, as they can refer to the other QML files in the module as relative (local) files, but if the module is imported from a remote location, those files must nevertheless be listed in the
qmldir
file. Types which you do not wish to export to users of your module may be marked with the
internal
keyword:
internal <TypeName> <File>
.
The same type can be provided by different files in different versions, in which case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), since the first name-version match is used and a request for a version of a type can be fulfilled by one defined in an earlier version of the module. If a user attempts to import a version earlier than the earliest provided or later than the latest provided, the import produces a runtime error, but if the user imports a version within the range of versions provided, even if no type is specific to that version, no error will occur.
A single module, in all versions, may only be provided in a single directory (and a single
qmldir
file). If multiple are provided, only the first in the search path will be used (regardless of whether other versions are provided by directories later in the search path).
The versioning system ensures that a given QML file will work regardless of the version of installed software, since a versioned import only imports types for that version, leaving other identifiers available, even if the actual installed version might otherwise provide those identifiers.
plugin <Name> [<Path>]
lines are used to add
QML C++ plugins
to the module. <Name> is the name of the library. It is usually not the same as the file name of the plugin binary, which is platform dependent; e.g. the library
MyAppTypes
would produce
libMyAppTypes.so
on Linux and
MyAppTypes.dll
在 Windows。
<Path> is an optional argument specifying either an absolute path to the directory containing the plugin file, or a relative path from the directory containing the
qmldir
file to the directory containing the plugin file. By default the engine searches for the plugin library in the directory that contains the
qmldir
file. The plugin search path can be queried with
QDeclarativeEngine::pluginPathList
() and modified using
QDeclarativeEngine::addPluginPath
(). When running the
QML 查看器
，使用
-P
option to add paths to the plugin search path.
typeinfo <File> lines add type description files to the module that can be read by QML tools such as Qt Creator to get information about the types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes file.
Without such a file QML tools may be unable to offer features such as code completion for the types defined in your plugins.
The
QML_IMPORT_TRACE
environment variable can be useful for debugging when there are problems with finding and loading modules. See
调试模块导入
了解更多信息。
QML modules may refer to one or more type information files in their qmldir file. These usually have the .qmltypes extension and are read by external tools to gain information about types defined in plugins.
As such qmltypes files have no effect on the functionality of a QML module. Their only use is to allow tools such as Qt Creator to provide code completion, error checking and other functionality to users of your module.
Any module that uses plugins should also ship a type description file.
The best way to create a qmltypes file for your module is to generate it using the
qmlplugindump
tool that is provided with Qt.
Example: If your module is in
/tmp/imports/My/Module
, you could run
qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
to generate type information for your module. Afterwards, add the line
typeinfo mymodule.qmltypes
to
/tmp/imports/My/Module/qmldir
to register it.
While the qmldump tool covers most cases, it does not work if:
In case you have to create a qmltypes file manually or need to adjust an existing one, this is the file format:
import QtQuick.tooling 1.1 // There always is a single Module object that contains all // Component objects. Module { // A Component object directly corresponds to a type exported // in a plugin with a call to qmlRegisterType. Component { // The name is a unique identifier used to refer to this type. // It is recommended you simply use the C++ type name. name: "QDeclarativeAbstractAnimation" // The name of the prototype Component. prototype: "QObject" // The name of the default property. defaultProperty: "animations" // The name of the type containing attached properties // and methods. attachedType: "QDeclarativeAnimationAttached" // The list of exports determines how a type can be imported. // Each string has the format "URI/Name version" and matches the // arguments to qmlRegisterType. Usually types are only exported // once, if at all. // If the "URI/" part of the string is missing that means the // type should be put into the package defined by the URI the // module was imported with. // For example if this module was imported with 'import Foo 4.8' // the Animation object would be found in the package Foo and // QtQuick. exports: [ "Animation 4.7", "QtQuick/Animation 1.0" ] Property { name: "animations"; type: "QDeclarativeAbstractAnimation" // defaults to false, whether this property is read only isReadonly: true // defaults to false, whether the type of this property was a pointer in C++ isPointer: true // defaults to false: whether the type actually is a QDeclarativeListProperty<type> isList: true // defaults to 0: the minor version that introduced this property revision: 1 } Property { name: "loops"; type: "int" } Property { name: "name"; type: "string" } Property { name: "loopsEnum"; type: "Loops" } Enum { name: "Loops" values: { "Infinite": -2, "OnceOnly": 1 } } // Signal and Method work the same way. The inner Parameter // declarations also support the isReadonly, isPointer and isList // attributes which mean the same as for Property Method { name: "restart" } Signal { name: "started"; revision: 2 } Signal { name: "runningChanged" Parameter { type: "bool" } Parameter { name: "foo"; type: "bool" } } } }