Import Statements 导入语句

Posted 2020-08-02 ddev

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.

导入语句允许客户告诉引擎QML文档内可使用哪些模块、JavaScript资源和组件目录。文档内可以使用哪些类型依赖于被文档导入的模块、资源和目录。

Import Types

导入类型

There are three different types of imports. Each import type has a slightly different syntax, and different semantics apply to different import types.

有3种不同类型的导入。每种导入类型在语法上有细微的差别，不同的语义应用到不同的导入类型。

Module (Namespace) Imports

模块的导入

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

最常见的导入是模块导入。客户可以导入注册了对象类型的模块和JavaScript资源到给定的命名空间。

The generic form of a module import is as follows:

模块导入的一般形式如下：

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.

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.

<ModuleIdentifier>是点分URI表示法指定的标识符，此标识符是模块提供的命名空间类型的唯一识别。

<Version.Number>是大版本.小版本格式的版本号。指定各对象类型和JavaScript资源的哪个版本哪个定义将被提供给导入。

<Qualifier>是可选的本地命名空间，如果给出，它作为模块提供的对象类型和JavaScript资源的识别(命名空间)被安装。如果省略，模块提供的对象类型和JavaScript资源将被安装到全局命名空间。

An example of an unqualified module import is as follows:

如下是一个无限定的模块导入的例子：

import QtQuick 2.0

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:

这样导入允许使用 QtQuick 模块提供的所有类型，不需要指定限定(的命名空间)。例如，客户代码可以创建 rectangle 如下：

import QtQuick 2.0

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

An example of a qualified module import is as follows:

如下是一个限定的模块导入：

import QtQuick 2.0 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.

这样允许同时导入多个提供的类型有名称冲突的模块，由于每一个类型都由被导入限定命名空间的模块提供，所以在使用时必须在前边加上限定符(可以理解为命名空间)，冲突可以通过QML引擎明确地解决掉。

An example of client code which creates a rectangle after using a qualified module import is as follows:

如下是一个使用限定式模块导入的客户代码创建一个 rectangle 的例子：

import QtQuick 2.0 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.

关于限定式导入的更多信息，请看接下来的章节<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.

注意，如果QML文档不导入提供具体QML对象类型的模块，但是尝试使用那个对象类型，将产生错误。

For example, the following QML document does not import QtQuick and thus attempting to use the Rectangle type will fail:

例如，如下的QML文档不导入 QtQuick 并尝试使用 Rectangle 类型，将失败：

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

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

这种情况，引擎将发射一个错误并拒绝载入文件。

Non-module Namespace Imports

无模块命名空间导入

Types can also be registered into namespaces directly via the various registration functions in C++ (such as qmlRegisterType()). The types which have been registered into a namespace in this way may be imported by importing the namespace, as if the namespace was a module identifier.

类型也可以在C++中通过各种注册函数直接注册到命名空间(例如 qmlRegisterType() 函数)。被注册进命名空间的类型可以通过导入命名空间被导入，如同命名空间是一个模块标识。

This is most common in client applications which define their own QML object types in C++ and register them with the QML type system manually.

这是客户端程序中最常用，在C++中定义自己的QML对象类型并且在QML类型系统手动地注册他们。

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 name:

如下，QtQuick 模块被导入进命名空间 "CoreItems" 。现在，任何引用 QtQuick 模块的类型都必须使用 CoreItems 前缀：

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

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:

命名空间入口是有用的,如果需要使用2个QML类型有相同的名字但是位于不同的模块.这种情况下2个模块可以被导入不同的命名空间以确保代码引用正确的类型:

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 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 2.0 as Project
import QtMultimedia 5.0 as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

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.

包含QML文档的目录也可以被直接导入到QML文档。这提供了一个简单的方法以把QML类型分割成可复用的组：文件系统上的目录。

The generic form of a directory import is as follows:

目录导入的格式通常如下：

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

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 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.

注意：导入路径是网络透明的：应用程序可以从远程路径导入文档如同从本地路径导入一样简单。查看通用的QML文档的网络透明的URL解析规则。如果目录是远程的，它必须包含一个(目录导入清单)qmldir文件，如果qmldir文件不存在QML引擎不能确定远程目录的内容。

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.

<Qualifier>应用到目录导入和模块导入有相同的语义；更多信息请查看前一章节<Importing into a Qualified Local Namespace>。

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

关于目录导入的更多信息，请查看更深入的文档<directory imports>。

JavaScript Resource Imports

JavaScript资源的导入

JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed.

JavaScript资源可以被直接导入到QML文档。每一个JavaScript资源必须有一个针对它的访问者的标识。

The generic form of a JavaScript resource import is as follows:

JavaScript资源的导入格式通常如下：

import "<JavaScriptFile>" as <Identifier>

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

注意<Identifier>必须是QML文档内独一无二的，不同于可应用到模块入口的本地命名空间限定符。

JavaScript Resources from Modules

来自模块的JavaScript资源

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

模块可以提供Javascript文件，通过添加标识说明到qmldir文件，qmldir文件是用来指定模块的。

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

例如，如果projects.MyQMLProject.MyFunctions模块被如下的qmldir文件指定，并且安装在QML的入口路径：

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:

客户端应用程序可以通过导入模块来导入模块内的已声明的JavaScript资源，并且使用标识关联到对应的已声明的资源。

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0

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:

如果模块被导入到文档局部的命名空间，JavaScript资源标识必须以命名空间限定符作前缀，才能被使用：

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
import org.example.Functions 1.0 as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

Further Information

补充信息

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 importing JavaScript resources in QML.

关于JavaScript资源的更多信息，请查看QML中文档<defining JavaScript resources in QML>在QML中定义JavaScript资源，更多的关于导入JavaScript资源的信息，如何在JavaScript资源内部导入，请查看更深入的文档<importing JavaScript resources in QML>在QML中导入JavaScript资源。

QML Import Path

QML 导入路径

When an identified module is imported, the QML engine searches the import path for a matching module.

当识别的模块被导入，QML 引擎查找匹配的模块的导入路径。

This import path, as returned by QQmlEngine::importPathList(), defines the default locations to be searched by the engine. By default, this list contains:

这个导入路径，作为 QQmlEngine::importPathList() 的返回值，定义引擎搜索的默认为止。默认情况下，列表包含：

1 The directory of the current file

2 The location specified by QLibraryInfo::Qml2ImportsPath

3 Paths specified by the QML2_IMPORT_PATH environment variable

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

附加导入路径可以通过 QQmlEngine::addImportPath() 或者环境变量 QML2_IMPORT_PATH 添加。当运行 qmlscene 工具，可以使用 -I 选项添加导入路径。

Debugging

The QML_IMPORT_TRACE environment variable can be useful for debugging when there are problems with finding and loading modules. See Debugging module imports for more information.

当查找和载入模块有问题时，环境变量 QML_IMPORT_TRACE 对调试有用。更详细的信息请查看调试模块的导入。