SplitView QML Type

在每个项目之间用可拖动的分割器排列项目。更多

Import Statement:	`import QtQuick.Controls`
Inherits:	Container

所有成员（包括继承成员）的列表

属性

handle : Component
orientation : enumeration
resizing : bool

附属物业

fillHeight : bool
fillWidth : bool
maximumHeight : real
maximumWidth : real
minimumHeight : real
minimumWidth : real
preferredHeight : real
preferredWidth : real
view : SplitView

方法

bool restoreState(state)
var saveState()

详细说明

SplitView 是一种控件，可水平或垂直排列项目，每个项目之间有一个可拖动的分割器。

SplitView 在其管理的项目上支持以下附加属性：

此外，每个句柄都有以下只读附加属性：

注意： 句柄应该是纯可视的，而不是事件句柄，因为这会干扰句柄的悬停和按下状态。

可通过implicitWidth 和implicitHeight 或SplitView.preferredWidth 和SplitView.preferredHeight 指定 SplitView 中项目的首选尺寸：

SplitView {
    anchors.fill: parent

    Item {
        SplitView.preferredWidth: 50
    }

    // ...
}

对于水平 SplitView，无需指定每个项目的首选高度，因为它们的大小将调整为视图的高度。垂直视图则相反。

拖动分割句柄时，SplitView.preferredWidth 或SplitView.preferredHeight 属性将被覆盖，具体取决于视图的orientation 。

要限制水平视图中项目的大小，请使用以下属性：

SplitView {
    anchors.fill: parent

    Item {
        SplitView.minimumWidth: 25
        SplitView.preferredWidth: 50
        SplitView.maximumWidth: 100
    }

    // ...
}

要限制垂直视图中项目的大小，请使用以下属性：

SplitView {
    anchors.fill: parent
    orientation: Qt.Vertical

    Item {
        SplitView.minimumHeight: 25
        SplitView.preferredHeight: 50
        SplitView.maximumHeight: 100
    }

    // ...
}

在 SplitView 中，总有一个项目（填充项目）的SplitView.fillWidth 设置为true （或SplitView.fillHeight ，如果orientation 是Qt.Vertical ）。这意味着该项目将获得其他项目布局后的所有剩余空间。默认情况下，SplitView 的最后一个可见子项将设置此选项，但可以通过在其他项目上将fillWidth 明确设置为true 来更改。

句柄可以属于左侧或顶部的项目，也可以属于右侧或底部的项目：

如果填充项目在右侧：句柄属于左侧项目。
如果填充项在左侧：则句柄属于右侧项。

要创建一个有三个项的 SplitView，并让中间的项获得多余的空间，可以采用以下方法：

SplitView {
    anchors.fill: parent
    orientation: Qt.Horizontal

    Rectangle {
        implicitWidth: 200
        SplitView.maximumWidth: 400
        color: "lightblue"
        Label {
            text: "View 1"
            anchors.centerIn: parent
        }
    }
    Rectangle {
        id: centerItem
        SplitView.minimumWidth: 50
        SplitView.fillWidth: true
        color: "lightgray"
        Label {
            text: "View 2"
            anchors.centerIn: parent
        }
    }
    Rectangle {
        implicitWidth: 200
        color: "lightgreen"
        Label {
            text: "View 3"
            anchors.centerIn: parent
        }
    }
}

序列化 SplitView 的状态

SplitView 的主要目的是让用户可以轻松配置各种用户界面元素的大小。此外，用户的首选尺寸应在不同会话中被记住。为此，可使用saveState() 和restoreState() 函数序列化SplitView.preferredWidth 和SplitView.preferredHeight 属性的值：

import QtCore
import QtQuick.Controls

ApplicationWindow {
    // ...

    Component.onCompleted: splitView.restoreState(settings.splitView)
    Component.onDestruction: settings.splitView = splitView.saveState()

    Settings {
        id: settings
        property var splitView
    }

    SplitView {
        id: splitView
        // ...
    }
}

或者，也可以使用Settings 的value() 和setValue() 函数：

import QtCore
import QtQuick.Controls

ApplicationWindow {
    // ...

    Component.onCompleted: splitView.restoreState(settings.value("ui/splitview"))
    Component.onDestruction: settings.setValue("ui/splitview", splitView.saveState())

    Settings {
        id: settings
    }

    SplitView {
        id: splitView
        // ...
    }
}

另请参阅 SplitHandle 、自定义 SplitView 和容器控件。

属性文档

handle : Component

该属性包含句柄组件。

只要count 大于1 ，该组件的实例就会被实例化count - 1 次。

下表解释了根据分割视图的方向如何调整每个句柄的大小：

方向	手柄宽度	句柄高度
`Qt.Horizontal`	`implicitWidth`	`height` 的SplitView 。
`Qt.Vertical`	`width` 的SplitView 。	`implicitHeight`

要在不改变视觉尺寸的情况下改变鼠标和触摸事件的手柄尺寸，请使用containmentMask ：

SplitView {
    id: splitView
    anchors.fill: parent

    handle: Rectangle {
        id: handleDelegate
        implicitWidth: 4
        implicitHeight: 4
        color: SplitHandle.pressed ? "#81e889"
            : (SplitHandle.hovered ? Qt.lighter("#c2f4c6", 1.1) : "#c2f4c6")

        containmentMask: Item {
            x: (handleDelegate.width - width) / 2
            width: 64
            height: splitView.height
        }
    }

    Rectangle {
        implicitWidth: 150
        color: "#444"
    }
    Rectangle {
        implicitWidth: 50
        color: "#666"
    }
}

另请参阅 自定义 SplitView。

orientation : enumeration

该属性表示SplitView 的方向。

方向决定了拆分项的布局方式：

可能的值

常量	说明
`Qt.Horizontal`	项目水平排列（默认）。
`Qt.Vertical`	项目垂直排列。

resizing : bool `[read-only]`

当用户通过拖动分割器手柄来调整分割项的大小时，该属性为true 。

附加属性文档

SplitView.fillHeight : bool

此附加属性控制在所有其他项目布局完毕后，项目是否占用分割视图中的剩余空间。

默认情况下，分割视图的最后一个可见子项将填充视图，但可以通过在其他项目上显式地将fillHeight 设置为true 来更改。如果多个项目都将fillHeight 设置为true ，最上面的项目将填充视图。

将fillHeight 设置为true 的拆分项的高度仍受限于其minimumHeight 和maximumHeight 。

另请参阅 minimumHeight,preferredHeight,maximumHeight 和fillWidth 。

SplitView.fillWidth : bool

此附加属性控制在所有其他项目布局完毕后，项目是否占用分割视图中的剩余空间。

默认情况下，分割视图的最后一个可见子项将填充视图，但可以通过在其他项目上显式地将fillWidth 设置为true 来更改。如果多个项目都将fillWidth 设置为true ，则最左边的项目将填充视图。

fillWidth 设置为true 的拆分项的宽度仍受限于其minimumWidth 和maximumWidth 。

另请参阅 minimumWidth,preferredWidth,maximumWidth 和fillHeight 。

SplitView.maximumHeight : real

该附加属性控制分割项的最大高度。preferredHeight 与minimumHeight 和 maximumHeight 绑定。分割项不能拖动到大于其maximumHeight 的高度。

默认值为Infinity 。要将此属性重置为默认值，请将其设置为undefined 。

另请参阅 minimumHeight,preferredHeight,fillHeight 和maximumWidth 。

SplitView.maximumWidth : real

该附加属性控制分割项的最大宽度。preferredWidth 与minimumWidth 和 maximumWidth 绑定。分割项不能拖动到大于其maximumWidth 。

默认值为Infinity 。要将此属性重置为默认值，请将其设置为undefined 。

另请参阅 minimumWidth,preferredWidth,fillWidth 和maximumHeight 。

SplitView.minimumHeight : real

该附加属性控制分割项的最小高度。preferredHeight 与 minimumHeight 和maximumHeight 绑定。分割项不能拖动到小于其minimumHeight 。

默认值为0 。要将此属性重置为默认值，请将其设置为undefined 。

另请参阅 maximumHeight,preferredHeight,fillHeight 和minimumWidth 。

SplitView.minimumWidth : real

该附加属性控制分割项的最小宽度。preferredWidth 与 minimumWidth 和maximumWidth 绑定。分割项不能拖动到小于其minimumWidth 。

默认值为0 。要将此属性重置为默认值，请将其设置为undefined 。

另请参阅 maximumWidth,preferredWidth,fillWidth 和minimumHeight 。

SplitView.preferredHeight : real

此附加属性控制分割项的首选高度。首选高度将用作项目的大小，并绑定在minimumHeight 和maximumHeight 中。如果未设置首选高度，则将使用项目的implicitHeight 。

当一个拆分的项目被调整大小时，首选高度将被设置，以便跟踪新的大小。

默认情况下，该属性未设置，因此将使用implicitHeight 代替。要将此属性重置为默认值，请将其设置为undefined 。

注意： 请勿设置拆分项的height 属性，因为它将在每次布局SplitView 时被覆盖。

另请参阅 minimumHeight,maximumHeight,fillHeight 和preferredWidth 。

SplitView.preferredWidth : real

此附加属性控制分割项的首选宽度。首选宽度将用作项目的大小，并绑定在minimumWidth 和maximumWidth 中。如果未设置首选宽度，则将使用项目的implicitWidth 。

当一个拆分的项目被调整大小时，首选宽度将被设置，以便跟踪新的大小。

默认情况下，此属性未设置，因此将使用implicitWidth 代替。要将此属性重置为默认值，请将其设置为undefined 。

注意： 请勿设置拆分项的width 属性，因为它将在每次布局SplitView 时被覆盖。

另请参阅 minimumWidth,maximumWidth,fillWidth 和preferredHeight 。

SplitView.view : SplitView

此附加属性保存所附加项目的分割视图，如果项目不在分割视图中，则保存null 。

方法文档

bool restoreState(state)

从state 中读取首选大小，并将其应用于拆分的项目。

如果状态恢复成功，则返回true ，否则返回false 。

另请参阅 Serializing SplitView's State 和saveState()。

var saveState()

将拆分项的首选尺寸保存到字节数组中并返回。

另请参阅 Serializing SplitView's State 和restoreState()。

© 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.

SplitView QML Type

属性

附属物业

方法

详细说明

序列化 SplitView 的状态

属性文档

handle : Component

orientation : enumeration

resizing : bool [read-only]

附加属性文档

SplitView.fillHeight : bool

SplitView.fillWidth : bool

SplitView.maximumHeight : real

SplitView.maximumWidth : real

SplitView.minimumHeight : real

SplitView.minimumWidth : real

SplitView.preferredHeight : real

SplitView.preferredWidth : real

SplitView.view : SplitView

方法文档

bool restoreState(state)

var saveState()

resizing : bool `[read-only]`