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

Методы

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

Основная навигация

StackView поддерживает три основных операции навигации: push(), pop() и replace(). Они соответствуют классическим операциям стека, где "push" добавляет элемент в верхнюю часть стека, "pop" удаляет верхний элемент из стека, а "replace" похожа на pop, за которым следует push, которая заменяет самый верхний элемент новым элементом. Самый верхний элемент стека соответствует элементу, который текуще виден на экране. Логически, "push" перемещается вперед или глубже в пользовательский интерфейс приложения, "pop" перемещается назад, а "replace" заменяет currentItem.

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

Учитывая стек [A, B, C]:

• push(D) => [A, B, C, D] - анимация перехода "push" между C и D
• pop() => [A, B] - анимация перехода "pop" между C и B
• replace(D) => [A, B, D] - анимация перехода "replace" между C и D
• pop(A) => [A] - анимация перехода "pop" между C и A

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

Глубокое связывание

Глубокое связывание означает запуск приложения в определенном состоянии. Например, приложение газеты можно запустить, чтобы показать конкретную статью, минуя самый верхний элемент. С точки зрения 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 применяются различные анимации перехода к входящим и исходящим элементам. Эти анимации определяют, как входящий элемент должен анимироваться, и как выходящий элемент должен анимироваться. Анимации можно настроить, назначив различные 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 анимируют позицию, что невозможно, когда применяются якоря. Обратите внимание, что это относится только к корню элемента. Использование якорей для его дочерних элементов работает как ожидается.

Примечание: Типы в модуле Qt.labs не гарантируют сохранение совместимости в будущих версиях.

См. также Настройка StackView, Управление навигацией и Контейнерные элементы управления.

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

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

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

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

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

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

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

initialItem : var

Это свойство содержит начальный элемент, который должен быть показан при создании StackView. Начальный элемент может быть элементом, компонентом или URL. Указание начального элемента эквивалентно:

Component.onCompleted: stackView.push(myInitialItem)

См. также push().

popEnter : Переход

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

См. также Настройка StackView.

popExit : Переход

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

См. также Настройка StackView.

pushEnter : Переход

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

См. также Настройка StackView.

pushExit : Переход

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

См. также Настройка StackView.

replaceEnter : Переход

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

См. также Настройка StackView.

replaceExit : Переход

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

См. также Настройка StackView.

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

[только для чтения] StackView.index : int

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

[только для чтения] StackView.status : перечисление

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

Доступные значения:

[только для чтения] StackView.view : StackView

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

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

void clear()

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

Элемент find(callback, behavior)

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

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

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

Элемент get(index, behavior)

Возвращает элемент в позиции index в стеке или null если индекс выходит за пределы допустимых значений.

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

Элемент pop(item, operation)

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

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

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

Примеры:

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

См. также clear().

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

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

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

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)

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

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

Замена верхнего элемента:

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"}])

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

См. также push().