【Qt6 QML Book 基础】03：核心元素（附完整可运行工程代码）-优快云博客

前言

在 Qt6 QML 开发中，Rectangle、Text、Image 等核心视觉元素是构建高性能界面的基础。继前两篇《可交互旋转风车动画》《QML 语法基础》之后，本文结合官方教程，通过完整可运行工程示例与逐行中文注释，系统解析视觉元素的样式控制、布局逻辑与交互实现，帮助开发者夯实 QML 界面开发基础。

一、运行效果图

本文示例代码运行后，界面包含矩形样式演示、文本效果展示、图像缩放裁剪及交互功能区，各元素按坐标精准定位，视觉层次分明。实际效果如下：

二、核心视觉元素概览

Qt6 QML 的视觉元素均继承自 Item 基类，共享几何定位、样式渲染、交互响应等通用能力。本章重点解析以下核心元素：

矩形（Rectangle）：基础图形绘制，支持纯色填充、边框、圆角及线性渐变
文本（Text）：复杂文本显示，支持字体样式、中间省略、下沉效果与对齐控制
图像（Image）：图片加载与显示控制，支持原始尺寸、等比缩放裁剪
鼠标区域（MouseArea）：非视觉交互组件，实现点击事件响应与元素状态切换

三、核心元素代码解析（含中文注释）

3.1 窗口与基础设置

import QtQuick          

Window {  
    id: mainWindow            // 主窗口唯一标识符  
    width: 640; height: 480   // 窗口尺寸（宽×高，像素）  
    visible: true             // 窗口默认可见  
    title: qsTr("核心视觉元素演示")  // 窗口标题（支持多语言翻译）

3.2 矩形元素：从基础形状到复杂样式

3.2.1 纯色填充矩形

    Rectangle {  
        id: rectSolid             // 纯色矩形标识  
        x: 12; y: 12              // 元素左上角坐标（x,y）  
        width: 76; height: 96     // 宽度与高度  
        color: "lightsteelblue"   // 填充颜色（使用SVG预定义颜色名）  
    }

3.2.2 边框圆角矩形

    Rectangle {  
        id: rectBorder            // 边框矩形标识  
        x: 112; y: 12             // 右移100像素（与前一矩形间隔80像素）  
        width: 76; height: 96     // 相同尺寸  
        border.color: "lightsteelblue"  // 边框颜色与填充色一致  
        border.width: 4           // 边框宽度（4像素）  
        radius: 8                 // 圆角半径（实现8像素圆角效果）  
    }

3.2.3 渐变填充矩形

    Rectangle {  
        id: rectGradient          // 渐变矩形标识  
        x: 212; y: 12             // 继续右移100像素  
        width: 176; height: 96    // 加宽尺寸以展示更长渐变区域  
        gradient: Gradient {      // 垂直方向线性渐变（顶部到底部）  
            GradientStop { position: 0.0; color: "lightsteelblue" }  // 渐变起点  
            GradientStop { position: 1.0; color: "slategray" }        // 渐变终点  
        }  
        border.color: "slategray"  // 边框颜色与渐变终点一致，保持视觉统一  
    }

3.3 文本元素：多场景文本显示方案

3.3.1 基础文本样式

    Text {  
        id: textNormal            // 普通文本标识  
        x: 12; y: 126            // 位于矩形区域下方126像素  
        text: "The quick brown fox"  // 显示文本内容  
        color: "#303030"         // 深灰色文本（十六进制RGB值）  
        font.family: "Ubuntu"     // 字体家族（推荐无衬线字体提升可读性）  
        font.pixelSize: 28       // 字体大小（适合标题类文本）  
    }

3.3.2 高级文本处理

    Text {  
        id: textAdvanced          // 高级文本标识  
        x: 12; y: 156            // 位于普通文本下方30像素  
        width: 40; height: 130    // 限定文本显示区域（强制换行或省略）  
        text: 'A very long text'  // 长文本内容（用于演示省略效果）  
        elide: Text.ElideMiddle   // 中间省略模式（显示为“…very long…”）  
        style: Text.Sunken        // 下沉样式（模拟立体效果）  
        styleColor: '#FF4444'     // 样式颜色（红色增强视觉对比）  
        verticalAlignment: Text.AlignTop  // 垂直顶部对齐  
        // wrapMode: Text.WordWrap  // 如需换行，取消注释并确保足够宽度  
    }

3.4 图像元素：图片加载与显示控制

3.4.1 原始尺寸显示

    Image {  
        id: imageOriginal        // 原始图片标识  
        x: 12; y: 196           // 位于文本区域下方196像素  
        source: "assets/triangle_red.png"  // 本地图片路径（需提前放入assets目录）  
        // 未设置宽高时，默认按图片实际尺寸渲染  
    }

3.4.2 裁剪缩放显示

    Image {  
        id: imageCropped         // 裁剪图片标识  
        x: 12 + 64 + 12; y: 196 // x坐标计算：原始图片宽度64 + 左右边距各12  
        height: 36              // 高度设置为原始一半（72像素→36像素）  
        source: "assets/triangle_red.png"  
        fillMode: Image.PreserveAspectCrop  // 保持宽高比并裁剪超出部分  
        clip: true                  // 启用裁剪（必须配合fillMode使用）  
    }

3.5 鼠标区域：实现元素交互逻辑

    Rectangle {  
        id: interactRect         // 交互矩形标识  
        x: 12; y: 276            // 位于图像区域下方276像素  
        width: 76; height: 96    // 相同尺寸  
        color: "lightsteelblue"  // 填充颜色与首个矩形一致  
        MouseArea {              // 覆盖父矩形的交互区域  
            width: parent.width; height: parent.height  // 完全覆盖父元素  
            onClicked: targetRect.visible = !targetRect.visible  // 点击切换目标矩形可见性  
        }  
    }  

    Rectangle {  
        id: targetRect           // 目标矩形标识（初始隐藏）  
        x: 112; y: 276           // 位于交互矩形右侧100像素  
        width: 76; height: 96    // 相同尺寸  
        border.color: "lightsteelblue"; border.width: 4; radius: 8  // 边框与圆角  
        visible: false          // 初始状态不可见  
    }  
}