Тип QML StackView

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

Заявление об импорте:	import QtQuick.Controls 2.4
С момента:	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() followed by 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 применяются различные анимации перехода для входящих и выходящих элементов. Эти анимации определяют, как входящий элемент должен анимироваться, и как выходящий элемент должен анимироваться. Анимации можно настроить, назначив разные 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 или 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 при извлечении из стека:

Component {
    id: itemComponent

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

StackView {
    initialItem: "Item1.qml"

    Component.onCompleted: push(itemComponent)
}

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

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

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

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