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

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

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

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

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

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

См. также status.

activating()

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

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

См. также status.

deactivated()

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

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

См. также status.

deactivating()

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

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

См. также status.

removed()

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

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

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

См. также status.

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

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

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

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

Примеры:

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

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

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

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

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

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

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

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

Заменяет один или несколько элементов в стеке указанным элементом и операцией, и необязательно применяет набор свойств к элементу. Элемент может быть элементом, компонентом или 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"}])

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

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