Back to Qt.io
Contact Us Blog Download Qt
本页内容

Qt Quick Layouts 响应式布局

Qt Quick Layouts 概述

使用Qt Quick Layouts 来排列用户界面中的控件。Qt Quick Layouts 会自动调整控件的大小，因此非常适合用于可调整大小的用户界面。

主要功能

Qt Quick Layouts 的部分关键功能包括：

此外，GridLayout 还增加了以下功能：

入门指南

要开始使用Qt Quick Layouts ，请在.qml 文件中使用以下导入语句将QML类型导入到您的应用程序中：

import QtQuick.Layouts

下一步是创建一个简单的布局。您还可以参考《Qt Quick Layouts - 基本示例》。

一个简单的布局

使用布局的目的是在布局大小发生变化时重新排列其子元素。这意味着应用程序必须确保布局能够调整大小。在下面的代码片段中，RowLayout通过指定 `anchors.fill: parent` 来确保这一点。不过，你也可以通过其他方式实现，例如指定 `width ` 和 `height ` 属性。 在同一代码片段中，橙色的 Rectangle具有100×150像素的固定尺寸，而深紫色的 Rectangle则会扩展以占据其被分配的全部空间。

Window {
    RowLayout {
        anchors.fill: parent
        spacing: 6
        Rectangle {
            color: 'azure'
            Layout.preferredWidth: 100
            Layout.preferredHeight: 150
        }
        Rectangle {
            color: "plum"
            Layout.fillWidth: true
            Layout.fillHeight: true
        }
    }
}

布局负责管理其子元素的几何属性。这包括width 、height 、x 、y 、anchors 等属性。

重要提示：请勿 在应用程序中为会影响子项几何属性的元素指定相关属性。在子项上设置这些属性会导致利益冲突，且结果未定义。当子项为布局时，此规则同样适用。因此，只有没有父布局的布局才能具有anchors.fill: parent 属性。

间距

如前面的代码片段所示，RowLayout的间距设置为6。这确保了布局中的所有项目之间都保持 6 像素的间距：

spacing: 6

若未指定间距值，布局将采用5像素的默认值。间距以及任何子元素的implicitWidth都会影响布局的implicitWidth。若依赖默认行为，这一点尤为重要，因为它可能会影响您的布局设计。例如，在以下代码片段中，这两个 ColumnLayout都设置了Layout.fillWidth: true。人们自然会认为它们的宽度会相同。然而，由于内部RowLayout 中项目之间的默认间距为 5 像素，第一个ColumnLayout的隐式宽度会变大，从而为第二个留出的空间更少。 例如：

ApplicationWindow {
    id: root
    width: 300
    height: 300
    visible: true

    RowLayout {
        anchors.fill: parent
        ColumnLayout {
            Rectangle {
                color: "tomato";
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            RowLayout {
                Rectangle {
                    color: "navajowhite"
                    Layout.fillWidth: true
                    Layout.fillHeight: true
                }
                Rectangle {
                    color: "darkseagreen"
                    Layout.fillWidth: true
                    Layout.fillHeight: true
                }
            }
        }
        ColumnLayout {
            Rectangle {
                color: "lightpink"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            Rectangle {
                color: "slategray"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            Rectangle {
                color: "lightskyblue"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
        }
    }
}

此代码片段生成的布局效果如下：

具有默认间距的 QML 布局

为了确保这两个列的大小相等，你可以

  1. 将RowLayout的间距设置为 `0`，或者
  2. 将两列的preferredWidth都设置为相同值 ColumnLayout。

指定首选尺寸

对于每个项目，其实际首选尺寸可能来自多个候选属性之一。为了确定实际首选尺寸，项目将按以下顺序查询这些候选属性，并采用第一个具有有效宽度或高度的候选属性。

候选属性描述
Layout.preferredWidth 或Layout.preferredHeight如果默认的隐式尺寸无法实现最佳布局，应用程序应修改这些属性。
implicitWidth 或implicitHeight 。每个项目应提供这些属性，以给出一个有意义的理想尺寸。例如，显示Text 类型所有内容所需的尺寸。0 的隐式宽度或高度将被视为无效。

项目可以指定Layout.preferredWidth ，而无需指定Layout.preferredHeight 。在这种情况下，实际的首选高度将根据implicitHeight 确定。

注意：若既 未指定 preferredWidth 也未指定 implicitWidth，布局将查询width 作为有效首选宽度的最终值。但是，不应依赖width 作为有效首选宽度的来源，因为这可能会导致意外行为。 例如，更改width 或height 属性不会触发布局重新排列；或者当被迫进行完全重建时，布局可能会使用实际的宽度和高度——而非 QML 文件中指定的宽度和高度。

尺寸约束

由于项目可以通过其布局进行调整大小，因此布局需要知道所有将 `Layout.fillWidth ` 或 `Layout.fillHeight ` 设置为`true` 的项目的 `minimum`、`preferred` 和 `maximum ` 尺寸。

如果布局本身未绑定到特定大小，则preferred 的宽度和高度即为项目的实际宽度和高度。如果布局被设置为特定大小，它将根据其项目首选大小的比例分配剩余空间，同时考虑最小和最大大小。 当所有项目都设置了fillWidth和fillHeight 时，首选尺寸和隐式尺寸将作为比例和权重发挥作用。

例如，以下代码将生成一个包含两个并排矩形的布局，该布局在水平方向上可拉伸。橙色矩形的大小可以从 50x150 调整为 300x150，而梅红色矩形的大小可以从 100x100 调整为 ∞x100。 只要未超过每个项的最小和最大宽度，梅红色矩形的宽度将是橙色矩形的两倍。

RowLayout {
    id: layout
    anchors.fill: parent
    spacing: 6
    Rectangle {
        color: 'orange'
        Layout.fillWidth: true
        Layout.minimumWidth: 50
        Layout.preferredWidth: 100
        Layout.maximumWidth: 300
        Layout.minimumHeight: 150
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
    Rectangle {
        color: 'plum'
        Layout.fillWidth: true
        Layout.minimumWidth: 100
        Layout.preferredWidth: 200
        Layout.preferredHeight: 100
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
}

RowLayout 的最小实现

综合各元素的约束条件，可得出布局元素的以下隐式约束：

最小首选最大值
隐式约束（宽度）156306∞（Number.POSITIVE_INFINITY ）
隐式约束（高度）150150150

因此，布局的宽度不能小于156，高度也不能大于或小于150，否则将违反其子项的任何约束条件。

连接窗口和布局

您可以使用常规的锚定概念来确保布局能够跟随窗口的大小调整而调整。

RowLayout {
    id: layout
    anchors.fill: parent

您可以利用布局的大小约束，确保窗口无法被调整到超出布局约束的范围。 您可以获取布局的大小约束，并将这些约束设置为Window 元素的minimumWidth、minimumHeight、maximumWidth和 maximumHeight属性。以下代码可确保窗口无法调整到超出布局约束的范围：

minimumWidth: layout.Layout.minimumWidth
minimumHeight: layout.Layout.minimumHeight
maximumWidth: 1000
maximumHeight: layout.Layout.maximumHeight

注意：由于 在此情况下layout.Layout.maximumWidth是无穷大，我们无法将其绑定到 Window 的maximumWidth属性上，因为该属性是一个整数。因此，最大宽度被设置为固定值1000 。

最后，将窗口的初始大小设置为布局的隐式大小：

width: layout.implicitWidth
height: layout.implicitHeight

项的跨行和拉伸

在GridLayout 中使用spans ，可使子项占用多个单元格。例如，您可能有一个GridLayout ，其中包含两行共六个单元格。 顶部一行包含项目item1、item2 和 item3。底部一行包含项目item4，该项目指定了columnSpan: 3和alignment: Qt.AlignHCenter。这会将 item4 置于构成底部一行三个单元格的中间位置。以下代码片段供参考：

ApplicationWindow {
    id: root
    width: 300
    height: 300
    visible: true

    GridLayout {
       rows: 2
       columns: 3
       Rectangle {
           color: 'cyan'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'magenta'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'yellow'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'black'
           implicitWidth: 50
           implicitHeight: 50
           Layout.columnSpan: 3
           Layout.alignment: Qt.AlignHCenter
       }
    }
}

行和列的大小由其内容隐式决定。 例如，一个 Button 可能会影响其所在列的宽度，或其所在行的高度。这意味着GridLayout 不会均匀分布。因此，您无法使用 span 来拉伸布局。若要调整项目或布局的拉伸程度，请改用stretchFactors 和/或大小提示。

注意：在 设置隐式或首选尺寸时 ，请勿将相关属性绑定到布局本身或其尺寸计算所依赖的项的宽度或高度上，因为这可能会导致难以排查的循环依赖关系。

Qt Quick Layouts 响应式布局

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.