QML 语言基础
理解声明式 UI 思维,掌握 QML 文档结构与属性绑定
#为什么要有 QML
在第四篇里你用 Qt Widgets 写过界面:创建一个 QPushButton,设置文字,把它塞进布局,再 connect 一个槽函数。这是命令式的写法——你一步一步告诉程序"先做什么、再做什么"。界面一旦复杂起来,尤其是带动画、自适应布局、多状态切换的界面,命令式代码会迅速膨胀成一大堆"设置属性"的语句,而且这些语句分散在各个函数的各个时机里,状态到底由谁决定变得难以追踪。
QML 走的是另一条路:声明式。你只描述"界面长什么样、属性和什么数据绑定在一起",而不描述"如何把它变成这样"。属性的更新由引擎自动完成。
举个直观对比。要让一个矩形的宽度始终是窗口的一半,Widgets 要这么写:
// Widgets:命令式,需要在每个改变窗口大小的时机手动更新
void MainWindow::resizeEvent(QResizeEvent *e)
{
QWidget::resizeEvent(e);
m_rect->setGeometry(0, 0, width() / 2, m_rect->height());
}QML 只需要一句:
Rectangle {
width: parent.width / 2 // 引擎自动维持这个关系
height: 100
}width: parent.width / 2 不是一次赋值,而是一条绑定。当 parent.width 变化时,width 自动重算。这就是 QML 的灵魂——你写的不是"赋值语句",而是"约束关系"。前端开发者会觉得这很眼熟:QML 的属性绑定 ≈ Vue 的 computed / React 的状态派生;QML 的对象树 ≈ DOM 树;QML 的 signal ≈ DOM 事件。
QML 不是要取代 Widgets。工具型、表单密集的桌面程序(IDE、配置工具、工业上位机)用 Widgets 效率更高;而动画丰富、屏幕尺寸多变、追求视觉表现的界面(车载 HMI、医疗设备、仪表盘、移动端)用 QML 更合适。Qt 官方对二者定位是长期并存的。
#一个 QML 文档的结构
QML 文件(.qml)由两部分组成:import 区和一个根对象。每个文件有且仅有一个根对象,对象可以嵌套子对象,形成一棵树。
// 文件:MyCard.qml —— 文件名首字母必须大写,它就是一个可复用的"组件类型"
import QtQuick
import QtQuick.Controls
Rectangle {
id: root // id:在本文件作用域内引用自己
width: 240; height: 120
radius: 8
color: "#ffffff"
border.color: "#d0d0d0"
// 自定义属性,供外部使用者传入
property string title: "标题"
property int count: 0
property alias subtitle: subLabel.text // 属性别名:把子对象的属性暴露出去
// 自定义信号
signal clicked(string name)
Text {
id: subLabel
anchors.top: parent.top
anchors.left: parent.left
anchors.margins: 12
text: root.title
font.pixelSize: 16
font.bold: true
}
Text {
anchors.centerIn: parent
// JavaScript 表达式,count 变化时自动重算
text: "共 " + root.count + " 条"
color: root.count > 0 ? "#333333" : "#999999"
}
MouseArea {
anchors.fill: parent
onClicked: root.clicked(root.title) // 发出自定义信号
}
}要点:
import QtQuick不带版本号。Qt 6 引入的版本无关导入会自动选择该模块的最新版本,避免 Qt 5 时代import QtQuick 2.15到处硬编码的麻烦。- 文件名即类型名。
MyCard.qml在同目录下可直接使用<MyCard { title: "CPU" } />。这也是为什么文件名必须大写开头。 id只能用小写开头(严格说是首字符小写),且在同一文件内唯一。id不是字符串,是编译期解析的标识符,不能动态拼接。property alias是暴露内部子对象属性的标准手法,避免了在 C++ 里写一堆 getter/setter。
#属性绑定:QML 的灵魂
绑定是"表达式 + 依赖追踪"。引擎在执行 width: parent.width / 2 时会记录它依赖了 parent.width,后者变化时前者重新求值。
import QtQuick
import QtQuick.Controls
ApplicationWindow {
visible: true
width: 400; height: 300
title: "绑定演示"
Rectangle {
id: box
x: 20; y: 20
width: 120; height: 120
// 绑定链:color 依赖 hovering,hovering 依赖 MouseArea
color: area.containsMouse ? "#4CAF50" : "#9E9E9E"
// Behavior:属性变化时自动补间动画,而不是突变
Behavior on color { ColorAnimation { duration: 200 } }
Behavior on rotation { NumberAnimation { duration: 300 } }
rotation: area.containsMouse ? 15 : 0
Text {
anchors.centerIn: parent
text: "点我"
color: "white"
}
MouseArea { id: area; anchors.fill: parent; hoverEnabled: true }
}
Slider {
id: slider
anchors.bottom: parent.bottom
anchors.left: parent.left; anchors.right: parent.right
from: 0; to: 360
value: 0
}
Rectangle {
anchors.centerIn: parent
width: 80; height: 80
color: "#2196F3"
// 三重依赖:width、rotation 都由 slider.value 推导
rotation: slider.value
scale: 0.5 + slider.value / 360
}
}绑定的失效陷阱(初学者最常见的坑):一旦你在 JavaScript 语句里给一个已被绑定的属性赋值,绑定就被打断了,此后它变成静态值。
Item {
width: parent.width / 2 // 建立绑定
function breakIt() {
width = 100 // 绑定被破坏!之后 parent.width 改变也不再生效
}
function keepIt() {
// 需要"临时覆盖"时,应改用 States 或显式保存,而不是直接赋值
}
}QML 里区分两种语法:属性: 表达式 是绑定,属性 = 表达式(在 JS 块中)是赋值。看到 = 就要警惕。
#信号与处理器
任何属性都有自动生成的 onXxxChanged 处理器;控件的交互信号则有 onClicked、onTextChanged 等约定名。自定义信号用 signal 声明,发出时直接"调用"它。
import QtQuick
import QtQuick.Controls
Rectangle {
width: 300; height: 200
signal valueSubmitted(real v, string who) // 带参数的自定义信号
// 1. 属性变化处理器
onWidthChanged: console.log("宽度变为", width)
// 2. 信号处理器,参数可直接用
onValueSubmitted: (v, who) => console.log(who, "提交了", v)
// 3. 用 Connections 连接"非直接父子"的对象(跨文件/跨组件时常用)
Connections {
target: backend // backend 是 C++ 注入的对象
function onDataReady(x) { console.log("收到", x) }
}
// 4. 用信号连接信号,等价于 Qt 5 的 signal.connect()
Component.onCompleted: valueSubmitted(3.14, "init")
}Qt 5 写法
onClicked: { ... }在 Qt 6 仍可用,但推荐用箭头函数onClicked: (mouse) => { ... },参数可见且语义清晰。Component.onCompleted是附加属性(Attached Property),由Component类型"附加"到任意对象上,类似的还有Keys.onReturnPressed、Window.active等。
#布局:anchors 锚布局
QML 没有 Widgets 那种 QHBoxLayout。首选方案是 anchors:把元素的边或中心线"锚"到另一个元素的边或中心线上。
import QtQuick
import QtQuick.Controls
Pane {
width: 360; height: 240
Rectangle { // 顶栏:贴满顶部
id: header
anchors.top: parent.top
anchors.left: parent.left
anchors.right: parent.right
height: 48
color: "#3F51B5"
}
Rectangle { // 内容区:夹在顶栏与底栏之间
anchors.top: header.bottom
anchors.bottom: footer.top
anchors.left: parent.left
anchors.right: parent.right
anchors.margins: 8
color: "#FAFAFA"
}
Rectangle { // 底栏:贴满底部
id: footer
anchors.bottom: parent.bottom
anchors.left: parent.left
anchors.right: parent.right
height: 40
color: "#EEEEEE"
}
// 居中 + 偏移
Text {
anchors.centerIn: parent
anchors.verticalCenterOffset: -20
text: "Hello QML"
}
}常用锚线:left/right/top/bottom、horizontalCenter/verticalCenter、centerIn(居中)、fill(填满)、margins(统一边距)、baseline。
锚布局的禁区:只能锚定兄弟或父对象,不能锚到任意远亲;不要同时设置 anchors.left 和 width 之外的冲突组合(例如同时给 left、right、width 赋值,引擎会警告,结果未定义)。需要按行列排列多个元素时,用下一篇的 RowLayout/ColumnLayout 更省事。
如果确实需要"临时改一个值、之后恢复绑定",正确做法是把临时值也建模成属性,让绑定表达式自己去选择,而不是用赋值去覆盖。例如 width: override >= 0 ? override : parent.width / 2,要恢复时把 override 设为 -1 即可,绑定始终完好。
#基本元素速览
| 元素 | 作用 | 关键属性 |
|---|---|---|
Item | 所有可视元素的基类,本身不可见 | x/y/width/height、opacity、visible、clip |
Rectangle | 矩形 | color、radius、border、gradient |
Text | 文本 | text、font、color、elide、wrapMode |
Image | 图片 | source、fillMode、asynchronous、sourceSize |
MouseArea | 不可见,提供鼠标/触摸输入 | anchors.fill、onClicked、hoverEnabled、containsMouse |
Repeater | 按模型重复生成元素 | model、delegate |
Item 与 Rectangle 的关系类似 QWidget 与 QFrame:前者是容器与坐标系,后者加了绘制。所有元素默认 clip: false,超出边界的子元素不会被裁剪,做圆角头像或滚动区域时要显式开 clip: true(但 clip 有性能代价,不要滥用)。
关于 Image,有两条实战经验值得记住。第一是设 sourceSize:加载一张 4000×3000 的图然后缩到 200×200 显示,Qt 默认会把整张大图解码进内存(约 48MB),显存和 GC 压力都非常大;指定 sourceSize { width: 200; height: 200 } 后 Qt 会按目标尺寸解码,内存降到几十 KB。第二是设 asynchronous: true,让解码在后台线程进行,避免加载大图时主线程卡顿几百毫秒——列表里显示大量缩略图时这一项几乎是必须的。
#开发与调试工作流
写 QML 的体验比 C++ 好很多,因为不需要编译就能看到结果。Qt 6 提供了 qml 工具(Qt 5 里叫 qmlscene),可以直接运行一个 .qml 文件,它还会监视文件变化并自动重载,改完保存即可看到效果:
# 直接预览一个 QML 文件,修改保存后自动刷新
qml MyPage.qml
# 若 QML 依赖 C++ 注册的类型,则用 qmlpreview 配合你的可执行程序
qmlpreview MyAppQt Creator 内置了同样的能力:打开 .qml 文件按 Ctrl+R(macOS 为 Cmd+R)即可弹出预览窗口;在 QML 代码里按 F10 可单步执行 JS 表达式,绑定求值过程也能在调试器中观察。排查绑定问题时,把环境变量 QT_LOGGING_RULES 设为 qt.qml.bindings.debug=true 可以看到引擎建立与打断绑定的详细日志,定位"为什么这个值不更新"特别有效。
#小结
- QML 是声明式语言:描述"是什么"而非"怎么做",核心机制是属性绑定——一条表达式加自动依赖追踪。
- 一个
.qml文件 =import区 + 唯一根对象;文件名即组件类型名,首字母必须大写。 property定义属性,property alias暴露内部属性,signal定义信号,处理器统一写作onXxx。- 绑定的死敌是 JS 中的
=赋值——它会打断绑定;需要临时改态请用 State 或额外属性。 - 布局首选
anchors,只能锚定父对象或兄弟对象,避免与width/height产生冲突约束。
#练习
- 写一个
TempCard.qml组件:显示温度数值,用property alias暴露标题,数值大于 30 时文字变红,点击后发出signal cardClicked(real value)。 - 做一个自适应布局:窗口宽度小于 500 时,两个卡片上下排列;大于等于 500 时左右排列。提示:用绑定表达式 +
parent.width判断,切换x/y与width的绑定。 - 故意制造一次"绑定失效":给
width绑定parent.width / 2,再用Timer在 3 秒后用width = 100赋值,观察窗口缩放时的表现差异,并说明原因。 - 实现一个简单的计数器:
MouseArea每点击一次计数加一,用onCountChanged打印日志,并在计数达到 10 时自动禁用点击。