【Qt6 QML Book 基础】02：Qt6QML语法基础（含完整可运行代码）

原创已于 2025-04-23 22:31:17 修改 · 926 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#qt6 #qt6qml #c++

于 2025-04-21 08:35:13 首次发布

Qt6Qml基础专栏收录该内容

15 篇文章

订阅专栏

引言

在跨平台 UI 开发领域，Qt6 QML 凭借其声明式语法和高效的组件化设计，成为构建现代化界面的首选方案。它通过简洁的语法描述 UI 元素层级、属性绑定和交互逻辑，大幅降低了复杂界面的开发成本。本文结合官方技术文档，针对国内开发者习惯，深度解析 QML 核心语法，并提供可直接运行的完整中文示例代码，帮助读者快速掌握从基础语法到实战应用的全流程。

运行效果图

在正式解析 QML 语法之前，先通过运行效果图了解本文示例代码的实际呈现效果，帮助读者建立直观认知。以下是示例程序的核心界面布局与交互状态：

（实际效果：窗口标题为 “Qt6 QML 语法示例”，中心显示一个深灰色矩形卡片，卡片内包含：

顶部居中的红色三角形图片
图片下方的 “三角形” 中文标题（白色字体，居中显示）
左下角的交互文本区域，显示空格按键次数）

一、QML 语法核心特性：声明式 UI 开发的精髓

QML 是一种声明式语言，通过描述对象关系和属性来定义 UI，而非命令式逻辑。其核心思想与 HTML+JavaScript 相似，但天生为 UI 设计优化，更适合描述界面元素的层级、外观和交互逻辑。

1. 元素层级与坐标系

层级结构：QML 界面由元素嵌套构成，子元素继承父元素的坐标系，x/y坐标始终相对于父元素。
根元素：每个 QML 文件必须有且仅有一个根元素（如Window、Rectangle），类似 HTML 的<html>标签。

// 根元素为Window，包含一个居中的Rectangle
Window {
    width: 300; height: 400
    Rectangle {
        id: root
        width: 120; height: 240
        color: "#4A4A4A"
        anchors.centerIn: parent // 相对于父元素居中
    }
}

2. 模块导入与版本管理（Qt6 新特性）

模块导入：使用import语句引入模块，Qt6 中版本号可选（如import QtQuick 6.0），默认使用当前 Qt Kit 的最新版本，简化代码：
qml
```
import QtQuick  // Qt6中可省略版本号，自动匹配最新
import QtQuick.Window
```

二、属性系统：QML 界面的 “基因”

QML 元素通过属性定义外观和行为，支持基础值、绑定、自定义属性等多种形式，是实现响应式界面的核心。

1. 属性类型与声明方式

基础属性：直接赋值，如width: 100、color: "#FF0000"。
绑定属性：通过表达式建立依赖关系，自动响应变化（如height: 2 * width）。

自定义属性：使用property关键字扩展元素功能：

qml

Text {
    property int counter: 0  // 自定义整数属性
    text: "计数：" + counter  // 绑定到自定义属性
}

2. 高级属性技巧

属性别名（Alias）：将内部属性暴露到外部作用域，方便跨组件访问：

Rectangle {
    id: container
    property alias contentText: textLabel.text  // 别名暴露文本属性
    Text { id: textLabel; text: "内部文本" }
}

分组属性：结构化组织相关属性（如字体、布局）：

Text {
    font { family: "思源黑体"; pixelSize: 18 }  // 分组属性语法
    horizontalAlignment: Text.AlignCenter
}

附加属性：属于元素类的全局属性（如键盘导航）：

Text {
    KeyNavigation.tab: nextLabel  // 按Tab键切换到nextLabel元素
}

三、脚本与交互：JavaScript 在 QML 中的深度集成

QML 无缝集成 JavaScript，支持编写事件处理、自定义函数和复杂逻辑，实现动态交互效果。

1. 事件处理与信号响应

信号处理器：通过onXXXChanged监听属性变化，或直接处理键盘、鼠标事件：

Text {
    focus: true  // 需要焦点以接收键盘事件
    Keys.onSpacePressed: {  // 空格按下事件
        increment()  // 调用自定义函数
    }
    onTextChanged: function(newText) {  // 文本变化时触发
        console.log("新文本：", newText)
    }
}

2. 自定义函数与逻辑封装

在 QML 元素内部定义 JavaScript 函数，实现代码复用：

Rectangle {
    function calculateArea() {  // 计算面积的自定义函数
        return width * height
    }
    Text { text: "面积：" + calculateArea() }
}

四、绑定与赋值：QML 的 “动态契约” 机制

QML 的:（绑定）与 JavaScript 的=（赋值）有本质区别：

绑定（:）：建立动态契约，属性值随依赖项自动更新，如：
```
ProgressBar { value: progress }  // 进度条值绑定到progress属性
```

赋值（=）：一次性设置值，会破坏原有绑定（慎用！）：

// 按下ESC时清空文本，同时破坏text属性的绑定关系
Keys.onEscapePressed: { label.text = "" }

最佳实践：若需在多个地方修改同一属性，避免混合使用绑定和赋值，改用统一的 JavaScript 逻辑或状态机管理。

五、完整可运行示例：整合三大核心语法

以下代码整合了元素层级、属性系统和脚本交互，包含中文注释和本地化适配：

import QtQuick
import QtQuick.Window

Window {
    id: mainWindow
    width: 300; height: 400
    visible: true
    title: "Qt6 QML 语法示例"  // 中文标题

    // 根矩形元素（居中显示）
    Rectangle {
        id: root
        width: 240; height: 320
        color: "#4A4A4A"
        anchors.centerIn: parent

        // 图片元素
        Image {
            id: triangleImg
            x: (parent.width - width)/2; y: 40
            source: "assets/triangle_red.png"  // 确保资源路径正确
        }

        // 文本元素：演示绑定与自定义属性
        Text {
            id: infoText
            y: triangleImg.y + triangleImg.height + 20
            width: root.width
            color: "white"
            horizontalAlignment: Text.AlignHCenter
            text: "三角形"  // 中文静态文本
        }

        // 交互文本：演示键盘事件与JavaScript函数
        Text {
            id: controlText
            x: 40; y: 160
            width: 200
            property int spaceCount: 0  // 记录空格按下次数
            text: "空格已按：" + spaceCount + " 次"  // 绑定自定义属性
            focus: true  // 启用焦点以接收键盘事件

            // 文本变化时打印日志（信号处理器）
            onTextChanged: function(newText) {
                console.log("计数更新：", newText)
            }

            // 空格按下时调用函数
            Keys.onSpacePressed: {
                updateCount()  // 调用自定义函数
            }

            // 自定义计数函数
            function updateCount() {
                spaceCount++  // 递增计数器，触发文本绑定更新
            }
        }
    }
}