导入语句

导入语句的语法

导入语句允许客户告诉引擎在 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

在这种情况下，任何在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 通过构建系统注册。以这种方式给出的导入名称和版本构成一个模块，可通过导入该模块来访问类型。

这在用 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 引擎会搜索导入路径以查找匹配的模块。

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。

调试

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