Тип 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(). Это называется операцией «unwind», где стек разворачивается до указанного элемента. Если элемент не найден, стек разворачивается до тех пор, пока не останется один элемент, который становится 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() за которым следует push([D, E, F]) => [D, E, F] - анимация перехода для добавления элементов отсутствует, так как стек был пустым.

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

Элемент, для которого у приложения нет ссылки, можно найти, вызвав find(). Метод требует обратной функции-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 применяются разные анимации переходов для входящих и выходящих элементов. Эти анимации определяют, как должен анимироваться входящий элемент, и как должен анимироваться вывод выходящего элемента. Анимации можно настроить, назначив различные Переходы для свойств 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 из Компонентов или 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 и Компонента в следующем примере, будут уничтожены 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 : перечисление

Это присоединённое свойство содержит статус элемента в стеке, или 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()

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