QML modules may use plugins to expose components defined in C++ to QML applications. Qt Creator cannot load the plugins to determine the details of the contained components, and therefore, the modules must provide extra type information for code completion and the semantic checks to work correctly.
To create a QML module and make it appear in the Library view in the Design mode:
.qml
files in a directory dedicated to your module. For example:
imports\asset_imports
.
importPaths
variable. For example
importPaths: [ "imports", "asset_imports" ]
.
qmldir
file for your module and place it in the module directory. For more information, see
Module Definition qmldir Files
.
qmltypes
file, preferably using
qmlplugindump
. For more information see,
Generating qmltypes Files
.
designer
in your module directory.
.metainfo
file for your module and place it in the
designer
directory. Meta information is needed to display the components in the
QML 类型
tab in
Library
. Use a metainfo file delivered with Qt, such as
qtquickcontrols2.metainfo
, as an example.
Your module should now appear in the
QML 导入
tab in
Library
in the Design mode. Your components should appear in the
QML 类型
tab if a valid
.metainfo
file is in place.
When you write a QML module or use QML from a C++ application, and the C++ is a part of your qmake project, you typically register new types with the
qmlRegisterType()
function or expose some class instances with
QQmlContext::setContextProperty
(). The Qt Creator C++ code model now scans for these calls and tells the QML code model about them. This means that properties are displayed during code completion and the JavaScript code checker does not complain about unknown types. However, this works only when the source code is available, and therefore, you must explicitly generate type information for QML modules with plugins before distributing them.
Classes registered with
qmlRegisterType()
can be used as backend objects in the Design mode. For more information, see
Adding Connections
.
Ideally, QML modules have a
plugins.qmltypes
file in the same directory as the
qmldir
file. The
qmltypes
file contains a description of the types exported by the module's plugins and is loaded by Qt Creator when the module is imported.
For Qt 4.8 and later, one or more
qmltypes
files can be listed in the
qmldir
file under the
typeinfo
header. These files will be read in addition to
plugins.qmltypes
。更多信息，见
Writing a qmltypes File
.
You can create and edit
qmltypes
files manually, but you are recommended to use the
qmlplugindump
tool shipped with Qt 4.8 and later to generate them automatically.
Once you have obtained
qmlplugindump
for the Qt version the QML module's plugins were compiled with, run the following command to load My.Module version 1.0 from
/import/path/my/module
including all its plugins and output a description of the plugins' types to
/import/path/my/module/plugins.qmltypes
:
qmlplugindump -nonrelocatable My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
You can safely ignore the debug output.
For Qt 4.7.x, you can compile a version of the tool called
qmldump
from the sources in
<QtCreator>/share/qtcreator/qml/qmldump
if the Qt version contains private headers.
If a module with plugins lacks the
qmltypes
file, Qt Creator tries to generate a temporary file itself by running the
qmldump
program in the background. However, this automatic dumping is a fallback mechanism with many points of failure and you cannot rely upon it.
By default, Qt Creator will look in the QML import path of Qt for QML modules.
If you use qmake and your application adds additional import paths that Qt Creator should use, specify them using
QML_IMPORT_PATH
在
.pro
file of your application:
QML_IMPORT_PATH += path/to/module
.
If you use CMake, add the following command to the CMakeLists.txt file to set the QML import path:
set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}/qml ${CMAKE_BINARY_DIR}/imports CACHE STRING "" FORCE)
The import path affects all the targets built by the CMake project.
A QML emulation layer (also called QML Puppet) is used in the Design mode to render and preview images and to collect data. To be able to render custom types correctly from QML modules, the emulation layer must be built with the same Qt version and compiler as the QML modules.
By default, a fallback emulation layer is provided by Qt Creator and built with the same Qt version as Qt Creator. Therefore, your QML modules will mostly not work out of the box.
To use an emulation layer that is built with the Qt configured in the build and run kit for the project, select 工具 > Options > Qt Quick > Qt Quick Designer > Use QML emulation layer which is built by the selected Qt radio button. Qt Creator builds the emulation layer when you select the Design mode.
A plugin should behave differently depending on whether it is run by the emulation layer or an application. For example, animations should not be run in the Design mode. You can use the value of the
QML_PUPPET_MODE
environment variable to check whether the plugin is currently being run by an application or edited in the Design mode.
If you want to use a different module in the Design mode than in your actual application for example to mockup C++ items, then you can use
QML_DESIGNER_IMPORT_PATH
在
.pro
file (for qmake projects), or declare and set the property
qmlDesignerImportPaths
in your product (for Qbs projects). Modules in the import paths defined in
QML_DESIGNER_IMPORT_PATH
will be used only in the Design mode. For an example, see
Qt Quick Controls - Contact List
.