Qt QML 模块及其函数详解
与 Qt Core 或 Qt Widgets 不同，QML 是一种声明式语言，主要关注 UI 的外观和行为，而不是传统的 C++ 代码流。因此，在 Qt QML 模块中，我们讨论的“函数”分为两个主要部分：
- C++ 端的核心类和函数： 这些函数负责加载、执行 QML 代码并实现 C++ 和 QML 之间的通信。
- QML 语言内部的函数和方法： 这些是 QML 元素本身提供的方法（Methods）和 JavaScript 函数。
🌟 I. C++ 端：Qt Qml 模块的核心类和函数
这些类属于 <QtQml> 模块，是 QML 引擎在 C++ 端的工作基础。
| 核心类 (Class) | 功能描述 | 常用函数 (Function) 及作用 |
|---|---|---|
QQmlEngine | QML 执行环境的核心。 管理组件缓存、网络访问、以及 QML 脚本的执行。 | QQmlEngine::load(const QUrl &url): 加载 QML 文件并创建根组件。返回 QObject 指针。QQmlEngine::rootContext(): 返回 QQmlContext 对象，用于在 C++ 中设置全局变量供 QML 访问。QQmlEngine::trimComponentCache(): 清理已加载的组件缓存，释放内存。 |
QQmlComponent | QML 组件的封装。 用于将 QML 文件编译成可实例化的对象。 | QQmlComponent::create(): 实例化已加载的 QML 组件，返回 QObject 指针。QQmlComponent::loadUrl(): 异步加载 QML 源文件。 |
QQmlContext | QML 上下文环境。 用于将 C++ 数据模型、对象和值暴露给 QML。 | QQmlContext::setContextProperty(const QString &name, QObject *value): 将 C++ 对象（或 QVariant）暴露给 QML，QML 中可通过 name 访问。QQmlContext::parentContext(): 获取父级上下文。 |
QQmlApplicationEngine | Qt Quick 应用程序的入口。 继承自 QQmlEngine，并简化了主 QML 文件的加载。 | QQmlApplicationEngine::load(const QUrl &url): 简化加载 QML 文件为应用程序的根组件，自动设置上下文。 |
QQuickView | 在 C++ 窗口中显示 QML 场景。 (属于 Qt Quick 模块，但与 QML 引擎紧密相关)。 | QQuickView::setSource(const QUrl &url): 设置要显示的 QML 文件路径。QQuickView::show(): 显示包含 QML 场景的窗口。 |
🚀 II. QML 语言内部的函数和方法 (QML Methods)
在 QML 内部，“函数”通常是特定 QML 元素提供的 方法 (Methods)，或是 QML 中直接编写的 JavaScript 函数。
A. 基础元素方法 (Qt Quick Module)
这些方法是 QML 的基石，用于控制 UI 元素的行为。
| QML 元素 | 核心方法 (Method) | 作用描述 |
|---|---|---|
Item | Item::x, Item::y: 属性，设置位置。Item::width, Item::height: 属性，设置大小。Item::parent: 属性，访问父元素。 | |
State | State::changes: 属性，定义在进入此状态时属性如何变化。State::onEntry / onExit: JavaScript 块，在进入/退出状态时执行代码。 | |
Component | Component::createObject(parent, properties): 动态创建组件实例的方法。 | |
MouseArea | 信号 clicked(): 鼠标点击时发射。MouseArea::contains(point): 检查给定点是否在区域内。 | |
Timer | Timer::start() / stop(): 启动和停止定时器。信号 triggered(): 定时器到期时发射。 |
B. 高级功能模块方法 (Qt Quick Controls, etc.)
| QML 元素 | 核心方法 (Method) | 作用描述 |
|---|---|---|
Loader | Loader::setSource(url): 运行时动态加载另一个 QML 文件。Loader::item: 属性，访问加载的组件实例（QObject*）。 | |
ListView / GridView | ListView::positionViewAt(index, mode): 滚动视图，将指定索引的项定位到特定位置。ListView::positionViewToBeginning(): 滚动到列表开头。 | |
StackView | StackView::push(url): 将新页面推入栈顶，通常伴随动画。StackView::pop(): 弹出栈顶页面，返回到上一个页面。 | |
Connections | on<SignalName>: 专用槽，用于连接到非父子关系对象的信号。 |
C. JavaScript 内建函数和 QML 全局函数
在 QML 的属性绑定或信号处理块中，可以直接使用标准 JavaScript 函数或 QML 提供的全局函数。
| 函数名 | 描述 | 作用 |
|---|---|---|
qsTr(string) | 翻译函数。 用于标记字符串进行翻译（使用 Qt Linguist）。 | text: qsTr("Hello") |
console.log() | 调试输出。 在 C++ 端输出调试信息（等同于 qDebug()）。 | onClicked: console.log("Button clicked") |
Date() | JavaScript 内建。 用于创建和操作日期/时间对象。 | var d = new Date() |
Math.random() / Math.round() | JavaScript 内建。 用于数学计算。 | N/A |
💡 总结：QML 编程的核心模式
QML 模块中的“函数”重点在于实现 C++ 和 QML 之间的桥梁以及 QML 内部的交互逻辑：
- C++ 调用 QML： C++ 使用
QQmlEngine加载 QML 文件，然后通过QObject::findChild()获取 QML 对象，并调用其方法。 - QML 调用 C++： C++ 通过
QQmlContext::setContextProperty()将 C++ 对象暴露给 QML，QML 直接调用该 C++ 对象的公共槽函数或方法。 - QML 内部交互： QML 元素之间通过属性绑定、状态机和信号/槽机制进行通信，核心逻辑常在
onClicked等信号处理块中以 JavaScript 函数的形式实现。