QC++ / Qt 学习之路

QML 语言基础

理解声明式 UI 思维,掌握 QML 文档结构与属性绑定

进阶第 35 / 48 章第五篇 · QML 与实战项目

#为什么要有 QML

在第四篇里你用 Qt Widgets 写过界面:创建一个 QPushButton,设置文字,把它塞进布局,再 connect 一个槽函数。这是命令式的写法——你一步一步告诉程序"先做什么、再做什么"。界面一旦复杂起来,尤其是带动画、自适应布局、多状态切换的界面,命令式代码会迅速膨胀成一大堆"设置属性"的语句,而且这些语句分散在各个函数的各个时机里,状态到底由谁决定变得难以追踪。

QML 走的是另一条路:声明式。你只描述"界面长什么样、属性和什么数据绑定在一起",而不描述"如何把它变成这样"。属性的更新由引擎自动完成。

举个直观对比。要让一个矩形的宽度始终是窗口的一半,Widgets 要这么写:

C++
// Widgets:命令式,需要在每个改变窗口大小的时机手动更新
void MainWindow::resizeEvent(QResizeEvent *e)
{
    QWidget::resizeEvent(e);
    m_rect->setGeometry(0, 0, width() / 2, m_rect->height());
}

QML 只需要一句:

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 区和一个根对象。每个文件有且仅有一个根对象,对象可以嵌套子对象,形成一棵树。

QML
// 文件: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,后者变化时前者重新求值。

QML
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 语句里给一个已被绑定的属性赋值,绑定就被打断了,此后它变成静态值。

QML
Item {
    width: parent.width / 2        // 建立绑定

    function breakIt() {
        width = 100                // 绑定被破坏!之后 parent.width 改变也不再生效
    }

    function keepIt() {
        // 需要"临时覆盖"时,应改用 States 或显式保存,而不是直接赋值
    }
}

QML 里区分两种语法:属性: 表达式 是绑定,属性 = 表达式(在 JS 块中)是赋值。看到 = 就要警惕。

#信号与处理器

任何属性都有自动生成的 onXxxChanged 处理器;控件的交互信号则有 onClicked、onTextChanged 等约定名。自定义信号用 signal 声明,发出时直接"调用"它。

QML
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:把元素的边或中心线"锚"到另一个元素的边或中心线上。

QML
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 文件,它还会监视文件变化并自动重载,改完保存即可看到效果:

Shell
# 直接预览一个 QML 文件,修改保存后自动刷新
qml MyPage.qml

# 若 QML 依赖 C++ 注册的类型,则用 qmlpreview 配合你的可执行程序
qmlpreview MyApp

Qt Creator 内置了同样的能力:打开 .qml 文件按 Ctrl+R(macOS 为 Cmd+R)即可弹出预览窗口;在 QML 代码里按 F10 可单步执行 JS 表达式,绑定求值过程也能在调试器中观察。排查绑定问题时,把环境变量 QT_LOGGING_RULES 设为 qt.qml.bindings.debug=true 可以看到引擎建立与打断绑定的详细日志,定位"为什么这个值不更新"特别有效。

#小结

  1. QML 是声明式语言:描述"是什么"而非"怎么做",核心机制是属性绑定——一条表达式加自动依赖追踪。
  2. 一个 .qml 文件 = import 区 + 唯一根对象;文件名即组件类型名,首字母必须大写。
  3. property 定义属性,property alias 暴露内部属性,signal 定义信号,处理器统一写作 onXxx。
  4. 绑定的死敌是 JS 中的 = 赋值——它会打断绑定;需要临时改态请用 State 或额外属性。
  5. 布局首选 anchors,只能锚定父对象或兄弟对象,避免与 width/height 产生冲突约束。

#练习

  1. 写一个 TempCard.qml 组件:显示温度数值,用 property alias 暴露标题,数值大于 30 时文字变红,点击后发出 signal cardClicked(real value)。
  2. 做一个自适应布局:窗口宽度小于 500 时,两个卡片上下排列;大于等于 500 时左右排列。提示:用绑定表达式 + parent.width 判断,切换 x/y 与 width 的绑定。
  3. 故意制造一次"绑定失效":给 width 绑定 parent.width / 2,再用 Timer 在 3 秒后用 width = 100 赋值,观察窗口缩放时的表现差异,并说明原因。
  4. 实现一个简单的计数器:MouseArea 每点击一次计数加一,用 onCountChanged 打印日志,并在计数达到 10 时自动禁用点击。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。