导入语句

导入语句的语法

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

存在三种不同类型的导入。每种导入类型都有略微不同的语法，并且对不同导入类型应用不同的语义。

模块（命名空间）导入

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

模块导入的通用形式如下

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

<ModuleIdentifier> 是使用点分 URI 表示法指定的标识符，它唯一地标识了模块提供的类型命名空间。
<Version.Number> 是形式为 主版本号.次版本号 的版本，它指定了由于导入而将提供哪些不同对象类型和 JavaScript 资源的定义。它可以省略，在这种情况下，将导入模块的最新版本。还可以省略次要版本。然后导入主版本的最新次要版本。
<Qualifier> 是一个可选的本地命名空间标识符，如果提供了，则模块提供的对象类型和 JavaScript 资源将安装在这个本地命名空间中。如果省略，则模块提供的对象类型和 JavaScript 资源将安装到全局名称空间中。

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

import QtQuick

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

import QtQuick

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

以下是一个具有版本号的未指定限定符导入示例

import QtQuick 2.10

在这种情况下，任何定义在 QtQuick 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在构建系统中进行注册。这样提供的导入名和版本形成了一个模块，可以导入以访问这些类型。

这在定义自己的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>]

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

对于目录导入适用的语义与模块导入相同；有关此主题的更多信息，请参阅关于导入到限制性局部命名空间的前一节。

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

JavaScript资源导入

可以直接在QML文档中导入JavaScript资源。每个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();
    }
}

QML 导入路径

导入了已标识模块后，QML 引擎将在 导入路径 中搜索匹配的模块。

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

当前文件的目录
QLibraryInfo::QmlImportsPath 指定的地方
QML_IMPORT_PATH 环境变量指定的路径
资源中的 qrc:/qt-project.org/imports 路径
资源中的 qrc:/qt/qml 路径（从 Qt 6.5 开始）。

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

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

注意：建议应用程序和库将它们的模块放在 "qrc:/qt/qml" 下。当使用 qt_add_qml_module() 和 QTP0001 启用时，模块创建时会默认这样做。

调试

在查找和加载模块存在问题的情况下，QML_IMPORT_TRACE 环境变量在调试时可能很有用。有关更多信息，请参阅调试模块导入。