导入语句#

QML 中导入语句的说明

导入语句的语法#

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

有三种不同类型的导入。每种导入类型都有稍微不同的语法，并且不同的语义应用于不同的导入类型。

模块（命名空间）导入#

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

模块导入的通用形式如下

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

  • <ModuleIdentifier> 是采用点分 URI 表示法指定的标识符，它唯一地标识了模块提供的类型命名空间。

  • <Version.Number> 是类似 主版本号.次版本号 的版本，它指定了由于导入而提供的各种对象类型和 JavaScript 资源的哪些定义将被启用。它可以省略，在这种情况下将导入模块的最新版本。也可以只省略次版本号。然后导入指定主版本的最新次版本。

  • <Qualifier> 是一个可选的本地命名空间标识符，如果指定，模块提供的对象类型和 JavaScript 资源将安装在此本地命名空间中。如果未指定，则模块提供的对象类型和 JavaScript 资源将安装到全局命名空间中。

以下是一个未指定限定符的模块导入的示例

import QtQuick

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

具有版本号的未指定导入示例可能如下

import QtQuick 2.10

在这种情况下，QtQuick 2.11 及更高版本或任何更高主要版本的任何类型将不会对文件可用。

以下是合格模块导入的示例

import QtQuick as Quick

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

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

有关合格导入的更多信息，请参阅即将出现的关于 导入合格本地命名空间 的部分。

注意，如果一个QML文档没有导入提供特定QML对象类型的模块，但仍然尝试使用该对象类型，将会出现错误。例如，以下QML文档没有导入QtQuick，因此尝试使用Rectangle类型将会失败

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

C++模块导入#

通常，使用宏QML_ELEMENT和QML_NAMED_ELEMENT()声明C++类型，并通过构建系统使用`QML_IMPORT_NAME`和`QML_IMPORT_MAJOR_VERSION`注册。这种方式给出的导入名称和版本形成一个模块，可以导入以访问这些类型。

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

导入到限定局部命名空间#

导入语句可以使用可选的`as`关键字来指定，应将类型导入到特定的文档局部命名空间中。如果指定了命名空间，则必须使用局部命名空间限定符作为导入提供的类型引用的前缀。

下面，将`QtQuick`模块导入到命名空间"CoreItems"。现在，对`QtQuick`模块中类型的任何引用都必须以`CoreItems`名称为前缀

命名空间在文件的范围内作为模块的标识符存在。命名空间不会成为根对象的可外部引用的属性，就像属性、信号和方法一样。

在需要使用位于不同模块中的名称相同但位置不同的两个QML类型时，命名空间导入非常有用。在这种情况下，可以通过将两个模块导入不同的命名空间来确保代码引用的是正确的类型。

请注意，可以像导入全局命名空间中的多个模块一样将多个模块导入到同一命名空间中。例如

import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

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

目录导入#

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

目录导入的通用形式如下

注意

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

对于``适用类似的语义，与模块导入一样；有关更多信息，请参阅前面关于导入到限定局部命名空间的章节。

关于目录导入的更多信息，请参阅关于目录导入的详细文档。

JavaScript 资源导入#

JavaScript 资源可以直接导入到 QML 文档中。每个 JavaScript 资源都必须有一个标识符，以便访问。

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

import "<JavaScriptFile>" as <Identifier>

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

模块中的 JavaScript 资源#

模块可以提供 JavaScript 文件，通过向指定模块的 qmldir 文件中添加标识符定义来实现。

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

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

客户端应用可以通过导入模块并使用与声明资源相关联的标识符来导入模块中声明的 JavaScript 资源

如果模块被导入到文档本地命名空间中，JavaScript 资源标识符必须以命名空间限定符为前缀才能使用

更多信息#

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

QML 导入路径#

导入标识模块时，QML 引擎会在导入路径中搜索匹配的模块。

此导入路径，如 importPathList() 返回，定义了引擎默认搜索的位置。默认情况下，此列表包含

  • 当前文件的目录

  • 由 QLibraryInfo::QmlImportsPath 指定的位置

  • 由环境变量 QML_IMPORT_PATH 指定的路径

  • 资源内的 qrc:/qt-project.org/imports 路径。

  • 资源内的 qrc:/qt/qml 路径（从 Qt 6.5 开始）。

可以通过 addImportPath() 或环境变量 QML_IMPORT_PATH 添加额外的导入路径。当运行 qml 工具时，您也可以使用 -I 选项添加导入路径。

您可以通过使用路径分隔符连接它们来在环境变量 QML_IMPORT_PATH 中指定多个导入路径。在 Windows 上，路径分隔符是分号 (;)，在其他平台上是冒号 (: )。这意味着在 QML_IMPORT_PATH 中不能指定资源路径或 URL，因为它们本身就包含冒号。然而，您可以通过调用 addImportPath() 编程式地添加资源路径和 URL。

注意

建议应用程序和库将它们的主程序放在“qrc:/qt/qml”下。当使用 qt_add_qml_module() 和启用 QTP0001 创建模块时，这将是默认行为。

调试#

在模块查找和加载出现问题的情况下，环境变量 QML_IMPORT_TRACE 对于调试非常有用。有关更多信息，请参阅模块导入调试。