3. QML语法基础

QML 是一种声明式语言，其核心思想是让开发者通过描述“界面应该是什么样”来构建应用，而非通过命令式代码一步步“绘制”界面。本章将深入剖析 QML 的语法骨架，包括对象声明、属性绑定、信号与槽机制、基本数据类型以及注释与代码结构。理解这些基础是构建任何复杂 Qt Quick 应用的先决条件，它们共同构成了 QML 文件（.qml）的语法单元与运行时行为逻辑。

3.1 对象声明：从矩形到组件的构建

核心原理

在 QML 中，一切皆对象。一个 QML 文件本质上定义了一个对象树，树的根节点通常是 Item、Rectangle、Window 等可视化元素或非可视化的逻辑对象。对象声明采用“类型 { 属性: 值 }”的语法结构，这与 JSON 类似但功能更强。每个对象可以拥有子对象，子对象通过缩进和花括号进行层级嵌套，从而形成父子关系。父对象负责管理子对象的生命周期，子对象的位置、旋转等几何属性默认相对于父对象坐标系。

操作流程：声明一个自定义矩形

import QtQuick 2.15

Rectangle {
    id: rootRect
    width: 300
    height: 200
    color: "lightblue"

    Rectangle {
        id: innerRect
        width: 100
        height: 100
        anchors.centerIn: parent
        color: "coral"
        radius: 10
    }
}

上述代码中，外层 Rectangle 是根对象，内层 Rectangle 是其子对象。通过 id 我们可以唯一标识对象，并在其他表达式中引用它。注意，id 在一个 QML 文档中必须唯一，且不能使用 JavaScript 保留字。

案例拆解：构建一个简单的用户卡片

假设我们需要在界面中展示一个用户信息卡片，包含头像、姓名和状态。我们可以通过嵌套对象声明来实现：

Item {
    width: 200; height: 60

    Rectangle { // 头像占位
        id: avatar
        width: 40; height: 40
        radius: 20
        color: "gray"
        anchors.left: parent.left
        anchors.verticalCenter: parent.verticalCenter
    }

    Text { // 姓名
        id: nameText
        text: "张三"
        font.pixelSize: 16
        anchors.left: avatar.right
        anchors.leftMargin: 10
        anchors.top: parent.top
        anchors.topMargin: 5
    }

    Text { // 状态
        id: statusText
        text: "在线"
        font.pixelSize: 12
        color: "green"
        anchors.left: avatar.right
        anchors.leftMargin: 10
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 5
    }
}

这个案例展示了对象声明如何通过组合基础元素（Rectangle、Text）来构建复合 UI 组件。每个子对象都通过锚定（anchors）来定位，这是 QML 布局的核心方式之一。

常见误区与总结

• 误区：认为 id 是字符串，可以用引号包裹。实际上 id 是标识符，不能加引号。
• 误区：在对象声明中直接写 JavaScript 语句（如 if 或 for），这是不允许的。对象声明只包含属性赋值和子对象。
• 总结：对象声明是 QML 的骨架，合理规划对象层级和 id 命名（如使用驼峰式）能显著提升代码可维护性。

3.2 属性绑定：数据驱动的界面更新

核心原理

属性绑定是 QML 最强大的特性之一。它允许将一个对象的属性值绑定到另一个表达式上，当表达式中的依赖项（其他属性、JavaScript 变量等）发生变化时，绑定属性会自动更新。这与命令式编程中“先取值再赋值”的模式截然不同。绑定语法使用冒号（:）后跟一个表达式，该表达式可以是简单的常量、属性引用或复杂的 JavaScript 运算。

判断方法：何时使用绑定？

当属性的值需要根据其他状态动态变化时，应使用绑定。例如，一个进度条的宽度应绑定到当前进度值；一个按钮的可用性应绑定到输入框是否有内容。判断标准是：该属性是否依赖于其他数据源？如果是，则使用绑定；如果只是静态初始值，则直接赋值即可。

案例拆解：实现一个实时更新的仪表盘

我们创建一个简单的速度表，速度值由一个滑块控制，文本和颜色都随速度变化：

Column {
    spacing: 10

    Slider {
        id: speedSlider
        from: 0; to: 200
        value: 50
    }

    Text {
        id: speedValue
        text: speedSlider.value.toFixed(0) + " km/h"
        font.pixelSize: 24
        color: speedSlider.value > 120 ? "red" : "black"
    }

    Rectangle {
        width: speedSlider.value * 2
        height: 10
        color: "blue"
    }
}

在这个案例中，speedValue.text 绑定了 speedSlider.value，color 绑定了条件表达式，Rectangle.width 也绑定了滑块值。当用户拖动滑块时，所有绑定属性都会自动刷新，无需手动编写事件处理代码。这体现了声明式 UI 的“状态驱动视图”思想。

常见误区与总结

• 误区：在绑定表达式中使用 id 时，如果对象尚未创建，会导致绑定失败。确保引用的对象在绑定表达式求值前已存在。
• 误区：过度使用绑定导致性能问题。复杂的绑定表达式（如大量字符串拼接或循环）会在每次依赖变化时重新求值，应尽量简化表达式或使用 Binding 类型进行条件控制。
• 总结：属性绑定是 QML 的“血液”，它让界面与数据保持同步。理解绑定的生命周期和性能特征，是编写高效 QML 代码的关键。

3.3 信号与槽：事件驱动的交互机制

核心原理

信号（Signal）是 QML 对象对外广播“某事发生了”的机制，而槽（Slot）则是响应信号的函数。在 QML 中，信号通常由用户交互（如点击、拖动）或属性变化触发。连接信号与槽有两种主要方式：一种是在 QML 中使用 on<SignalName> 信号处理器，另一种是通过 Connections 类型或 connect() 方法进行动态连接。信号处理器是 QML 中最常用的方式，它允许在对象声明内部直接定义响应逻辑。

操作流程：为按钮添加点击响应

Button {
    id: myButton
    text: "点击我"
    onClicked: {
        console.log("按钮被点击了")
        myButton.text = "已点击"
    }
}

这里 onClicked 就是 clicked 信号的处理器。当按钮被点击时，QML 引擎会自动调用该处理器中的 JavaScript 代码。注意，在信号处理器中，我们可以直接访问该对象及其兄弟对象的 id。

案例拆解：自定义信号实现跨组件通信

假设我们有一个输入框和一个标签，当输入框内容变化时，标签显示输入长度。我们可以使用自定义信号：

Item {
    id: root
    signal textChanged(string newText)

    TextInput {
        id: input
        anchors.top: parent.top
        onTextChanged: root.textChanged(text)
    }

    Text {
        id: label
        anchors.top: input.bottom
        text: "长度: 0"
    }

    Connections {
        target: root
        function onTextChanged(newText) {
            label.text = "长度: " + newText.length
        }
    }
}

在这个案例中，root 定义了一个自定义信号 textChanged，TextInput 的内置信号处理器中发射该信号，而 Connections 对象则监听该信号并更新标签。这种模式解耦了信号发射者和接收者，使得组件之间的通信更加清晰。

常见误区与总结

• 误区：在信号处理器中忘记使用 function 关键字（在 Connections 中），导致语法错误。
• 误区：信号处理器中执行耗时操作（如网络请求），会阻塞 UI 渲染。应使用异步方式或 WorkerScript。
• 总结：信号与槽是 QML 交互的核心。合理使用信号处理器和 Connections，可以构建低耦合、高内聚的组件架构。

3.4 基本数据类型与注释

核心原理

QML 支持多种基本数据类型，包括 int、real、double、bool、string、color、font、url、var 等。其中 var 可以存储任意 JavaScript 值。类型在属性声明时是隐式推断的，但也可以显式指定。注释与 JavaScript 类似，支持单行 // 和多行 /* */。良好的注释习惯对于维护大型 QML 项目至关重要。

操作流程：正确使用类型与注释

Item {
    // 这是单行注释
    /* 这是
       多行注释 */
    property int count: 10
    property string name: "Qt"
    property color bgColor: "steelblue"
    property var dataObject: ({ "key": "value" })
}

在声明属性时，使用 property 关键字可以定义自定义属性，并指定类型。这有助于提高代码的可读性和类型安全性。注释应解释“为什么”而非“是什么”，避免冗余。

案例拆解：类型转换与注释规范

在实际开发中，经常需要将字符串转换为数字，或反之。QML 中可以使用 JavaScript 的全局函数，如 Number()、parseInt() 等。同时，注释应遵循团队规范，例如在函数上方说明功能、参数和返回值。

function calculateArea(radius) {
    // 计算圆的面积
    // 参数: radius - 半径 (number)
    // 返回: 面积 (number)
    return Math.PI * radius * radius;
}

常见误区与总结

• 误区：混淆 var 和具体类型。过度使用 var 会失去类型检查的优势，建议在明确类型时使用具体类型。
• 误区：注释过于简单或过于冗长。好的注释应描述意图和约束，而不是逐行翻译代码。
• 总结：数据类型是 QML 的“细胞”，注释是“说明书”。掌握类型转换和注释规范，能让代码更健壮、更易维护。

3.5 代码结构与组织

核心原理

一个规范的 QML 文件结构通常包含：导入语句（import）、对象声明、属性定义、信号定义、函数定义和内部组件。导入语句必须位于文件顶部，用于引入 Qt Quick 模块或其他自定义模块。代码结构直接影响加载性能和可读性。合理的结构应遵循“从上到下、从公共到私有”的原则。

操作流程：组织一个复杂的 QML 文件

import QtQuick 2.15
import QtQuick.Controls 2.15

Rectangle {
    id: root
    width: 400; height: 300

    // 公共属性
    property string title: "示例"

    // 信号
    signal buttonClicked()

    // 私有函数
    function doSomething() {
        console.log("执行操作")
    }

    // 子组件
    Button {
        text: root.title
        onClicked: {
            root.buttonClicked()
            root.doSomething()
        }
    }
}

在这个结构中，import 在最前，然后是根对象，接着是属性、信号、函数，最后是子对象。这种顺序有助于快速定位关键信息。

案例拆解：模块化与复用

当项目变大时，应将重复的 UI 片段提取为独立的 QML 文件（组件）。例如，创建一个 CustomButton.qml，然后在主文件中通过 CustomButton {} 使用。这要求文件命名与组件类型名一致，且放在同一目录或导入路径中。

// CustomButton.qml
Button {
    property color bgColor: "lightgray"
    background: Rectangle {
        color: parent.bgColor
    }
}

// main.qml
CustomButton {
    text: "自定义"
    bgColor: "lightblue"
}

常见误区与总结

• 误区：将所有代码写在一个巨大的 QML 文件中，导致难以维护。应遵循单一职责原则，拆分为多个小组件。
• 误区：忽略 import 的版本控制。不同版本的 Qt Quick 可能有 API 差异，应明确指定版本号。
• 总结：良好的代码结构是项目可持续演进的基础。通过模块化、清晰的注释和合理的文件组织，可以显著降低后期维护成本。