导入语句¶

导入语句的语法¶

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

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

模块（命名空间）导入¶

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

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

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

• 是一个以点分隔的URI符号指定的标识符，它唯一标识了模块提供的类型命名空间。

• 是一个形式为 MajorVersion.MinorVersion 的版本号，它指定了由于导入而将提供的各种对象类型和 JavaScript 资源的定义。它可以省略，在这种情况下将导入模块的最新版本。也可以只省略次要版本。然后将导入给定主要版本的最新次要版本。

• 是一个可选的本地命名空间标识符，如果提供，模块提供的对象类型和 JavaScript 资源将安装到该命名空间中。如果省略，模块提供的对象类型和 JavaScript 资源将安装到全局命名空间中。

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

import QtQuick

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

一个带有版本号的不合格导入的示例是

import QtQuick 2.10

在这种情况下，QtQuick 2.11 及更高版本或任何更高主版本（如 6.0）中定义的任何类型将无法在该文件中使用。

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

import QtQuick as Quick

此导入允许同时导入提供冲突类型名称的多个模块，然而，由于导入到限定命名空间的模块提供的每个类型的使用都必须以限定符为前缀，因此QML引擎能够明确地解决冲突。

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

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

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

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

C++ 模块导入¶

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

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

导入到限定的本地命名空间¶

import 语句可以选择性地使用 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类型分割成可重用的分组提供了一种简单的方法：文件系统上的目录。

目录导入的通用形式如下：

对于目录导入，的语义与模块导入类似；有关该主题的更多信息，请参阅前面关于导入到限定本地命名空间的部分。

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

JavaScript 资源导入¶

JavaScript 资源可以直接在 QML 文档中导入。每个 JavaScript 资源都必须有一个标识符，通过该标识符进行访问。

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

import "<JavaScriptFile>" as <Identifier>

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

来自模块的JavaScript资源¶

Javascript 文件可以通过模块提供，通过向指定模块的 qmldir 文件添加标识符定义。

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

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

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

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

更多信息¶

有关JavaScript资源的更多信息，请参阅关于在QML中定义JavaScript资源的文档，有关如何导入JavaScript资源以及如何在JavaScript资源中使用导入的更多信息，请参阅关于在QML中导入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。

调试¶

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