QML开发：高级布局组件

原创已于 2025-08-09 15:19:25 修改 · 1.1k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#qt

于 2025-08-09 15:18:23 首次发布

QML教程专栏收录该内容

10 篇文章

订阅专栏

文章目录

一、RowLayout 介绍

RowLayout 是 Qt Quick Layouts 模块中的一个水平线性布局容器，它会将子元素按照从左到右的顺序排列。

与基础的 Row 不同，RowLayout 支持：

自动分配和调整子元素大小，配合子元素的 Layout.* 属性可以实现灵活的伸缩行为；
支持间距（spacing）和内边距（margins）；
子元素的大小、对齐和填充空间都可以被精准控制。

RowLayout 适合用来实现响应式的水平排列布局，比如工具栏按钮组、横向菜单、表单中一行的控件排列等。

常用属性：

spacing：子元素之间的间距（像素）
margins：容器四边的内边距
leftPadding / rightPadding / topPadding / bottomPadding：容器各边具体内边距
Layout.fillWidth / Layout.fillHeight：子元素是否填满分配空间

子元素常用 Layout 属性：
RowLayout 支持子元素设置以下属性，控制元素大小和布局行为：

Layout.preferredWidth：期望宽度
Layout.minimumWidth：最小宽度
Layout.maximumWidth：最大宽度
Layout.fillWidth：是否占用剩余水平空间（true / false）
Layout.alignment：对齐方式，如 Qt.AlignVCenter（垂直居中）

简单示例：

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Layouts 1.12

ApplicationWindow {
    visible: true
    width: 400
    height: 150
    title: "RowLayout 示例"

    RowLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        Rectangle {
            width: 50; height: 50
            color: "red"
            Layout.preferredWidth: 50
            Layout.fillHeight: true
        }

        Rectangle {
            color: "green"
            Layout.preferredWidth: 100
            Layout.fillHeight: true
        }

        Rectangle {
            color: "blue"
            Layout.fillWidth: true     // 占用剩余宽度
            Layout.fillHeight: true
        }
    }
}

RowLayout + 按钮动态添加/删除矩形元素的 QML 示例：

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Layouts 1.12

ApplicationWindow {
    visible: true
    width: 500
    height: 200
    title: "RowLayout 动态添加删除示例"

    Column {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 10

        RowLayout {
            id: boxLayout
            width: parent.width
            height: 80
            spacing: 10
            Rectangle {
                width: 60; height: 60
                color: "lightgray"
                radius: 5
                border.color: "gray"
                Text {
                    anchors.centerIn: parent
                    text: "初始"
                }
            }
        }

        Row {
            spacing: 20
            Button {
                text: "添加"
                onClicked: {
                    // 动态创建 Rectangle 元素，添加到 boxLayout
                    var component = Qt.createComponent("RectangleItem.qml")
                    if (component.status === Component.Ready) {
                        var rect = component.createObject(boxLayout)
                        if (rect === null) {
                            console.log("创建失败")
                        } else {
                            boxLayout.addItem(rect)
                        }
                    }
                }
            }
            Button {
                text: "删除"
                onClicked: {
                    // 删除最后一个元素，避免删除初始元素
                    if (boxLayout.count > 1) {
                        var item = boxLayout.itemAt(boxLayout.count - 1)
                        boxLayout.removeItem(item)
                        item.destroy()
                    }
                }
            }
        }
    }
}

并且需要单独一个 RectangleItem.qml 文件，定义动态添加的矩形组件：

import QtQuick 2.12

Rectangle {
    width: 60
    height: 60
    color: Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    radius: 8
    border.color: "black"

    Text {
        anchors.centerIn: parent
        text: "动态"
        font.bold: true
    }
}

二、ColumnLayout 介绍

ColumnLayout 是 Qt Quick Layouts 模块提供的垂直线性布局容器，它会将子元素从上到下垂直排列。

相比基础的 Column，ColumnLayout 支持：

自动调整子元素的宽高，并能根据子元素的 Layout.* 属性智能分配空间；
支持间距（spacing）和内边距（margins）；
子元素大小、对齐和填充空间的灵活控制；
适合需要响应式垂直排列的界面布局。

常用属性：

spacing：子元素之间的垂直间距（像素）
margins：容器四边的内边距
topPadding / bottomPadding / leftPadding / rightPadding：容器各边具体内边距

子元素常用 Layout 属性：

Layout.preferredHeight：期望高度
Layout.minimumHeight ：最小高度
Layout.maximumHeight：最大高度
Layout.fillHeight：是否占用剩余垂直空间（true / false）
Layout.alignment：对齐方式，如 Qt.AlignHCenter（水平居中）

简单示例：

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Layouts 1.12

ApplicationWindow {
    visible: true
    width: 300
    height: 350
    title: "ColumnLayout 示例"

    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 12

        Rectangle {
            color: "lightcoral"
            width: 200
            Layout.preferredHeight: 60
            Layout.fillWidth: true
        }

        Rectangle {
            color: "lightgreen"
            width: 200
            Layout.preferredHeight: 80
            Layout.fillWidth: true
        }

        Rectangle {
            color: "lightblue"
            width: 200
            Layout.fillHeight: true   // 填充剩余垂直空间
            Layout.fillWidth: true
        }
    }
}

三、GridLayout 介绍

RGridLayout 是 Qt Quick Layouts 模块提供的网格布局容器，它将子元素按照行和列排列，类似表格的布局方式。

相比基础的 Grid，GridLayout 支持：

自动计算和调整单元格大小，根据子元素的 Layout.* 属性动态分配空间；
支持行间距（rowSpacing）和列间距（columnSpacing）；
灵活的单元格合并和对齐；
适合复杂的二维表格布局和响应式界面

常用属性：

columns 指定列数（必填）
rows 指定行数（可选，通常由子项数量和列数自动决定）
rowSpacing 行间距（像素）
columnSpacing 列间距（像素）
margins 容器四边内边距

子元素常用 Layout 属性：

Layout.row：子元素所在的行索引（从 0 开始）
Layout.column：子元素所在的列索引（从 0 开始）
Layout.rowSpan：子元素跨越的行数
Layout.columnSpan：子元素跨越的列数
Layout.preferredWidth：子元素期望宽度
Layout.preferredHeight ：子元素期望高度
Layout.fillWidth：是否占用剩余宽度
Layout.fillHeight：是否占用剩余高度
Layout.alignment：子元素在单元格中的对齐方式

简单示例：

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Layouts 1.12

ApplicationWindow {
    visible: true
    width: 400
    height: 300
    title: "GridLayout 示例"

    GridLayout {
        anchors.fill: parent
        columns: 3
        rowSpacing: 10
        columnSpacing: 10
        margins: 15

        Rectangle {
            color: "lightcoral"
            Layout.preferredWidth: 80
            Layout.preferredHeight: 60
        }
        Rectangle {
            color: "lightgreen"
            Layout.preferredWidth: 80
            Layout.preferredHeight: 60
        }
        Rectangle {
            color: "lightblue"
            Layout.preferredWidth: 80
            Layout.preferredHeight: 60
        }
        Rectangle {
            color: "orange"
            Layout.preferredWidth: 80
            Layout.preferredHeight: 60
            Layout.columnSpan: 2  // 横跨两列
        }
        Rectangle {
            color: "plum"
            Layout.preferredWidth: 80
            Layout.preferredHeight: 60
        }
    }
}

四、StackLayout 介绍

StackLayout 是 Qt Quick Layouts 模块中的一个布局容器，将多个子项叠放在同一位置，但一次只显示其中一个子项。它通过 currentIndex 属性控制当前显示的子项，实现类似分页、选项卡页或步骤切换的界面效果。

主要特点：

所有子元素重叠显示，但只有索引为 currentIndex 的子项可见。
支持通过程序控制显示哪个子项，实现页面切换或状态切换。
方便实现多页面界面、Tab 界面、向导页等。

常用属性：

currentIndex：当前显示的子项索引，默认值 0
count：子项数量，只读

简单示例：

import QtQuick 2.12
import QtQuick.Controls 2.12
import QtQuick.Layouts 1.12

ApplicationWindow {
    visible: true
    width: 300
    height: 200
    title: "StackLayout 示例"

    Column {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        StackLayout {
            id: stackLayout
            width: parent.width
            height: 100

            Rectangle {
                color: "lightcoral"
                anchors.fill: parent
                Text {
                    anchors.centerIn: parent
                    text: "页面 1"
                    font.pixelSize: 24
                    color: "white"
                }
            }

            Rectangle {
                color: "lightgreen"
                anchors.fill: parent
                Text {
                    anchors.centerIn: parent
                    text: "页面 2"
                    font.pixelSize: 24
                    color: "white"
                }
            }

            Rectangle {
                color: "lightblue"
                anchors.fill: parent
                Text {
                    anchors.centerIn: parent
                    text: "页面 3"
                    font.pixelSize: 24
                    color: "white"
                }
            }
        }

        Row {
            spacing: 10
            Button {
                text: "上一页"
                enabled: stackLayout.currentIndex > 0
                onClicked: stackLayout.currentIndex--
            }
            Button {
                text: "下一页"
                enabled: stackLayout.currentIndex < stackLayout.count - 1
                onClicked: stackLayout.currentIndex++
            }
        }
    }
}