导入语句

导入语句的语法

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

导入分为三种不同类型。每种导入类型的语法略有不同，且不同导入类型适用不同的语义。

模块（命名空间）导入

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

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

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

• <ModuleIdentifier> 是一个采用点分 URI 表示法的标识符，用于唯一标识该模块提供的类型命名空间。
• <Version.Number> 采用MajorVersion.MinorVersion 的形式，用于指定通过该导入将提供哪些对象类型和 JavaScript 资源的定义。该参数可以省略，此时将导入模块的最新版本。也可以仅省略次版本号，此时将导入给定主版本下的最新次版本。
• <Qualifier> 是一个可选的本地命名空间标识符，如果指定，该模块提供的对象类型和 JavaScript 资源将被安装到该命名空间中。如果省略，该模块提供的对象类型和 JavaScript 资源将被安装到全局命名空间中。

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

import QtQuick

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

import QtQuick

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

带版本号的未限定导入示例如下：

import QtQuick 2.10

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

带限定符的模块导入示例如下：

import QtQuick as Quick

这种导入方式允许同时导入多个提供冲突类型名的模块；但由于在受限命名空间中导入的模块所提供的类型每次使用前都必须加上限定符，因此 QML 引擎能够明确地解决此类冲突。

以下是一个客户端代码示例，该代码在使用限定模块导入后创建了一个矩形：

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

Project.Rectangle {
    width: 100; height: 50

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

目录导入

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

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

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

<Qualifier> 文件在目录导入中的语义与模块导入类似；有关此主题的更多信息，请参阅前一节“导入到限定本地命名空间”。

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

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 资源：

import QtQuick
import projects.MyQMLProject.MyFunctions

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

如果该模块被导入到文档本地命名空间中，则必须在 JavaScript 资源标识符前添加命名空间限定符才能使用：

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

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

更多信息

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

QML 导入路径

导入已标识的模块时，Qml 引擎会沿导入路径搜索匹配的模块，以加载 QML 文件和 QML 模块插件。Qt 假定导入路径下的所有文件均来自可信来源。

该导入路径由QQmlEngine::importPathList()方法返回，它定义了引擎默认搜索的位置。默认情况下，该列表按以下优先级顺序包含：

• （如适用）平台特定的捆绑包路径（例如在 macOS 或 Android 上）
• 应用程序二进制文件的目录
• 资源目录内的 qrc:/qt-project.org/imports 路径
• 资源文件中的 qrc:/qt/Qml 路径（自 Qt 6.5 起）。
• 由QML2_IMPORT_PATH 环境变量指定的路径（已弃用）
• 由QML_IMPORT_PATH 环境变量指定的路径
• 由以下内容指定的位置QLibraryInfo::QmlImportsPath

如果QCoreApplication 上设置了Qt::AA_PluginApplication 属性，则默认情况下，应用程序目录、环境变量指定的任何路径以及资源文件系统之外的任何平台特定的捆绑路径都会被省略。

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

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

调试

当在查找和加载模块时出现问题，QML_IMPORT_TRACE 环境变量可用于调试。有关更多信息，请参阅“调试模块导入”。