4、Qt Quick核心元素：Rectangle、Text、Image、Item、基础布局与坐标系统

Qt Quick 的声明式 UI 构建，其核心并非复杂的类继承体系，而是围绕一组高度可组合的基础元素（Element）展开。理解 Item、Rectangle、Text 与 Image 的职责边界，以及它们所依赖的坐标系统与布局机制，是掌握 QML 开发的关键第一步。本章将深入剖析这些核心元素的内部原理、使用规范与常见陷阱，帮助您建立扎实的 QML 视觉构建基础。

上图清晰地展示了 Qt Quick 中视觉元素的基本关系：所有可视元素最终都继承自抽象的 Item 类型，而 Rectangle、Text、Image 则是 Item 最直接、最常用的具体实现。它们共享 Item 提供的核心属性（如位置、尺寸、透明度），同时又各自扩展了专有的渲染能力。理解这一层级关系，是进行复杂界面设计的基础。

4.1 核心原理：一切皆 Item，渲染各不同

在 QML 的世界里，Item 本身并不绘制任何内容，它是一个纯粹的逻辑与几何容器。它定义了所有可视元素共有的抽象契约：几何属性（x, y, width, height, z）、变换属性（scale, rotation, transformOrigin）、视觉属性（opacity, visible, clip）以及布局属性（anchors）。任何复杂的 UI 组件，本质上都是一棵由 Item 及其子类组成的树。

• Rectangle：用于绘制填充矩形区域。其核心属性 color 定义填充色，radius 定义圆角半径，border.color 与 border.width 定义描边。它常被用作背景、卡片、分隔线或占位符。值得注意的是，Rectangle 的 color 属性支持渐变（通过 Gradient 对象），但性能上纯色填充最优。
• Text：负责显示文本。其核心属性 text 为显示字符串，font.family、font.pixelSize、font.bold 等控制字体样式，color 控制文本颜色。关键特性是 horizontalAlignment 与 verticalAlignment 控制对齐方式，wrapMode 控制换行策略。此外，elide 属性可以在文本过长时显示省略号，textFormat 支持纯文本或富文本（Rich Text）。
• Image：用于显示位图图像。核心属性 source 指定图像来源（本地文件路径或 URL），fillMode 决定图像如何适应 Image 元素的边界框。常见的 fillMode 包括 Stretch（拉伸填充）、PreserveAspectFit（保持比例完整显示）、PreserveAspectCrop（保持比例并裁剪填充）。Image 还支持异步加载（asynchronous）和缓存（cache）以优化性能。

4.2 操作流程：构建一个静态卡片组件

让我们通过一个具体的操作流程，来演示如何综合运用这些元素。假设我们需要构建一个用户信息卡片，包含头像、姓名和简介。我们将遵循“自顶向下”的布局思路。

1. 创建根容器：使用 Rectangle 作为卡片背景，设置固定宽度（如 300px）和高度（如 100px），并设置 radius 和 border 以美化外观。
2. 放置头像：在根 Rectangle 内部，添加一个 Image 元素。通过 anchors.left 和 anchors.verticalCenter 将其锚定在左侧垂直居中。设置 source 为头像图片路径，并设置 width 和 height 为 60px，fillMode 为 PreserveAspectCrop 并配合 clip: true 实现圆形裁剪效果（外层再套一个 Rectangle 设置 radius）。
3. 布局文本区域：在头像右侧，创建一个 Item 作为文本区域的容器。设置其 anchors.left 为头像的右边距，anchors.right 为父容器的右边距，anchors.verticalCenter 与父容器垂直居中。这样，文本区域就自动适应了剩余空间。
4. 填充文本内容：在文本容器 Item 内部，添加两个 Text 元素。第一个用于显示姓名，设置较大的 font.pixelSize 和加粗属性。第二个用于显示简介，设置较小的字号和灰色 color。通过 anchors.top 和 anchors.left 控制它们的相对位置。

import QtQuick 2.15
import QtQuick.Controls 2.15

Rectangle {
    width: 320; height: 80
    radius: 8
    border.color: "#cccccc"
    border.width: 1

    // 头像裁剪容器
    Rectangle {
        id: avatarContainer
        width: 60; height: 60
        radius: 30 // 圆形
        clip: true
        anchors.left: parent.left
        anchors.leftMargin: 10
        anchors.verticalCenter: parent.verticalCenter

        Image {
            anchors.fill: parent
            source: "images/avatar.png"
            fillMode: Image.PreserveAspectCrop
        }
    }

    // 文本区域容器
    Item {
        id: textArea
        anchors.left: avatarContainer.right
        anchors.leftMargin: 12
        anchors.right: parent.right
        anchors.rightMargin: 10
        anchors.verticalCenter: parent.verticalCenter

        Text {
            id: nameText
            anchors.top: parent.top
            anchors.left: parent.left
            anchors.right: parent.right
            text: "张三"
            font.pixelSize: 18
            font.bold: true
            color: "#333333"
            elide: Text.ElideRight
        }

        Text {
            id: descText
            anchors.top: nameText.bottom
            anchors.topMargin: 4
            anchors.left: parent.left
            anchors.right: parent.right
            text: "高级软件工程师，专注于 Qt/QML 开发。"
            font.pixelSize: 12
            color: "#666666"
            wrapMode: Text.WordWrap
            maximumLineCount: 2
            elide: Text.ElideRight
        }
    }
}

4.3 案例拆解：坐标系统与锚点布局的实战对比

为了更深刻地理解坐标系统，我们来看一个典型的场景：在一个 400x400 的窗口中，需要将两个按钮（Button A 和 Button B）并排居中显示。我们对比两种实现方式。

在这个案例中，坐标（x, y）是相对于父 Item 的左上角计算的。如果父窗口的 width 从 400 变为 500，那么按钮 A 和 B 仍然停留在 (100, 180) 和 (220, 180)，不再居中。而使用锚点布局，我们只需定义按钮之间的相对关系：Button A 的右边距与 Button B 的左边距对齐，Button B 的右边距与父容器的右边距对齐。这样，无论父容器如何变化，两个按钮组成的整体始终水平居中。

4.4 常见误区与总结复盘

在实际开发中，初学者常会遇到以下几个问题，我们在此进行复盘与总结。

• 误区一：混淆 Item 与 Rectangle 的使用场景。很多新手喜欢用 Rectangle 作为所有元素的根容器，即使它不需要背景色。这会导致不必要的渲染开销。正确的做法是：如果只需要一个逻辑分组或定位容器，应使用 Item；只有当需要绘制背景、边框或圆角时，才使用 Rectangle。
• 误区二：忽略 clip 属性。当子元素的内容超出父 Item 的边界时，默认情况下是会被绘制出来的（除非父元素设置了 clip: true）。这常常导致界面出现意外的视觉溢出。例如，在实现圆角头像时，如果不设置 clip: true，图片的直角就会暴露出来。
• 误区三：对 Text 的隐式尺寸理解不足。 Text 元素在没有显式设置 width 和 height 时，会自动计算其内容所需的尺寸。这在布局中非常有用，但也可能导致问题。例如，当您需要将 Text 放入一个固定大小的容器中，并希望文本超出时显示省略号，就必须显式设置 Text 的 width 和 height，并配合 elide 属性。
• 误区四：忽视 z 轴顺序。当多个元素重叠时，它们的绘制顺序由 z 属性决定。默认情况下，z 值为 0，后添加的子元素会绘制在先添加的子元素之上。如果需要控制层级，应显式设置 z 值，而不是依赖声明顺序。