Тип QML StackView

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

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

Свойства

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

Базовая навигация

StackView поддерживает три основных операции навигации: push(), pop() и replace(). Они соответствуют классическим операциям стека, где «push» добавляет элемент в верхнюю часть стека, «pop» удаляет верхний элемент из стека, а «replace» — это как pop, за которым следует push, что заменяет самый верхний элемент новым элементом. Самый верхний элемент в стеке соответствует элементу, который в данный момент виден на экране. Логически, «push» навигирует вперёд или глубже в UI приложения, «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(). Метод требует функции обратного вызова, которая вызывается для каждого элемента в стеке (начиная с верхнего) до тех пор, пока не будет найдено совпадение. Если функция обратного вызова возвращает 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 {
    StackView {
        initialItem: Rectangle {
            width: 200
            height: 200
            color: "salmon"
        }
    }
}

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

• Установите implicitWidth и implicitHeight самого StackView.
• Установите implicitWidth и implicitHeight для прямоугольника.
• Установите contentWidth и contentHeight для диалога.
• Установите размер для диалога.

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

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

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

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

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

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

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

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

[только для чтения, начиная с QtQuick.Controls 2.3 (Qt 5.10)] 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.view : StackView

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

[начиная с QtQuick.Controls 2.2 (Qt 5.9)] 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).

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

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

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

Примечание: Соответствующий обработчик — onActivated.

Этот сигнал был введён в QtQuick.Controls 2.1 (Qt 5.8).

См. также status.

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

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

Примечание: Соответствующий обработчик — onActivating.

Этот сигнал был представлен в QtQuick.Controls 2.1 (Qt 5.8).

См. также статус.

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

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

Примечание: Соответствующий обработчик — onDeactivated.

Этот сигнал был представлен в QtQuick.Controls 2.1 (Qt 5.8).

См. также статус.

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

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

Примечание: Соответствующий обработчик — onDeactivating.

Этот сигнал был представлен в QtQuick.Controls 2.1 (Qt 5.8).

См. также статус.

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

См. также статус.

Документация по методам

void clear(transition)

Удаляет все элементы из стека.

Только элементы, которые StackView создал сам (из Component или url), будут уничтожены при извлечении. Дополнительную информацию см. в разделе Владение элементами.

Начиная с QtQuick.Controls 2.3, можно дополнительно указать transition. Поддерживаемые переходы:

Элемент find(callback, behavior)

Поиск конкретного элемента в стеке. Функция callback вызывается для каждого элемента в стеке (с элементом и индексом в качестве аргументов), пока функция callback не вернёт true. Возвращаемое значение — найденный элемент. Например:

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

Поддерживаемые значения behavior:

Элемент get(index, behavior)

Возвращает элемент в позиции index в стеке или null если индекс вне диапазона.

Поддерживаемые значения behavior:

Элемент pop(item, operation)

Извлекает один или несколько элементов из стека. Возвращает последний удалённый элемент из стека.

Если аргумент item указан, все элементы до (но не включая) item будут извлечены. Если item — null, все элементы до (но не включая) первого элемента будут извлечены. Если не указано, извлекается только текущий элемент.

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

Только элементы, которые StackView создал сам (из Component или url), будут уничтожены при извлечении. Дополнительную информацию см. в разделе Владение элементами.

operation может быть дополнительно указан в качестве последнего аргумента. Поддерживаемые операции:

Если операция не указана, будет использовано значение PopTransition.

Примеры:

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

См. также clear(), Извлечение элементов и Извлечение элементов через Pop.

Элемент push(item, properties, operation)

Помещает элемент item в стек с использованием необязательной operation и необязательного набора свойств properties. Элемент может быть Item, Component или url. Возвращает элемент, ставший текущим.

StackView автоматически создаёт экземпляр, если в качестве элемента используется Component или url, и экземпляр будет уничтожен при извлечении из стека. Дополнительную информацию см. в разделе Владение элементами.

Необязательный аргумент 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 может быть дополнительно указан в качестве последнего аргумента. Поддерживаемые операции:

Если операция не указана, будет использовано значение PushTransition.

Примечание: Элементы, которые уже существуют в стеке, не помещаются.

См. также initialItem и Помещение элементов.

Элемент replace(target, item, properties, operation)

Заменяет один или несколько элементов в стеке указанным элементом item и необязательной operation, и необязательно применяет набор свойств properties к элементу. Элемент может быть Item, Component или url. Возвращает элемент, ставший текущим.

Только элементы, которые StackView создал сам (из Component или url), будут уничтожены при извлечении. Дополнительную информацию см. в разделе Владение элементами.

Если аргумент target указан, все элементы до указанного будут заменены. Если target — null, все элементы в стеке будут заменены. Если не указано, заменится только верхний элемент.

StackView создаёт экземпляр автоматически, если заменяемый элемент является компонентом или 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"}])

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

Если операция не указана, будет использоваться ReplaceTransition.

Следующий пример иллюстрирует использование переходов push и pop с replace().

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

См. также push() и Замена элементов.