当前位置：首页 > news >正文

【QT Quick】基础语法：导入外部QML文件

news 2026/5/12 13:13:32

在实际项目中，代码通常分为多个文件进行模块化管理，这样可以方便代码重用，例如统一风格或共享功能模块。我们将在此部分学习如何创建 QML 项目，并演示如何访问外部代码，包括其他 QML 文件、库文件以及 JS 代码。

准备开发环境

在开发环境方面，我们尽量只使用纯 QML，不结合 C++，这样就可以避免频繁编译。建议使用以下两种工具之一进行开发：

VS Code + 命令行：可以通过命令行来执行 QML 文件。
Qt Creator：在课程中，我们选择使用 Qt Creator 来创建项目。Qt Creator 提供了 Qt Quick UI 原型系统，用于快速验证 QML 语法。以下是使用 Qt Creator 创建项目的步骤：
- 打开 Qt Creator，选择创建一个 “Qt Quick 项目”（即 UI 原型系统），该类型的项目不需要 C++ 代码。
- 确定项目配置，如 SDK 和工具链设置。
- 项目创建后，生成了一个默认的 QML 项目结构，包括入口文件 main.qml。

访问同一目录下的文件

在 QML 项目中，如果我们希望引用同一目录下的其他 QML 文件，可以通过以下方式实现：

文件名必须以大写字母开头。
直接使用文件名作为类型名，不需要导入（import）任何内容。

创建新的 QML 文件

在项目目录下创建一个新文件，命名为 MyType.qml（文件名首字母必须大写）。
在 MyType.qml 中定义内容，例如：
```
// MyType.qml
import QtQuick 2.0Text {text: "MyType Text"
}
```
这里我们创建了一个简单的 Text 元素，以便验证文件是否被成功调用。

在主 QML 文件中使用自定义类型

在主 QML 文件（如 main.qml）中使用自定义类型 MyType：

import QtQuick 2.0Rectangle {width: 400height: 400MyType {anchors.centerIn: parentx: 100y: 50}
}

这里我们直接使用 MyType，将其作为一个组件插入到主界面中。
可以对自定义类型的属性进行调整，例如位置 x 和 y，或者使用 anchors 进行布局。

验证结果

运行项目时，您应该会看到自定义类型 MyType 的 Text 显示在界面上。这样就成功演示了如何在同一目录下访问其他 QML 文件。

访问外部文件

在 QML 中，可以使用 import 关键字访问外部库。这种方式非常类似于 C++20 及其他现代编程语言中导入外部模块的方式。我们将在这一章节中了解如何导入 QML 系统库以及自定义库，并讨论可能遇到的命名冲突问题。

`import` 语法

在 QML 中导入外部库时，通常需要指定库的名称、版本号以及可选的命名空间标识符 as。其一般格式如下：

import 库名称 版本号 as 命名空间

例如，以下代码导入了 QtQuick 库的 6.0 版本：

import QtQuick 6.0

库的名称与版本号

库名称：导入的库名称可以是系统自带的库，如 QtQuick、QtQuick.Controls 等，也可以是自定义的库。
版本号：版本号通常包括主版本号和次版本号（例如 6.0）。在 QML 中，通过指定版本号来确保使用特定的 API 版本。如果不指定版本号，默认会使用安装的最新版本。
版本兼容性：QML 支持兼容多个版本的库，因此可以同时提供新版本和旧版本的兼容支持。例如，可以导入 6.0 版本的库，但如果项目需要兼容较低版本，则可以同时提供多个版本的实现。

解决命名冲突

当导入多个库时，有可能会遇到命名冲突的问题，比如多个库中都存在同名组件。为了解决这种问题，可以使用 as 关键字为导入的库指定一个别名，这样就可以通过别名来访问库中的组件。

例如，以下代码导入了 QtQuick.Controls 并为其指定了别名 CON：

import QtQuick.Controls 6.0 as CONRectangle {width: 400height: 400// 使用带有命名空间的 Button 组件CON.Button {text: "This is a button from QtQuick.Controls"anchors.centerIn: parent}
}

通过这种方式，即使导入了多个库中存在同名的 Button，也可以通过别名来区分不同的库。

导入目录中的代码

在实际项目开发中，我们可能会将多个相关的 QML 文件放入一个目录中，这些文件可以被当作一个整体导入到主项目中。这样可以减少逐个导入的麻烦，并提高代码组织的清晰度。

步骤 1：在项目目录下创建一个新目录，例如 MyDir。
步骤 2：在 MyDir 目录中创建多个 QML 文件，例如 Type1.qml 和 Type2.qml。

Type1.qml:
```
import QtQuick 2.0Text {text: "This is Type 1"
}
```
Type2.qml:
```
import QtQuick 2.0Text {text: "This is Type 2"
}
```

步骤 3：在主文件中导入整个目录。

import "MyDir"Rectangle {width: 400height: 400// 使用目录中定义的类型Type1 {anchors.top: parent.topanchors.horizontalCenter: parent.horizontalCenter}Type2 {anchors.bottom: parent.bottomanchors.horizontalCenter: parent.horizontalCenter}
}

通过导入整个目录，可以使用该目录中的所有 QML 类型，而不需要逐个导入每个文件。