import 语句

导入语句语法

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.

模块 (名称空间) 导入

The most common type of import is a module import. Clients can import QML 模块 which register QML object types and JavaScript resources into a given namespace.

模块 import 的一般形式如下：

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

The <ModuleIdentifier> is an identifier specified in dotted URI notation, which uniquely identifies the type namespace provided by the module.
The <Version.Number> is a version of the form 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.
The <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.

An example of an unqualified module import is as follows:

import QtQuick

This import allows the use of all of the types provided by the QtQuick module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows:

import QtQuick
Rectangle {
    width: 200
    height: 100
    color: "red"
}

An example of an unqualified import with version would be

import QtQuick 2.10

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:

import QtQuick as Quick

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:

import QtQuick as Quick
Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

For more information about qualified imports, see the upcoming section on 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 QtQuick and thus attempting to use the Rectangle type will fail:

Rectangle {
    width: 200
    height: 100
    color: "red"
}

In this case, the engine will emit an error and refuse to load the file.

C++ 模块导入

通常，C++ 类型的声明是使用 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++.

Importing into a Qualified Local Namespace

The import statement may optionally use the 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 QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the QtQuick module must be prefixed with the CoreItems 名称：

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!" }
}

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:

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!" }
}

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:

import QtQuick as Project
import QtMultimedia as Project
Project.Rectangle {
    width: 100; height: 50
    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

目录导入

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:

import "<DirectoryPath>" [as <Qualifier>]

注意： 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 Network Transparency in QML documents. If the directory is remote, it must contain a directory import listing qmldir file as the QML engine cannot determine the contents of a remote directory if that qmldir file does not exist.

Similar semantics for the <Qualifier> apply to directory imports as for module imports; for more information on the topic, please see the previous section about Importing into a Qualified Local Namespace .

For more information about directory imports, please see the in-depth documentation about directory imports .

JavaScript 资源导入

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:

import "<JavaScriptFile>" as <Identifier>

注意， <Identifier> must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports.

来自模块的 JavaScript 资源

Javascript files can be provided by modules, by adding identifier definitions to the qmldir file which specifies the module.

For example, if the projects.MyQMLProject.MyFunctions module is specified with the following qmldir file, and installed into the QML import path:

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

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:

import QtQuick
import projects.MyQMLProject.MyFunctions
Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

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:

import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs
Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

进一步信息

For more information about JavaScript resources, please see the documentation about 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 在 QML 导入 JavaScript 资源 .

QML 导入路径

当 identified module is imported, the QML engine searches the import 路径 for a matching module.

此 import 路径，如返回通过 QQmlEngine::importPathList (), defines the default locations to be searched by the engine. By default, this list contains:

当前文件的目录
位置指定通过 QLibraryInfo::QmlImportsPath
Paths specified by the QML_IMPORT_PATH 环境变量
The qrc:/qt-project.org/imports path inside the resources.
The qrc:/qt/qml path inside the resources (since Qt 6.5).

Additional import paths can be added through QQmlEngine::addImportPath () 或 QML_IMPORT_PATH environment variable. When running the qml tool , you can also use the -I option to add an import path.

You can specify multiple import paths in the 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.

注意： It is recommended that applications and libraries put their modules under "qrc:/qt/qml". This happens by default when the module is created with qt_add_qml_module() and QTP0001 is enabled.

调试

The QML_IMPORT_TRACE environment variable can be useful for debugging when there are problems with finding and loading modules. See 调试模块导入了解更多信息。