Тип QML StackView

Предоставляет модель навигации на основе стека. Подробнее...

Заявление об импорте:	import QtQuick.Controls 2.5
С момента:	Qt 5.7
Наследует:	Control

Список всех членов, включая унаследованные

Свойства

busy : bool
currentItem : Item
depth : int
empty : bool
initialItem : var
popEnter : Transition
popExit : Transition
pushEnter : Transition
pushExit : Transition
replaceEnter : Transition
replaceExit : Transition

Присоединенные свойства

index : int
status : перечисление
view : StackView
visible : bool

Присоединенные сигналы

activated()
activating()
deactivated()
deactivating()
removed()

Методы

void clear(transition)
Item find(callback, behavior)
Item get(index, behavior)
Item pop(item, operation)
Item push(item, properties, operation)
Item replace(target, item, properties, operation)

Подробное описание

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 в приложении столь же просто, как добавление его в качестве дочернего элемента к окну. Стек обычно привязан к краям окна, за исключением верхней или нижней части, где он может быть привязан к строке состояния или другому аналогичному компоненту пользовательского интерфейса. Затем стек можно использовать, вызывая его методы навигации. Первый элемент, который отображается в StackView, — это элемент, который был назначен свойству initialItem, или самый верхний элемент, если свойство initialItem не задано.

StackView поддерживает три основных операции навигации: push(), pop() и replace(). Они соответствуют классическим операциям стека, где «push» добавляет элемент в верхнюю часть стека, «pop» удаляет верхний элемент из стека, а «replace» — это как pop, за которым следует push, что заменяет самый верхний элемент новым элементом. Самый верхний элемент в стеке соответствует элементу, который в данный момент отображается на экране. Логически «push» перемещает навигацию вперед или глубже в пользовательский интерфейс приложения, «pop» — назад, а «replace» — заменяет currentItem.

Добавление элементов

На следующей анимации три элемента Label помещаются в представление стека с помощью функции push():

Стек теперь содержит следующие элементы: [A, B, C].

Примечание: Когда стек пуст, операция push() не будет иметь анимации перехода, потому что нет элемента, от которого можно переходить (обычно при запуске приложения).

Удаление элементов

Продолжая пример выше, самый верхний элемент в стеке удаляется с помощью вызова pop():

Стек теперь содержит следующие элементы: [A, B].

Примечание: Операция pop() на стеке с глубиной 1 или 0 ничего не делает. В таких случаях стек можно очистить с помощью метода clear().

Разворачивание элементов через Pop

Иногда необходимо вернуться более чем на один шаг в стеке. Например, для возвращения к главному элементу или какому-либо разделу в приложении. В таких случаях можно указать элемент в качестве параметра для pop(). Это называется операцией «разворачивания», где стек разворачивается до тех пор, пока не останется указанный элемент. Если элемент не найден, стек разворачивается до тех пор, пока не останется один элемент, который становится currentItem. Чтобы явно развернуть стек до самого низа, рекомендуется использовать pop(null), хотя любой несуществующий элемент тоже подойдет.

На следующей анимации мы разворачиваем стек до первого элемента, вызвав pop(null):

Стек теперь содержит один элемент: [A].

Замена элементов

На следующей анимации мы заменяем самый верхний элемент на D:

Стек теперь содержит следующие элементы: [A, B, D].

Глубокое связывание

Глубокое связывание означает запуск приложения в определенном состоянии. Например, приложение газеты можно запустить, показав конкретную статью, минуя самый верхний элемент. С точки зрения StackView, глубокое связывание означает возможность изменить состояние стека настолько, что можно поместить набор элементов в верхнюю часть стека или полностью сбросить стек до заданного состояния.

API для глубокого связывания в StackView такое же, как и для основной навигации. Добавление массива вместо одного элемента добавляет все элементы этого массива в стек. Однако анимация перехода применяется только к последнему элементу массива. Обычные семантики push() применяются к глубокому связыванию, то есть добавляется то, что помещено в стек.

Примечание: Загружается только последний элемент массива. Остальные элементы загружаются только при необходимости, либо при последующих вызовах pop, либо по запросу получения элемента с помощью get().

Это даёт нам следующий результат, учитывая стек [A, B, C]:

push([D, E, F]) => [A, B, C, D, E, F] - Анимация перехода "push" между C и F
replace([D, E, F]) => [A, B, D, E, F] - Анимация перехода "replace" между C и F
clear() followed by push([D, E, F]) => [D, E, F] - Анимация перехода при добавлении элемента отсутствует, так как стек был пустым.

Поиск элементов

Элемент, для которого у приложения нет ссылки, может быть найден с помощью вызова find(). Метод требует обратной функции-callback, которая вызывается для каждого элемента в стеке (начиная с вершины) до тех пор, пока не будет найдено совпадение. Если callback возвращает 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 применяются различные анимации перехода для входящих и выходящих элементов. Эти анимации определяют, как должен анимироваться входящий элемент и как должен анимироваться вывод выходящего элемента. Анимации можно настроить, назначив различные Transition для свойств pushEnter, pushExit, popEnter, popExit, replaceEnter и replaceExit StackView.

Примечание: Анимации переходов влияют на поведение переходов друг друга. Настройка анимации для одного и оставление другой может привести к непредсказуемым результатам.

Следующий фрагмент кода определяет простую анимацию плавного перехода для операций 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, не поддерживается. Обычно переходы push, pop и replace анимируют положение, что невозможно при применении якорей. Обратите внимание, что это относится только к корню элемента. Использование якорей для его дочерних элементов работает как ожидается.

Владение элементами

StackView принимает на себя владение только теми элементами, которые он создаёт сам. Это означает, что любой элемент, помещённый в StackView, никогда не будет уничтожен StackView; только элементы, которые StackView создаёт из Components или URL, уничтожаются 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 при их удалении из стека:

Component {
    id: itemComponent

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

StackView {
    initialItem: "Item1.qml"

    Component.onCompleted: push(itemComponent)
}

Размер

StackView не наследует неявный размер от элементов, помещённых в него. Это означает, что использование его в качестве contentItem Dialog, например, не будет работать как ожидается:

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

Существует несколько способов обеспечения того, чтобы StackView имел размер в этой ситуации:

Установите implicitWidth и implicitHeight для самого StackView.
Установите implicitWidth и implicitHeight для Rectangle.
Установите contentWidth и contentHeight для Dialog.
Присвойте Dialog размер.

См. также Настройка StackView, Элементы управления навигацией, Элементы управления контейнерами и Управление фокусом в Qt Quick Controls 2.

Документация свойств

[только для чтения] busy : bool

Это свойство указывает, выполняется ли переход.

[только для чтения] currentItem : Item

Это свойство содержит текущий верхний элемент в стеке.

[только для чтения] depth : int

Это свойство содержит количество элементов, в настоящее время помещенных в стек.

[только для чтения] empty : bool

Это свойство указывает, пуст ли стек.

Это свойство было добавлено в 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

Это присоединённое свойство содержит индекс элемента в стеке, или -1 если элемент не находится в стеке.

[только для чтения] StackView.status : enumeration

Это присоединённое свойство содержит состояние элемента в стеке или StackView.Inactive если элемент не находится в стеке.

Доступные значения:

Константа	Описание
`StackView.Inactive`	Элемент неактивен (или не находится в стеке).
`StackView.Deactivating`	Элемент деактивируется (удаляется из стека).
`StackView.Activating`	Элемент активизируется (становится текущим элементом).
`StackView.Active`	Элемент активен, то есть текущий элемент.

[только для чтения] StackView.view : StackView

Это присоединённое свойство содержит представление стека элемента, или null если элемент не находится в стеке.

StackView.visible : bool

Это присоединённое свойство определяет видимость элемента, к которому оно прикреплено. Значение соответствует значению Item::visible.

По умолчанию, StackView отображает входящие элементы при начале перехода enter и скрывает исходящие элементы по завершении перехода exit. Явное задание этого свойства позволяет переопределить поведение по умолчанию, что дает возможность отображать элементы, находящиеся ниже самого верхнего.

Примечание: По умолчанию переходы большинства стилей сдвигают исходящие элементы за пределы области просмотра и, возможно, анимируют их непрозрачность. Чтобы отобразить весь стек элементов, следует настроить переходы таким образом, чтобы были видны элементы, находящиеся под ними.

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

Документация по присоединённым сигналам

activated()

Этот присоединённый сигнал испускается, когда элемент, к которому он присоединён, активируется в стеке.