SplitView QML Type

在各项之间放置可拖动的分隔线来排列项目。更多...

• 所有成员的列表，包括继承的成员

属性

• 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 支持在其管理的项目上设置以下附加属性：

• SplitView.minimumWidth
• SplitView.minimumHeight
• SplitView.preferredWidth
• SplitView.preferredHeight
• SplitView.maximumWidth
• SplitView.maximumHeight
• SplitView.fillWidth （仅有一个子项时为 true）
• SplitView.fillHeight （仅有一个子项时为 true）

此外，每个控件柄具有以下只读附加属性：

• SplitHandle.hovered
• SplitHandle.pressed

SplitView 中项目的首选大小可通过 `implicitWidth ` 和 `implicitHeight ` 或 `SplitView.preferredWidth ` 和 `SplitView.preferredHeight` 进行指定：

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 `（若 `orientation ` 为 `Qt.Vertical`，则为 `SplitView.fillHeight`）。这意味着当其他项目布局完成后，该项目将占据所有剩余空间。默认情况下，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 的主要目的是让用户能够轻松配置各种 UI 元素的大小。此外，用户偏好的大小应在不同会话之间被记住。为实现这一点，可以使用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 次。

下表说明了根据拆分视图的取向，每个控件将如何调整大小：

若要在不改变其视觉尺寸的情况下调整鼠标和触摸事件中控件的大小，请使用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 的朝向。

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

可能的取值：

resizing : bool [read-only]

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

附加属性文档

SplitView.fillHeight : bool [attached]

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

默认情况下，拆分视图中最后一个可见的子项将填满整个视图，但可以通过在另一个项上显式将fillHeight 设置为true 来更改此行为。如果有多个项的fillHeight 被设置为true ，则最上层的项将填满整个视图。

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

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

SplitView.fillWidth : bool [attached]

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

默认情况下，分屏视图中最后一个可见的子项将填满视图，但可以通过在另一个项上显式将fillWidth 设置为true 来更改此行为。如果多个项的fillWidth 均设置为true ，则最左侧的项将填满视图。

对于将fillWidth 设置为true 的分割项，其宽度仍受其minimumWidth 和maximumWidth 的限制。

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

SplitView.maximumHeight : real [attached]

此附加属性控制拆分项的最大高度。preferredHeight 受minimumHeight 和 maximumHeight 的限制。拆分项无法被拖动至超过其maximumHeight 的大小。

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

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

SplitView.maximumWidth : real [attached]

此附加属性控制拆分项的最大宽度。preferredWidth 的取值范围限定在minimumWidth 和 maximumWidth 之间。拆分项无法被拖动至超过其maximumWidth 的宽度。

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

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

SplitView.minimumHeight : real [attached]

此附加属性控制拆分项的最小高度。preferredHeight 的取值范围限定在minimumHeight和maximumHeight 之间。拆分项无法被拖动至小于其minimumHeight 的大小。

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

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

SplitView.minimumWidth : real [attached]

此附加属性用于控制拆分项的最小宽度。preferredWidth 被限定在 minimumWidth 和maximumWidth 之间。拆分项无法被拖动至小于其minimumWidth 的宽度。

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

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

SplitView.preferredHeight : real [attached]

此附加属性用于控制拆分项的首选高度。首选高度将作为该项的大小，并受minimumHeight 和maximumHeight 的限制。如果未设置首选高度，则将使用该项的implicitHeight 。

当拆分项调整大小时，将设置 preferredHeight 以记录新尺寸。

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

另请参阅 minimumHeight 、maximumHeight 、fillHeight 以及preferredWidth 。

SplitView.preferredWidth : real [attached]

此附加属性用于控制拆分项的首选宽度。首选宽度将作为该项的尺寸，并受minimumWidth 和maximumWidth 的限制。如果未设置首选宽度，则使用该项的implicitWidth 。

当拆分项调整大小时，将设置 preferredWidth 以记录新尺寸。

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

另请参阅 minimumWidth 、maximumWidth 、fillWidth 以及preferredHeight 。

SplitView.view : SplitView [attached]

此附加属性保存其所附加项的分屏视图，如果该项未处于分屏视图中，则保存null 。

方法文档

bool restoreState(state)

从state 读取首选尺寸，并将其应用于拆分后的项目。

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

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

var saveState()

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

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