StackView QML Type

提供基于堆栈的导航模型。更多...

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

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

属性

busy : bool
currentItem : Item
depth : int
empty : bool (since QtQuick.Controls 2.3 (Qt 5.10))
initialItem : var
popEnter : Transition
popExit : Transition
pushEnter : Transition
pushExit : Transition
replaceEnter : Transition
replaceExit : Transition

关联属性

index : int
status : enumeration
view : StackView
visible : bool (since QtQuick.Controls 2.2 (Qt 5.9))

附加信号

activated() (since QtQuick.Controls 2.1 (Qt 5.8))
activating() (since QtQuick.Controls 2.1 (Qt 5.8))
deactivated() (since QtQuick.Controls 2.1 (Qt 5.8))
deactivating() (since QtQuick.Controls 2.1 (Qt 5.8))
removed() (since QtQuick.Controls 2.1 (Qt 5.8))

方法

void clear(transition)
Item find(callback, behavior)
Item get(index, behavior)
Item pop(item, operation)
Item popCurrentItem(operation) (since 6.7)
Item popToIndex(index, operation) (since 6.7)
Item popToItem(item, operation) (since 6.7)
Item push(item, properties, operation)
Item pushItem(item, properties, operation) (since 6.7)
Item pushItem(component, properties, operation) (since 6.7)
Item pushItem(url, properties, operation) (since 6.7)
Item pushItems(items, operation) (since 6.7)
Item replace(target, item, properties, operation)
Item replaceCurrentItem(items, operation) (since 6.7)
Item replaceCurrentItem(item, properties, operation) (since 6.7)
Item replaceCurrentItem(component, properties, operation) (since 6.7)
Item replaceCurrentItem(url, properties, operation) (since 6.7)

详细说明

显示页面导航的堆栈视图线框图

StackView 可与一组相互关联的信息页面配合使用。例如，一款电子邮件应用程序中，有分别用于列出最新邮件、查看特定邮件以及列出/查看附件的独立视图。当用户打开一封邮件时，邮件列表视图会被压入栈中；当用户选择返回时，该视图会被弹出。

以下代码片段演示了一个简单的用例，其中在点击相关按钮时，mainView 会被压入栈中，并在弹出时从栈中弹出：

ApplicationWindow {
    title: qsTr("Hello World")
    width: 640
    height: 480
    visible: true

    StackView {
        id: stack
        initialItem: mainView
        anchors.fill: parent
    }

    Component {
        id: mainView

        Row {
            spacing: 10

            Button {
                text: "Push"
                onClicked: stack.push(mainView)
            }
            Button {
                text: "Pop"
                enabled: stack.depth > 1
                onClicked: stack.pop()

            }
            Text {
                text: stack.depth
            }
        }
    }
}

在应用程序中使用 StackView

在应用程序中使用 StackView 非常简单，只需将其作为子视图添加到 Window 中即可。栈通常锚定在窗口的边缘，但顶部或底部除外——这些位置可能锚定在状态栏或其他类似的 UI 组件上。随后可通过调用其导航方法来使用该堆栈。StackView 中首先显示的项目是分配给 `initialItem` 的项目，或者如果未设置 `initialItem `，则显示最顶部的项目。

StackView 支持三种主要的导航操作：push()、pop() 和replace()。这些操作对应于经典的堆栈操作，其中“push”将一个项目添加到堆栈顶部，“pop”从堆栈中移除顶部项目，而“replace”类似于先“pop”后“push”，将顶部项目替换为新项目。栈中的最顶部项对应于屏幕上可见的项（currently ）。从逻辑上讲，“push”操作会向前导航或深入应用程序的用户界面，“pop”操作会向后导航，“replace”操作则会替换顶部项（currentItem ）。

添加项目

在下面的动画中，使用push() 函数将三个Label 控件压入堆栈视图：

栈中现在包含以下项目：[A, B, C] 。

注意：当 栈为空时，push() 操作不会产生过渡动画，因为没有可过渡的源状态（通常发生在应用程序启动时）。

弹出项目

承接上例，通过调用 `pop()` 方法移除栈顶元素：

栈中现在包含以下项目：[A, B] 。

注意： 对深度为 1 或 0 的栈执行 pop() 操作不会产生任何效果。在这种情况下，可以使用clear() 方法清空栈。

通过 Pop 操作弹出项目

有时，需要沿栈向后回溯多个步骤。例如，返回应用程序中的“主”项或某种部分项。在这种情况下，可以将一个项作为pop() 的参数指定。这被称为“展开”操作，即栈会向下展开直至到达指定的项。如果未找到该项，堆栈将回溯直至只剩下一项，该项即成为currentItem 。若要显式回溯至堆栈底部，建议使用pop(null)，尽管任何不存在的项均可实现此目的。

在下面的动画中，我们通过调用pop(null) 将栈回溯到第一个元素：

栈中现在仅包含一个项：[A] 。

替换项

在下面的动画中，我们使用 `D` 将栈顶元素替换为 `replace `：

栈中现在包含以下元素：[A, B, D] 。

深度链接

深度链接是指将应用程序启动到特定状态。例如，可以启动一个报纸应用程序并直接显示某篇特定文章，而跳过栈顶项。就 StackView 而言，深度链接意味着能够修改栈的状态，甚至可以将一组项目压入栈顶，或将栈完全重置为给定状态。

StackView 中深度链接的 API 与基本导航相同。将数组而非单个项目压入栈，会将该数组中的所有项目添加到栈中。不过，过渡动画仅应用于数组中的最后一个项目。push() 的常规语义同样适用于深度链接，即它会将推入栈中的任何内容添加到栈中。

注意：仅 加载数组的最后一个项目。其余项目仅在需要时加载，即在后续调用 pop 时，或通过get() 请求获取项目时。

假设栈中内容为 [A, B, C]，则会得到以下结果：

push([D, E, F]) => [A, B, C, D, E, F] - C 与 F 之间的“压栈”过渡动画
replace([D, E, F]) => [A, B, D, E, F] - C 与 F 之间的“替换”过渡动画
clear() 随后调用push([D, E, F]) => [D, E, F] — 由于栈为空，因此不显示“入栈”过渡动画。

查找项目

对于应用程序没有引用项的项，可以通过调用find()来查找。该方法需要一个回调函数，该函数将针对栈中的每个项（从顶部开始）依次调用，直到找到匹配项为止。如果回调函数返回true ，则find()停止并返回匹配的项；否则返回null 。

下面的代码在栈中搜索名为“order_id”的项，并向下展开至该项。

stackView.pop(stackView.find(function(item) {
    return item.name == "order_id";
}));

您还可以使用get(index) 访问栈中的某个项。

previousItem = stackView.get(myItem.StackView.index - 1));

过渡效果

对于每次 push 或 pop 操作，系统都会对进入和退出的项应用不同的过渡动画。这些动画定义了进入项应如何动画进入，以及退出项应如何动画退出。可以通过为 StackView 的pushEnter 、pushExit 、popEnter 、popExit 、replaceEnter 和replaceExit 属性分配不同的Transitions 来定制这些动画。

注意： 过渡动画会相互影响彼此的过渡行为。仅自定义其中一个动画而忽略另一个，可能会导致出乎意料的结果。

以下代码片段定义了用于 push 和 pop 操作的简单淡入淡出过渡效果：

StackView {
    id: stackview
    anchors.fill: parent

    pushEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    pushExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
    popEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    popExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
}

注意： 不支持在添加到 StackView 的项目上使用锚点。通常，“推入”、“弹出”和“替换”过渡会动画化位置，而应用锚点时无法实现这一点。请注意，这仅适用于项目的根节点。对其子节点使用锚点则可按预期工作。

项目所有权

StackView 仅对其自行创建的项拥有所有权。这意味着，任何推入 StackView 的项都不会被 StackView 销毁；只有 StackView 通过 `Components ` 或 `URLs ` 创建的项才会被 StackView 销毁。为说明这一点，下例中的消息仅会在 StackView 被销毁时输出，而不会在项从栈中弹出时输出：

Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: Item {
        Component.onDestruction: print("Destroying initial item")
    }

    Component.onCompleted: push(itemComponent.createObject(window))
}

然而，在下面的示例中，通过 URL 和 Component 创建的两个项目，在从 StackView 中弹出时都会被 StackView 销毁：

Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: "Item1.qml"

    Component.onCompleted: push(itemComponent)
}

大小

StackView 不会从压入其中的项中继承隐式大小。这意味着，例如将其用作Dialog 的contentItem 时，结果将不会如预期那样：

Dialog {
    StackView {
        initialItem: Rectangle {
            width: 200
            height: 200
            color: "salmon"
        }
    }
}

在这种情况下，有几种方法可以确保 StackView 具有大小：

在 StackView 本身上设置implicitWidth 和implicitHeight 。
在Rectangle 上设置implicitWidth 和implicitHeight 。
在对话框（Dialog）上设置contentWidth 和contentHeight 。
为 Dialog 指定大小。

另请参阅 《Qt Quick Controls 》中的 “自定义 StackView”、“使用 StackView 导航”、“导航控件”、“容器控件”和“焦点管理”。

属性文档

busy : bool `[read-only]`

该属性用于表示过渡是否正在运行。

currentItem : Item `[read-only]`

该属性保存栈中当前的顶层元素。

depth : int `[read-only]`

该属性存储当前压入栈中的元素个数。

empty : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

该属性表示栈是否为空。

该属性在 QtQuick.Controls 2.3（Qt 5.10）中引入。

另请参阅 depth 。

initialItem : var

该属性存储在创建StackView 时应显示的初始项目。初始项目可以是Item 、Component 或url 。指定初始项目等同于：

Component.onCompleted: stackView.push(myInitialItem)

另请参阅 push()。

popEnter : Transition

该属性存储了当从堆栈中弹出另一个项目时，应用于进入该堆栈的项目的过渡效果。

另请参阅 “自定义 StackView”。

popExit : Transition

该属性用于存储在项目从堆栈中弹出时，应用于该项目的过渡效果。

另请参阅 “自定义 StackView”。

pushEnter : Transition

该属性存储了在将项目压入堆栈时，应用于进入堆栈的该项目的过渡效果。

另请参阅 “自定义 StackView”。

pushExit : Transition

该属性存储了当另一个项目被压入栈中时，应用于从栈中弹出的项目的过渡效果。

另请参阅 “自定义 StackView”。

replaceEnter : Transition

该属性存储了当某个项目替换另一个项目并进入堆栈时，应用于该项目的过渡效果。

另请参阅 “自定义 StackView”。

replaceExit : Transition

该属性存储了当项目被另一个项目替换并退出堆栈时，应用于该项目的过渡效果。

另请参阅 “自定义 StackView”。

附加属性文档

StackView.index : int `[read-only attached]`

该附加属性保存其所附属项的堆栈索引；如果该项不在堆栈中，则保存-1 。

StackView.status : enumeration `[read-only attached]`

此附加属性保存其所附加项的堆栈状态；如果该项不在堆栈中，则保存为StackView.Inactive 。

可用值：

常量	描述
`StackView.Inactive`	该项目处于非活动状态（或未处于堆栈中）。
`StackView.Deactivating`	该项正在被停用（从堆栈中弹出）。
`StackView.Activating`	该项正在被激活（成为当前项）。
`StackView.Active`	该项处于活动状态，即当前项。

StackView.view : StackView `[read-only attached]`

该附加属性保存其所附加项的堆栈视图，如果该项不在堆栈中，则保存null 。

StackView.visible : bool `[attached, since QtQuick.Controls 2.2 (Qt 5.9)]`

此附加属性保留其所附加项的可见性。其值遵循Item::visible 的值。

默认情况下，当“进入”过渡开始时，StackView 会显示新进入的项目；当“退出”过渡结束时，则隐藏即将离开的项目。显式设置此属性可覆盖默认行为，从而使位于最顶层项目下方的项目保持可见。

注意： 大多数样式的默认过渡效果会 将退出项滑出视图范围，并可能对其不透明度进行动画处理。为了保持整个项目栈可见，请考虑自定义 `transitions `，以便底层项目能够被看到。

显示可见性行为的堆栈视图

StackView {
    id: stackView
    property real offset: 10
    width: 100; height: 100

    initialItem: Component {
        id: page
        Rectangle {
            property real pos: StackView.index * stackView.offset
            property real hue: Math.random()
            color: Qt.hsla(hue, 0.5, 0.8, 0.6)
            border.color: Qt.hsla(hue, 0.5, 0.5, 0.9)
            StackView.visible: true
        }
    }

    pushEnter: Transition {
        id: pushEnter
        ParallelAnimation {
            PropertyAction { property: "x"; value: pushEnter.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: pushEnter.ViewTransition.item.pos + stackView.offset; to: pushEnter.ViewTransition.item.pos; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 400; easing.type: Easing.OutCubic }
        }
    }
    popExit: Transition {
        id: popExit
        ParallelAnimation {
            PropertyAction { property: "x"; value: popExit.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: popExit.ViewTransition.item.pos; to: popExit.ViewTransition.item.pos + stackView.offset; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 1; to: 0; duration: 400; easing.type: Easing.OutCubic }
        }
    }

    pushExit: Transition {
        id: pushExit
        PropertyAction { property: "x"; value: pushExit.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: pushExit.ViewTransition.item.pos }
    }
    popEnter: Transition {
        id: popEnter
        PropertyAction { property: "x"; value: popEnter.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: popEnter.ViewTransition.item.pos }
    }
}

该属性在 QtQuick.Controls 2.2（Qt 5.9）中引入。

附带的信号文档

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` activated()

当该信号所关联的项目在堆栈中被激活时，会触发此附加信号。

注意： 对应的处理函数 为onActivated 。

该信号于 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 status 。

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` activating()

当所附加的项目正在栈中被激活时，会触发此附加信号。

注意： 相应的处理函数是onActivating 。

该信号在 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 status 。

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` deactivated()

当该信号被附加的项目在堆栈中被停用时，会触发此附加信号。

注意： 相应的处理程序 为onDeactivated 。

该信号于 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 status 。

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` deactivating()

当所附加的项正在栈中被失效时，会触发此附加信号。

注意： 相应的处理程序 为onDeactivating 。

该信号于 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 status 。

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` removed()

当该信号所关联的项从栈中移除时，会触发此附加信号。它可用于安全地销毁被压入栈中的项，例如：

Item {
    StackView.onRemoved: destroy() // Will be destroyed sometime after this call.
}

注意： 对应的处理程序 是onRemoved 。

该信号在 QtQuick.Controls 2.1（Qt 5.8）中引入。

另请参阅 status 。

方法文档

void clear(transition)

从栈中移除所有项目。

只有由StackView 自行创建（源自Component 或url ）的项在弹出时才会被销毁。更多信息请参见Item Ownership 。

自QtQuick.Controls 2.3 起，可选地指定transition 。支持的转换：

常量	描述
`StackView.Immediate`	立即清除栈，不执行任何过渡（默认）。
`StackView.PushTransition`	使用“push”过渡清空栈。
`StackView.ReplaceTransition`	使用“replace”过渡清除栈。
`StackView.PopTransition`	使用“弹出”过渡效果清空堆栈。

Item find(callback, behavior)

在栈中搜索特定元素。系统会针对栈中的每个元素调用callback 函数（将元素和索引作为参数传入），直到回调函数返回true 。返回值即为找到的元素。例如：

stackView.find(function(item, index) {
    return item.isTheOne
})

behavior 支持的值：

常量	描述
`StackView.DontLoad`	跳过未加载的项目（不针对这些项目调用回调函数）。
`StackView.ForceLoad`	强制加载未加载的项目。

Item get(index, behavior)

返回栈中位置为index 的元素；如果索引超出范围，则返回null 。

支持的behavior 值：

常量	描述
`StackView.DontLoad`	该项目不会被强制加载（如果尚未加载，则返回`null` ）。
`StackView.ForceLoad`	强制加载该项。

Item pop(item, operation)

从栈中弹出一个或多个元素。返回从栈中弹出的最后一个元素。

如果指定了item 参数，则会弹出所有元素，直到（但不包括）item 为止。如果item 为null ，则会弹出所有元素，直到（但不包括）第一个元素为止。如果未指定，则仅弹出当前元素。

注意： 对深度为 1 或 0 的栈执行 pop() 操作不会产生任何效果。在这种情况下，可以使用clear() 方法清空栈。

只有由 `StackView ` 自身创建（来自 `Component ` 或 `url`）的元素在弹出时才会被销毁。更多信息请参见Item Ownership 。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“push”过渡的操作（自QtQuick.Controls 2.1 起）。
`StackView.ReplaceTransition`	包含“replace”过渡的操作（自QtQuick.Controls 2.1 起）。
`StackView.PopTransition`	包含“弹出”过渡的操作（自QtQuick.Controls 2.1 起）。

如果未提供操作，将使用PopTransition 。

示例：

stackView.pop()
stackView.pop(someItem, StackView.Immediate)
stackView.pop(StackView.Immediate)
stackView.pop(null)

注意：若 您正在编译 QML，请改用强类型函数popToItem 、popToIndex 或popCurrentItem 。

另请参阅 clear()、Popping Items 和Unwinding Items via Pop 。

`[since 6.7]` Item popCurrentItem(operation)

从栈中弹出currentItem 。返回从栈中弹出的最后一个元素；如果depth 为1 ，则返回null 。

只有由StackView 自身创建的项（来自Component 或url ）在弹出时才会被销毁。更多信息请参见Item Ownership 。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用PopTransition 。

此函数等同于popToIndex(stackView.currentIndex - 1) 。

该方法在 Qt 6.7 中引入。

另请参阅 clear()、Popping Items 和Unwinding Items via Pop 。

`[since 6.7]` Item popToIndex(index, operation)

将栈中所有元素弹出至index （不包括本身）。返回从栈中移除的最后一个元素。

如果 `index ` 超出范围，将发出警告并返回 `null `。

只有由StackView 自身创建（来自Component 或url ）的项在弹出时才会被销毁。更多信息请参阅Item Ownership 。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用PopTransition 。

stackView.popToIndex(stackView.depth - 2, StackView.Immediate)

该方法在 Qt 6.7 中引入。

另请参阅 clear()、Popping Items 以及Unwinding Items via Pop 。

`[since 6.7]` Item popToItem(item, operation)

将栈中所有元素弹出至item （不包括本身）。返回从栈中移除的最后一个元素。

如果 `item ` 为 `null`，则会发出警告并返回 `null `。

只有由StackView 自身创建（来自Component 或url ）的项在弹出时才会被销毁。更多信息请参阅Item Ownership 。

可选地，将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡的操作。

如果未提供操作，将使用“PopTransition ”。

stackView.popToItem(someItem, StackView.Immediate)

该方法在 Qt 6.7 中引入。

另请参阅 clear()、Popping Items 和Unwinding Items via Pop 。

Item push(item, properties, operation)

使用可选的operation 将一个item 压入栈中，并可选地对该项应用一组properties 。该项可以是Item 、Component 或url 。返回成为当前项的该项。

StackView 如果压入栈中的项是Component 或url ，则会自动创建一个实例，该实例将在从栈中弹出时被销毁。更多信息请参阅Item Ownership 。

可选的properties 参数指定了一个映射，用于为压入栈中的项设置初始属性值。对于动态创建的项，这些值会在创建最终完成之前应用。这比在创建后设置属性值更高效，特别是在定义大量属性值时，同时也允许在项创建之前（使用Qt.binding()) 设置属性绑定。

推送单个项：

stackView.push(rect)

// or with properties:
stackView.push(rect, {"color": "red"})

可以通过传递额外参数或以数组形式，同时推送多个项目。最后一个项目将成为当前项目。每个项目后面都可以跟一组要应用的属性。

传递可变数量的参数：

stackView.push(rect1, rect2, rect3)

// or with properties:
stackView.push(rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"})

插入项目数组：

stackView.push([rect1, rect2, rect3])

// or with properties:
stackView.push([rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"}])

可选地将operation 指定为最后一个参数。支持的操作：

常量	描述
`StackView.Immediate`	不包含过渡的即时操作。
`StackView.PushTransition`	包含“推送”过渡的操作（自QtQuick.Controls 2.1起）。
`StackView.ReplaceTransition`	包含“替换”过渡的操作（自QtQuick.Controls 2.1 起）。
`StackView.PopTransition`	包含弹出过渡的操作（自QtQuick.Controls 2.1 起）。

如果未提供操作，则当栈为空时将使用 `Immediate `，否则将使用 `PushTransition `。

注意： 栈中已存在的项目不会被压入。

注意：如果您正在 编译 QML，请改用强类型的pushItem 或pushItems 函数。

另请参阅 initialItem 和Pushing Items 。

`[since 6.7]` Item pushItem(item, properties, operation)

将一个item 压入栈中，可选地应用一组properties ，并使用可选的operation 。返回变为当前项（即最后一个项）的元素。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含转换的即时操作。
`StackView.PushTransition`	包含“压入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用PushTransition 。

要将多个项压入栈中，请使用pushItems()。

该方法在 Qt 6.7 中引入。

另请参阅 initialItem 和Pushing Items 。

`[since 6.7]` Item pushItem(component, properties, operation)

将一个component 压入栈中，可选地应用一组properties ，并使用可选的operation 。返回成为当前项（即最后一个项）的元素。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“压入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡的运算。

如果未提供操作，将使用PushTransition 。

要将多个项目压入栈中，请使用pushItems()。

该函数重载了 pushItem()。

该方法在 Qt 6.7 中引入。

另请参阅 initialItem 和Pushing Items 。

`[since 6.7]` Item pushItem(url, properties, operation)

将一个url 压入栈中，可选地应用一组properties ，并使用可选的operation 。返回成为当前项（即最后一个项）的元素。

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含转换的即时操作。
`StackView.PushTransition`	包含“压入”过渡的操作。
`StackView.ReplaceTransition`	包含“replace”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用PushTransition 。

要将多个项目压入栈中，请使用pushItems()。

该函数重载了 pushItem()。

该方法在 Qt 6.7 中引入。

另请参阅 initialItem 和Pushing Items 。

`[since 6.7]` Item pushItems(items, operation)

使用可选的operation 将items 推入栈中，并可选地对每个元素应用一组属性。items 是一个元素数组。每个元素可以是Item 、Component 或url ，其后可跟随一个可选的属性参数（见下文）。返回成为当前项的元素（即最后一个元素）。

StackView 如果压入栈中的元素是Component 或url ，则会自动创建一个实例，该实例将在从栈中弹出时被销毁。更多信息请参阅Item Ownership 。

可选的 properties 参数位于每个项之后，用于指定初始属性值的映射。对于动态创建的项目，这些值会在创建最终完成之前应用。这比在创建后设置属性值更高效，特别是在定义大量属性值时，同时也允许在项目创建之前（使用Qt.binding()) 设置属性绑定。

stackView.push([item, rectComponent, Qt.resolvedUrl("MyItem.qml")])

// With properties:
stackView.pushItems([
    item, { "color": "red" },
    rectComponent, { "color": "green" },
    Qt.resolvedUrl("MyItem.qml"), { "color": "blue" }
])

// With properties for only some items:
stackView.pushItems([
    item, { "color": "yellow" },
    rectComponent
])

operation 可作为最后一个参数可选指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含过渡效果的即时操作。
`StackView.PushTransition`	包含“push”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用 `PushTransition `。

要压入单个项，请使用相应的pushItem 函数：

pushItem(item, properties, operation)
pushItem(component, properties, operation)
pushItem(url, properties, operation)

注意： 栈中已存在的项不会被压入。

此方法于 Qt 6.7 中引入。

另请参阅 initialItem 、pushItem 以及Pushing Items 。

Item replace(target, item, properties, operation)

使用指定的item 和可选的operation 替换栈中的一项或多项元素，并可选地对该元素应用一组properties 。该元素可以是Item 、Component 或url 。返回成为当前元素的那个元素。

只有由StackView 自身创建的项（源自Component 或url ）在弹出时才会被销毁。更多信息请参阅Item Ownership 。

如果指定了target 参数，则会替换栈中所有项目直至target 项为止。如果target 的值为null ，则栈中的所有项目都会被替换。如果未指定，则仅替换栈顶项目。

StackView 如果替换项是Component 或url ，则会自动创建一个实例。可选的properties 参数指定了替换项的初始属性值映射。对于动态创建的项，这些值会在创建最终完成之前应用。这比在创建后设置属性值更高效，特别是在定义大量属性值时，同时还允许在项创建之前（使用Qt.binding()) 设置属性绑定。

替换顶部项目：

stackView.replace(rect)

// or with properties:
stackView.replace(rect, {"color": "red"})

可以通过将项目作为额外参数或数组传递，同时替换多个项目。每个项目后均可跟上一组要应用的属性。

传递可变数量的参数：

stackView.replace(rect1, rect2, rect3)

// or with properties:
stackView.replace(rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"})

替换项目数组：

stackView.replace([rect1, rect2, rect3])

// or with properties:
stackView.replace([rect1, {"color": "red"}, rect2, {"color": "green"}, rect3, {"color": "blue"}])

可选地将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含过渡的即时操作。
`StackView.PushTransition`	包含“推送”过渡的操作（自QtQuick.Controls 2.1起）。
`StackView.ReplaceTransition`	包含“替换”过渡的操作（自QtQuick.Controls 2.1 起）。
`StackView.PopTransition`	包含“弹出”过渡的操作（自QtQuick.Controls 2.1 起）。

如果未提供操作，当栈为空时将使用 `Immediate `，否则将使用 `ReplaceTransition `。

以下示例演示了如何在 replace() 中使用 push 和 pop 过渡。

StackView {
    id: stackView

    initialItem: Component {
        id: page

        Page {
            Row {
                spacing: 20
                anchors.centerIn: parent

                Button {
                    text: "<"
                    onClicked: stackView.replace(page, StackView.PopTransition)
                }
                Button {
                    text: ">"
                    onClicked: stackView.replace(page, StackView.PushTransition)
                }
            }
        }
    }
}

注意：如果您正在 编译 QML，请改用强类型的replaceCurrentItem 函数。

另请参阅 push() 和Replacing Items 。

`[since 6.7]` Item replaceCurrentItem(items, operation)

从栈中弹出currentItem ，并压入items 。如果指定了可选参数operation ，则将使用相应的转换。每个项后面可以跟一组可选属性，这些属性将应用于该项。返回成为当前项的项。

可选的 properties 参数位于每个项之后，用于指定初始属性值的映射。对于动态创建的项，这些值会在创建过程完成之前应用。这比在创建后设置属性值更高效，特别是在定义大量属性值时，同时也允许在项创建之前（使用Qt.binding()) 设置属性绑定。

只有由StackView 自身创建的项（源自Component 或url ）在弹出时才会被销毁。更多信息请参阅Item Ownership 。

operation 可选地作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“压入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡的操作。

如果未提供操作，将使用ReplaceTransition 。

stackView.replaceCurrentItem([item, rectComponent, Qt.resolvedUrl("MyItem.qml")])

// With properties:
stackView.replaceCurrentItem([
    item, { "color": "red" },
    rectComponent, { "color": "green" },
    Qt.resolvedUrl("MyItem.qml"), { "color": "blue" }
])

要压入单个项，请使用相应的重载：

replaceCurrentItem(item, properties, operation)
replaceCurrentItem(component, properties, operation)
replaceCurrentItem(url, properties, operation)

该方法在 Qt 6.7 中引入。

另请参阅 push() 和Replacing Items 。

`[since 6.7]` Item replaceCurrentItem(item, properties, operation)

从栈中弹出currentItem ，并压入item 。如果指定了可选参数operation ，则将使用相应的过渡效果。如果指定了可选参数properties ，则将这些属性应用于该项。返回成为当前项的该项。

只有由StackView 自身创建的项（源自Component 或url ）在弹出时才会被销毁。更多信息请参阅Item Ownership 。

可选地，将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的即时操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“replace”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用 `ReplaceTransition `。

要将多个项目压入栈中，请使用replaceCurrentItem(items, operation)。

此函数重载了 replaceCurrentItem()。

该方法在 Qt 6.7 中引入。

另请参阅 Replacing Items 。

`[since 6.7]` Item replaceCurrentItem(component, properties, operation)

从栈中弹出currentItem ，并压入component 。如果指定了可选参数operation ，则将使用相应的过渡效果。如果指定了可选参数properties ，则将它们应用于该项。返回成为当前项的项。

只有由StackView 自身创建（基于Component 或url ）的项在弹出时才会被销毁。更多信息请参见Item Ownership 。

可选地，将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含转换的即时操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用 `ReplaceTransition `。

要将多个项目压入栈中，请使用replaceCurrentItem(items, operation)。

此函数重载了 replaceCurrentItem()。

该方法在 Qt 6.7 中引入。

另请参阅 Replacing Items 。

`[since 6.7]` Item replaceCurrentItem(url, properties, operation)

从栈中弹出currentItem ，并将url 压入栈中。如果指定了可选参数operation ，则将使用相应的过渡。如果指定了可选参数properties ，则将这些属性应用于该项。返回成为当前项的该项。

只有由StackView 自身创建的项（源自Component 或url ）在弹出时才会被销毁。更多信息请参阅Item Ownership 。

可选地，将operation 作为最后一个参数指定。支持的操作：

常量	描述
`StackView.Immediate`	不包含状态转换的立即操作。
`StackView.PushTransition`	包含“推入”过渡的操作。
`StackView.ReplaceTransition`	包含“替换”过渡的操作。
`StackView.PopTransition`	包含“弹出”过渡效果的操作。

如果未提供操作，将使用 `ReplaceTransition `。

要将多个项目压入栈中，请使用replaceCurrentItem(items, operation)。

此函数重载了 replaceCurrentItem()。

该方法在 Qt 6.7 中引入。

另请参阅 Replacing Items 。

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

StackView QML Type

属性

关联属性

附加信号

方法

详细说明

在应用程序中使用 StackView

基本导航

添加项目

弹出项目

通过 Pop 操作弹出项目

替换项

深度链接

查找项目

过渡效果

项目所有权

大小

属性文档

busy : bool [read-only]

currentItem : Item [read-only]

depth : int [read-only]

empty : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

initialItem : var

popEnter : Transition

popExit : Transition

pushEnter : Transition

pushExit : Transition

replaceEnter : Transition

replaceExit : Transition

附加属性文档

StackView.index : int [read-only attached]

StackView.status : enumeration [read-only attached]

StackView.view : StackView [read-only attached]

StackView.visible : bool [attached, since QtQuick.Controls 2.2 (Qt 5.9)]

附带的信号文档

[attached, since QtQuick.Controls 2.1 (Qt 5.8)] activated()

[attached, since QtQuick.Controls 2.1 (Qt 5.8)] activating()

[attached, since QtQuick.Controls 2.1 (Qt 5.8)] deactivated()

[attached, since QtQuick.Controls 2.1 (Qt 5.8)] deactivating()

[attached, since QtQuick.Controls 2.1 (Qt 5.8)] removed()

方法文档

void clear(transition)

Item find(callback, behavior)

Item get(index, behavior)

Item pop(item, operation)

[since 6.7] Item popCurrentItem(operation)

[since 6.7] Item popToIndex(index, operation)

[since 6.7] Item popToItem(item, operation)

Item push(item, properties, operation)

[since 6.7] Item pushItem(item, properties, operation)

[since 6.7] Item pushItem(component, properties, operation)

[since 6.7] Item pushItem(url, properties, operation)

[since 6.7] Item pushItems(items, operation)

Item replace(target, item, properties, operation)

[since 6.7] Item replaceCurrentItem(items, operation)

[since 6.7] Item replaceCurrentItem(item, properties, operation)

[since 6.7] Item replaceCurrentItem(component, properties, operation)

[since 6.7] Item replaceCurrentItem(url, properties, operation)

busy : bool `[read-only]`

currentItem : Item `[read-only]`

depth : int `[read-only]`

empty : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

StackView.index : int `[read-only attached]`

StackView.status : enumeration `[read-only attached]`

StackView.view : StackView `[read-only attached]`

StackView.visible : bool `[attached, since QtQuick.Controls 2.2 (Qt 5.9)]`

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` activated()

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` activating()

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` deactivated()

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` deactivating()

`[attached, since QtQuick.Controls 2.1 (Qt 5.8)]` removed()

`[since 6.7]` Item popCurrentItem(operation)

`[since 6.7]` Item popToIndex(index, operation)

`[since 6.7]` Item popToItem(item, operation)

`[since 6.7]` Item pushItem(item, properties, operation)

`[since 6.7]` Item pushItem(component, properties, operation)

`[since 6.7]` Item pushItem(url, properties, operation)

`[since 6.7]` Item pushItems(items, operation)

`[since 6.7]` Item replaceCurrentItem(items, operation)

`[since 6.7]` Item replaceCurrentItem(item, properties, operation)

`[since 6.7]` Item replaceCurrentItem(component, properties, operation)

`[since 6.7]` Item replaceCurrentItem(url, properties, operation)