Тип 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" перемещает навигацию вперед или глубже в пользовательский интерфейс приложения, "pop" — назад, а "replace" заменяет currentItem.

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

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

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

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

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

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

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

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

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

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

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

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

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

Глубокая ссылка

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

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

Это дает нам следующий результат, учитывая стек [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(индекс).

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

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

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

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

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

См. также status.

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

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

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

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

См. также status.

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

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

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

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

См. также status.

[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), будут уничтожены при извлечении. См. Владение элементами для получения дополнительной информации.

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

Item find(callback, behavior)

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

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

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

Item get(index, behavior)

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

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

Item pop(item, operation)

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

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

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

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

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

Примеры:

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

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

Item 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 и Помещение элементов.

Item replace(target, item, properties, operation)

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

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

Если аргумент 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"}])

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

Если операция не указана, будет использоваться 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() и Замена элементов.