QML语法导入语句文档详细

导入语句的语法

导入语句允许客户端告诉引擎QML文档中使用了哪些模块，JavaScript资源和组件目录。文档中可以使用的类型取决于文档导入的模块，资源和目录。

导入类型

有三种不同的进口类型。每种导入类型的语法略有不同，并且不同的语义适用于不同的导入类型。

模块（名称空间）导入

最常见的导入类型是模块导入。客户端可以导入QML模块，这些模块将QML对象类型和JavaScript资源注册到给定的名称空间中。

模块导入的通用形式如下：

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

• <ModuleIdentifier>是在虚线URI表示法，其唯一地标识由所述模块所提供的类型名称空间指定的标识符。
• <Version.Number>是形式的版本，MajorVersion.MinorVersion指定哪个各种对象类型和JavaScript资源的定义，将提供因进口。
• <Qualifier>是在其中由所述模块所提供的对象类型和JavaScript资源将被安装，如果给定的一个可选的本地名称空间标识符。如果省略，则模块提供的对象类型和JavaScript资源将安装到全局名称空间中。

不合格模块导入的示例如下：

import QtQuick 2.0

此导入允许使用QtQuick模块提供的所有类型，而无需指定限定符。例如，创建矩形的客户端代码如下：

import QtQuick 2.0

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

合格模块导入的示例如下：

import QtQuick 2.0 as Quick

此导入允许同时导入提供有冲突类型名称的多个模块，但是由于每次使用由导入到合格名称空间中的模块提供的类型时，都必须在限定符之前添加，因此可以解决冲突由QML引擎明确定义。

使用合格模块导入后创建矩形的客户端代码示例如下：

import QtQuick 2.0 as Quick

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

有关合格导入的更多信息，请参见后面的“ 导入到合格本地命名空间”一节。

请注意，如果QML文档未导入提供特定QML对象类型的模块，而是尝试使用该对象类型，则将发生错误。例如，以下QML文档不会导入QtQuick，因此尝试使用该Rectangle类型将失败：

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

在这种情况下，引擎将发出错误并拒绝加载文件。

C ++模块导入

通常，C ++类型用声明QML_ELEMENT和QML_NAMED_ELEMENT（）宏和经由使用构建系统注册QML_IMPORT_NAME和QML_IMPORT_MAJOR_VERSION。通过这种方式指定的导入名称和版本构成了一个模块，可以将其导入以访问类型。

这在使用C ++定义自己的QML对象类型的客户端应用程序中最为常见。

导入到合格的本地命名空间

该import语句可以选择使用as关键字来指定应将类型导入到特定的文档本地名称空间中。如果指定了名称空间，那么任何对导入可用类型的引用都必须以本地名称空间限定符作为前缀。

在下面，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!" }
}

命名空间充当文件范围内模块的标识符。命名空间不会成为根对象的属性，可以使用属性，信号和方法从外部引用它。

如果需要使用两个具有相同名称但位于不同模块中的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 Qt Quick!" }
}

请注意，可以将多个模块导入同一名称空间的方式与将多个模块导入全局名称空间的方式相同。例如：

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

目录导入

包含QML文档的目录也可以直接导入QML文档中。这为将QML类型划分为可重用的分组提供了一种简单的方法：文件系统上的目录。

目录导入的一般形式如下：

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

注意：导入路径是网络透明的：应用程序可以从远程路径导入文档，就像从本地路径导入文档一样简单。请参阅QML文档中有关网络透明性的通用URL解析规则。如果目录是远程目录，则它必须包含目录导入列表qmldir文件，因为如果该qmldir文件不存在，则QML引擎无法确定该目录的内容。

<Qualifier>适用于目录导入的语义与模块导入相似。有关该主题的更多信息，请参见上一节“ 导入到合格的本地命名空间”。

有关目录导入的更多信息，请参阅有关目录导入的深入文档。

JavaScript资源导入

JavaScript资源可以直接导入QML文档中。每个JavaScript资源都必须具有用于访问它的标识符。

JavaScript资源导入的通用形式如下：

import "<JavaScriptFile>" as <Identifier>

请注意，<Identifier>在QML文档中，必须是唯一的，这与可以应用于模块导入的本地名称空间限定符不同。

模块中的JavaScript资源
通过将标识符定义添加到qmldir指定模块的文件中，模块可以提供Javascript文件。

例如，如果projects.MyQMLProject.MyFunctions模块使用以下qmldir文件指定，并安装到QML导入路径中：

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

客户端应用程序能够通过导入模块并使用与已声明资源关联的标识符来导入模块中声明的JavaScript资源：

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0

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

如果将模块导入到文档本地名称空间，则必须使用名称空间限定符作为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();
    }
}

更多信息

有关JavaScript资源的更多信息，请参见有关在QML中定义JavaScript资源的文档，以及有关如何导入JavaScript资源以及如何从JavaScript资源中使用导入的更多信息，请参见有关导入JavaScript的深入文档。QML中的资源。

QML导入路径

当识别模块是进口的，QML引擎搜索的进口路径的匹配模块。

由QQmlEngine :: importPathList（）返回的此导入路径定义了引擎要搜索的默认位置。默认情况下，此列表包含：

• 当前文件的目录
  • QLibraryInfo :: Qml2ImportsPath指定的位置
  • QML2_IMPORT_PATH环境变量指定的路径
  • qrc：/qt-project.org/imports资源内的路径。

可以通过QQmlEngine :: addImportPath（）或QML2_IMPORT_PATH环境变量添加其他导入路径。运行qmlscene工具时，还可以使用该-I选项添加导入路径。

您可以QML2_IMPORT_PATH通过使用路径分隔符将其导入来在环境变量中指定多个导入路径。在Windows上，路径分隔符是分号（;），在其他平台上则是冒号（:)。这意味着您无法在QML2_IMPORT_PATH中指定资源路径或URL，因为它们本身包含冒号。但是，您可以通过以编程方式调用QQmlEngine :: addImportPath（）来添加资源路径和URL 。

调试

QML_IMPORT_TRACE当查找和加载模块存在问题时，环境变量对于调试非常有用。有关更多信息，请参见调试模块导入。