Тип 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(). Это называется операцией «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() с последующим 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 на Rectangle.
• Установите contentWidth и contentHeight на Dialog.
• Установите размер Dialog.

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

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

activated()

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

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

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

См. также status.

activating()

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

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

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

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

deactivated()

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

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

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

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

deactivating()

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

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

Этот сигнал был введён в 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. Поддерживаемые переходы:

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

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

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

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

Примеры:

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

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

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

Item replace(target, item, properties, operation)

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

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

Если аргумент target указан, все элементы до item будут заменены. Если 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"}])

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

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