📚 课程目录第3章 Qt Quick核心组件

3. Qt Quick核心组件

在QML工业HMI开发中，界面并不是靠“控件堆叠”完成的，而是由一组职责清晰的基础组件组合而成。理解这些组件的定位、属性体系和协作方式，是构建可维护、可复用HMI界面的前提。本节围绕Item、Rectangle、Text、Image、MouseArea、Button六个核心组件展开，说明它们在工业场景中的典型用法与组合关系。

一、核心原理：Item是所有可视元素的基类

在Qt Quick中，Item是最基础的可视元素类型，它本身不绘制任何内容，但定义了所有可视元素共有的几何与变换能力：位置（x、y）、尺寸（width、height）、锚点（anchors）、层级（z）、透明度（opacity）、旋转与缩放（rotation、scale）、可见性（visible）以及焦点和键盘处理能力。可以说，Rectangle、Text、Image、MouseArea等组件都直接或间接继承自Item，因此它们天然具备上述属性。

工业HMI中，Item常被用作“逻辑容器”或“布局分组”。例如把一组泵状态指示器放入一个Item中统一控制可见性，或作为自定义组件的根节点。需要特别注意的是，Item没有背景色，若需要可见的矩形区域，应使用Rectangle。

Item不绘制自身，但它是所有可视组件的“坐标系与变换基础”。在HMI中，Item更多承担分组、布局和逻辑承载的角色。

二、常用组件职责与关键属性

下面用一张结构关系图展示六个核心组件之间的继承与协作关系，以及它们在HMI中的典型职责。

从图中可以看出，Rectangle、Text、Image、MouseArea都继承自Item，而Button则是Qt Quick Controls 2中对“矩形背景+文本+鼠标交互”的封装。理解这层关系后，就能明白为什么自定义按钮时，往往用Rectangle+Text+MouseArea组合实现，而不是直接修改Button的内部结构。

三、方法流程：从零构建一个HMI状态指示灯

下面以工业HMI中常见的“泵运行状态指示灯”为例，说明组件的组合流程。该指示灯需要：矩形背景、圆形灯体、状态文字、点击查看详情。

import QtQuick 2.15
import QtQuick.Controls 2.15

Item {
    width: 160; height: 120

    Rectangle {
        id: lampBody
        width: 60; height: 60
        radius: 30
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.top: parent.top
        color: running ? "#2ecc71" : "#95a5a6"
        border.color: "#2c3e50"
        border.width: 2

        Behavior on color {
            ColorAnimation { duration: 300 }
        }
    }

    Text {
        id: lampLabel
        anchors.top: lampBody.bottom
        anchors.topMargin: 8
        anchors.horizontalCenter: parent.horizontalCenter
        text: running ? "运行中" : "已停止"
        font.pixelSize: 16
        color: "#2c3e50"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: detailPanel.visible = true
    }
}

这段代码体现了典型的HMI组件组合思路：Rectangle负责灯体外观，Text负责状态文字，MouseArea负责交互，Item作为根容器统一管理。其中Behavior on color让状态切换具有平滑过渡，避免工业现场因颜色突变造成误判。

四、案例/场景：组件在工业HMI中的典型应用

组件	HMI典型用途	关键属性	注意事项
Item	页面分组、自定义组件根节点	x、y、anchors、visible	无背景，需配合Rectangle使用
Rectangle	面板背景、按钮底板、状态灯	color、radius、border、gradient	圆角半径不宜超过短边一半
Text	参数值、报警信息、标签	text、font、color、elide	长文本需设置elide或wrapMode
Image	设备图标、工艺流程图、Logo	source、fillMode、cache	工业现场建议使用本地资源
MouseArea	点击、悬停、拖拽交互	onClicked、hoverEnabled、drag	注意与父级事件冒泡关系
Button	确认、取消、复位等操作按钮	text、onClicked、enabled	样式定制需重写background

五、误区与复盘

常见误区一：用Item当背景。Item本身不绘制任何内容，若直接给Item设置color属性会报错。需要背景时应使用Rectangle。

常见误区二：MouseArea覆盖顺序错误。MouseArea必须放在被点击元素的上层或同层，否则可能被其他元素遮挡导致点击无效。在HMI中，建议将MouseArea作为最后一个子元素声明。

复盘建议：在工业HMI中，优先使用Rectangle+Text+MouseArea组合实现自定义控件，而不是直接修改Button内部结构。这样既能保证样式统一，又便于后续维护和复用。同时，所有交互组件都应考虑触摸屏操作场景，适当增大点击热区。

掌握这六个核心组件后，后续的布局管理、状态机、动画和自定义控件都将建立在这一基础之上。建议在实际项目中反复练习组件的组合方式，逐步形成自己的HMI组件库。