Тип 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

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

[только для чтения, начиная с QtQuick.Controls 2.3 (Qt 5.10)] empty : bool

Это свойство указывает, пуст ли стек.

Это свойство было добавлено в QtQuick.Controls 2.3 (Qt 5.10).

См. также depth.

initialItem : var

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

См. также состояние.

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