Тип QML StackView

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

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

Свойства

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

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

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

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

• void activated()
• void activating()
• void deactivated()
• void deactivating()
• void removed()

Методы

• void clear()
• 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» заменяет текущий элемент.

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

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

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

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

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

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

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

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

Развёртывание элементов с помощью Pop

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

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

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

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

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

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

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

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

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 , если элемент не находится в стеке.

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

Это свойство QML было введено в QtQuick.Controls 2.2 (Qt 5.9).

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

void activated()

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

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

См. также status.

void activating()

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

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

См. также status.

void deactivated()

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

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

См. также status.

void deactivating()

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

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

См. также status.

void removed()

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

Item {
    StackView.onRemoved: destroy() // Will be destroyed sometime after this call.
}

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

См. также status.

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

void clear()

Удаляет все элементы из стека. Анимации не применяются.

Item find(callback, behavior)

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

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

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

Элемент get(индекс, поведение)

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

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

Элемент pop(элемент, операция)

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

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

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

Примеры:

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

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

Элемент push(элемент, свойства, операция)

Добавляет элемент в стек, используя указанную операцию, и необязательно применяет набор свойств к элементу. Элемент может быть Элементом, Компонентом или url. Возвращает элемент, который стал текущим.

StackView автоматически создаёт экземпляр, если добавляемый элемент — Компонент или url. Необязательный аргумент свойства задаёт карту начальных значений свойств для добавленного элемента. Для динамически создаваемых элементов эти значения применяются до завершения создания. Это эффективнее, чем установка значений свойств после создания, особенно при большом количестве свойств, и также позволяет настроить привязки свойств (используя 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"}])

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

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

См. также initialItem и Добавление элементов.

Элемент replace(цель, элемент, свойства, операция)

Заменяет один или несколько элементов в стеке на указанный элемент и операцию, и необязательно применяет набор свойств к элементу. Элемент может быть Элементом, Компонентом или url. Возвращает элемент, который стал текущим.

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

StackView автоматически создаёт экземпляр, если заменяемый элемент — Компонент или url. Необязательный аргумент свойства задаёт карту начальных значений свойств для заменяемого элемента. Для динамически создаваемых элементов эти значения применяются до завершения создания. Это эффективнее, чем установка значений свойств после создания, особенно при большом количестве свойств, и также позволяет настроить привязки свойств (используя 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"}])

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

Следующий пример демонстрирует использование переходов 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() и Замена элементов.