Тип QML ListView

Обеспечивает представление списка элементов, предоставляемых моделью Подробнее...

Заявление импорта:	import QtQuick 2.7
Наследует:	Flickable

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

Свойства

add : Переход
addDisplaced : Переход
cacheBuffer : int
count : int
currentIndex : int
currentItem : Элемент
currentSection : строка
delegate : Компонент
displaced : Переход
displayMarginBeginning : int
displayMarginEnd : int
effectiveLayoutDirection : перечисление
footer : Компонент
footerItem : Элемент
footerPositioning : перечисление
header : Компонент
headerItem : Элемент
headerPositioning : перечисление
highlight : Компонент
highlightFollowsCurrentItem : bool
highlightItem : Элемент
highlightMoveDuration : int
highlightMoveVelocity : вещественное
highlightRangeMode : перечисление
highlightResizeDuration : int
highlightResizeVelocity : вещественное
keyNavigationEnabled : bool
keyNavigationWraps : bool
layoutDirection : перечисление
model : модель
move : Переход
moveDisplaced : Переход
orientation : перечисление
populate : Переход
preferredHighlightBegin : вещественное
preferredHighlightEnd : вещественное
remove : Переход
removeDisplaced : Переход
section
- section.property : строка
- section.criteria : перечисление
- section.delegate : Компонент
- section.labelPositioning : перечисление
snapMode : перечисление
spacing : вещественное
verticalLayoutDirection : перечисление

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

delayRemove : bool
isCurrentItem : bool
nextSection : строка
previousSection : строка
section : строка
view : ListView

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

add()
remove()

Методы

decrementCurrentIndex()
forceLayout()
incrementCurrentIndex()
int indexAt(вещественное x, вещественное y)
Элемент itemAt(вещественное x, вещественное y)
positionViewAtBeginning()
positionViewAtEnd()
positionViewAtIndex(int index, PositionMode mode)

Подробное описание

A ListView отображает данные из моделей, созданных на основе встроенных типов QML, таких как ListModel и XmlListModel, или пользовательских классов моделей, определённых на C++, которые наследуют от QAbstractItemModel или QAbstractListModel.

У ListView есть свойство model, которое определяет отображаемые данные, и свойство delegate, которое определяет, как должны отображаться данные. Элементы в ListView выстраиваются по горизонтали или вертикали. Представления списков по своей природе являются прокручиваемыми, поскольку ListView наследуется от Flickable.

Пример использования

Следующий пример демонстрирует определение простой модели списка, определённой в файле с именем ContactModel.qml:

import QtQuick 2.0

ListModel {
    ListElement {
        name: "Bill Smith"
        number: "555 3264"
    }
    ListElement {
        name: "John Brown"
        number: "555 8426"
    }
    ListElement {
        name: "Sam Wise"
        number: "555 0473"
    }
}

Другой компонент может отображать эти данные модели в ListView, как показано ниже:

import QtQuick 2.0

ListView {
    width: 180; height: 200

    model: ContactModel {}
    delegate: Text {
        text: name + ": " + number
    }
}

Здесь ListView создаёт компонент ContactModel для своей модели и элемент Text для своего делегата. Представление создаёт новый компонент Text для каждого элемента в модели. Обратите внимание, что делегат может напрямую обращаться к данным модели name и number.

Улучшенное представление списка показано ниже. Делегат визуально улучшен и переместился в отдельный компонент contactDelegate.

Rectangle {
    width: 180; height: 200

    Component {
        id: contactDelegate
        Item {
            width: 180; height: 40
            Column {
                Text { text: '<b>Name:</b> ' + name }
                Text { text: '<b>Number:</b> ' + number }
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

Выбранный в данный момент элемент выделяется синим прямоугольником Rectangle с помощью свойства highlight, и focus установлено в true, чтобы включить навигацию с помощью клавиатуры для представления списка. Само представление списка является областью фокуса (см. Фокус клавиатуры в Qt Quick для получения дополнительной информации).

Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Они добавляются к contentItem ListView, а не к самому представлению. Состояние никогда не должно храниться в делегате.

ListView присоединяет ряд свойств к корневому элементу делегата, например ListView.isCurrentItem. В следующем примере корневой элемент делегата может напрямую получить доступ к этому присоединённому свойству как ListView.isCurrentItem, в то время как объект-потомок contactInfo должен ссылаться на это свойство как wrapper.ListView.isCurrentItem.

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

Примечание: Представления не включают обрезку автоматически. Если представление не обрезается другим элементом или экраном, необходимо установить clip: true, чтобы красиво обрезать элементы, которые находятся вне области видимости.

Макеты ListView

Макет элементов в ListView можно контролировать с помощью этих свойств:

orientation - управляет тем, как элементы располагаются — по горизонтали или вертикали. Это значение может быть либо Qt.Horizontal, либо Qt.Vertical.
layoutDirection - управляет направлением горизонтального расположения элементов для горизонтально ориентированного представления: то есть, выстраиваются ли элементы слева направо или справа налево. Это значение может быть либо Qt.LeftToRight, либо Qt.RightToLeft.
verticalLayoutDirection - управляет направлением вертикального расположения элементов для вертикально ориентированного представления: то есть, выстраиваются ли элементы сверху вниз или снизу вверх. Это значение может быть либо ListView.TopToBottom, либо ListView.BottomToTop.

По умолчанию ListView имеет вертикальную ориентацию, и элементы выстраиваются сверху вниз. Таблица ниже показывает различные макеты, которые может иметь ListView, в зависимости от значений перечисленных выше свойств.

ListViews с ориентацией Qt.Vertical
Сверху вниз	Снизу вверх
ListViews с ориентацией Qt.Horizontal
Слева направо	Справа налево

Направление прокрутки

По умолчанию вертикальный ListView устанавливает flickableDirection в Flickable.Vertical, а горизонтальный ListView — в Flickable.Horizontal. Кроме того, вертикальный ListView рассчитывает (оценивает) только contentHeight, а горизонтальный ListView — только contentWidth. Другое измерение устанавливается в -1.

Начиная с Qt 5.9 (Qt Quick 2.9), можно создать ListView, который можно прокручивать в обоих направлениях. Для этого flickableDirection можно установить в Flickable.AutoFlickDirection или Flickable.AutoFlickIfNeeded, а необходимое значение contentWidth или contentHeight должно быть указано.

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

Порядок отображения элементов в ListView

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

Свойство	Значение Z по умолчанию
delegate	1
footer	1
header	1
highlight	0
section.delegate	2

Эти значения по умолчанию устанавливаются, если значение Z элемента равно 0, поэтому установка значения Z этих элементов на 0 не оказывает влияния. Обратите внимание, что значение Z имеет тип real, поэтому можно установить дробные значения, например, 0.1.

См. также QML Data Models, GridView, PathView и Qt Quick Examples - Views.

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

add : Transition

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

Например, вот представление, которое задаёт такой переход:

ListView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

Всякий раз, когда элемент добавляется в указанное выше представление, элемент будет анимироваться из позиции (100,100) в его конечную позицию x,y внутри представления в течение одной секунды. Переход применяется только к новым элементам, добавляемым в представление; он не применяется к элементам, смещаемым добавлением новых элементов. Для анимации смещаемых элементов установите свойства displaced или addDisplaced.

Дополнительные сведения и примеры использования переходов представлений см. в документации ViewTransition.

Примечание: Этот переход не применяется к элементам, созданным при первоначальной загрузке представления или при изменении модели представления model. (В этих случаях применяется переход populate.) Кроме того, этот переход не должен анимировать высоту нового элемента; это приведёт к неверному расположению элементов, находящихся под новым элементом. Вместо этого высоту можно анимировать в обработчике onAdd в делегате.

См. также addDisplaced, populate и ViewTransition.

addDisplaced : Transition

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

Например, вот представление, которое задаёт такой переход:

ListView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Всякий раз, когда элемент добавляется в указанное выше представление, все элементы под новым элементом смещаются, в результате чего они перемещаются вниз (или вбок, если ориентация горизонтальная) в представлении. При этом перемещении движение элементов к их новым позициям x,y в представлении будет анимироваться с помощью NumberAnimation в течение одной секунды, как указано. Этот переход не применяется к новому элементу, который был добавлен в представление; для анимации добавленных элементов установите свойство add.

Если элемент смещается несколькими типами операций одновременно, не определено, будет ли применён переход addDisplaced, moveDisplaced или removeDisplaced. Кроме того, если не нужно указывать различные переходы в зависимости от того, смещается ли элемент при добавлении, перемещении или удалении, можно установить свойство displaced вместо этого.

Дополнительные сведения и примеры использования переходов представлений см. в документации ViewTransition.

Примечание: Этот переход не применяется к элементам, созданным при первоначальной загрузке представления или при изменении модели представления model. В этих случаях применяется переход populate.

См. также displaced, add, populate и ViewTransition.

cacheBuffer : int

Это свойство определяет, сохраняются ли делегаты за пределами видимой области представления.

Если это значение больше нуля, представление может сохранять столько делегатов, сколько может поместиться в заданном буфере. Например, если в вертикальном представлении высота делегата составляет 20 пикселей, а cacheBuffer установлено в 40, то может быть создано/сохранено до 2 делегатов над видимой областью и 2 делегата под ней. Делегаты в буфере создаются асинхронно, позволяя создание происходить на нескольких кадрах и уменьшая вероятность пропусков кадров. Для повышения производительности отрисовки делегаты за пределами видимой области не отрисовываются.

Значение этого свойства по умолчанию зависит от платформы, но обычно будет больше нуля. Отрицательные значения игнорируются.

Обратите внимание, что cacheBuffer — это не буфер пикселей; он просто сохраняет дополнительные созданные делегаты.

Примечание: Установка этого свойства не является заменой для создания эффективных делегатов. Оно может улучшить плавность прокрутки за счёт дополнительного использования памяти. Чем меньше объектов и связей в делегате, тем быстрее можно прокручивать представление. Важно понимать, что установка cacheBuffer лишь отсрочит проблемы, вызванные медленной загрузкой делегатов; это не решение для этой ситуации.

cacheBuffer работает за пределами любых отступов отображения, заданных с помощью displayMarginBeginning или displayMarginEnd.

count : int

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

currentIndex : int

Свойство currentIndex содержит индекс текущего элемента, а currentItem содержит сам текущий элемент. Установка currentIndex в -1 очистит выделение и установит currentItem в null.

Если highlightFollowsCurrentItem равно true, установка любого из этих свойств плавно прокрутит ListView таким образом, чтобы текущий элемент стал видимым.

Обратите внимание, что положение текущего элемента может быть лишь приблизительным, пока он не станет видимым в представлении.

currentItem : Item

Если highlightFollowsCurrentItem равно true, установка любого из этих свойств плавно прокрутит ListView так, чтобы текущий элемент стал видимым.

Обратите внимание, что положение текущего элемента может быть приблизительным до тех пор, пока он не станет видимым в представлении.

currentSection : string

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

delegate : Component

Делегат предоставляет шаблон, определяющий каждый элемент, создаваемый представлением. Индекс представлен как доступное index свойство. Свойства модели также доступны в зависимости от типа модели данных.

Количество объектов и связей в делегате напрямую влияет на производительность перелистывания представления. Если это возможно, поместите функциональность, которая не требуется для обычного отображения делегата, в Loader, который может загружать дополнительные компоненты по мере необходимости.

ListView будет выводить элементы на основе размера корневого элемента в делегате.

Рекомендуется, чтобы размер делегата был целым числом, чтобы избежать выравнивания элементов с дробными частями пикселей.

По умолчанию порядок следования экземпляров делегатов в стеке равен 1.

Примечание: Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Они являются дочерними элементами ListView's contentItem, а не самого представления. Состояние никогда не должно храниться в делегате.

См. также Порядок следования в ListView.

displaced : Transition

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

Это удобный способ указать универсальную анимацию, которая будет применяться ко всем элементам, смещенным в результате добавления, перемещения или удаления, без необходимости указывать отдельные свойства addDisplaced, moveDisplaced и removeDisplaced. Например, вот представление, которое задаёт анимацию смещения:

ListView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Когда любой элемент добавляется, перемещается или удаляется в представлении выше, элементы ниже смещаются, перемещаясь вниз (или вбок, если ориентация горизонтальная) в пределах представления. Во время этого смещения перемещение элементов в новые позиции x,y в представлении будет анимировано с помощью NumberAnimation в течение одной секунды, как указано.

Если представление задает эту общую анимацию смещения, а также конкретные addDisplaced, moveDisplaced или removeDisplaced анимации, то при соответствующей операции будет использоваться более конкретная анимация вместо общей анимации смещения, при условии, что более конкретная анимация не отключена (путем установки enabled в false). Если она действительно отключена, применяется общая анимация смещения.

Более подробную информацию и примеры использования анимаций представлений см. в документации ViewTransition.

См. также addDisplaced, moveDisplaced, removeDisplaced и ViewTransition.

displayMarginBeginning : int

Это свойство позволяет отображать делегаты за пределами геометрии представления.

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

Например, если в вертикальном представлении делегат имеет высоту 20 пикселей, и displayMarginBeginning и displayMarginEnd оба установлены в 40, тогда будут созданы и показаны 2 делегата выше и 2 делегата ниже.

Значение по умолчанию равно 0.

Это свойство предназначено для настройки определенных UI-конфигураций, а не для повышения производительности. Если вы хотите создать делегаты за пределами геометрии представления для повышения производительности, вам, вероятно, следует использовать свойство cacheBuffer вместо этого.

Это свойство QML было добавлено в QtQuick 2.3.

displayMarginEnd : int

Это свойство позволяет отображать делегаты за пределами геометрии представления.

Значение по умолчанию равно 0.

Это свойство QML было добавлено в QtQuick 2.3.

effectiveLayoutDirection : enumeration

Это свойство содержит эффективное направление вывода для горизонтально ориентированного списка.

При использовании присоединённого свойства LayoutMirroring::enabled для локальных макетов, визуальное направление вывода горизонтального списка будет зеркальным. Однако свойство layoutDirection останется неизменным.

См. также ListView::layoutDirection и LayoutMirroring.

Это свойство содержит компонент, используемый в качестве подвала.

Экземпляр компонента подвала создаётся для каждого представления. Подвал размещается в конце представления, после всех элементов. По умолчанию порядок следования в стеке подвала равен 1.

См. также header, footerItem и Порядок следования в ListView.

footerItem : Item

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

См. также footer, headerItem и Порядок следования в ListView.

footerPositioning : enumeration

Это свойство определяет позиционирование элемента подвала footer item.

Возможные значения:

ListView.InlineFooter (по умолчанию) - подвал расположен в конце содержимого и перемещается вместе с содержимым как обычный элемент.
ListView.OverlayFooter - подвал размещается в конце представления.
ListView.PullBackFooter - подвал размещается в конце представления. Подвал может быть отодвинут путём перемещения содержимого назад, и возвращён путём перемещения содержимого вперёд.

Примечание: Это свойство не влияет на порядок следования в стеке подвала. Например, если подвал должен отображаться над элементами делегата delegate при использовании ListView.OverlayFooter, его значение Z должно быть установлено на значение, большее, чем у делегатов. Дополнительная информация представлена в Порядке следования в ListView.

Это свойство QML было добавлено в Qt 5.4.

header : Component

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

Экземпляр компонента заголовка создаётся для каждого представления. Заголовок размещается в начале представления, перед всеми элементами. По умолчанию порядок следования в стеке заголовка равен 1.

См. также footer, headerItem и Порядок следования в ListView.

headerItem : Item

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

См. также header, footerItem и Порядок следования в ListView.

headerPositioning : enumeration

Это свойство определяет позиционирование элемента заголовка header item.

Возможные значения:

Список элементов.InlineHeader (по умолчанию) - заголовок размещается в начале содержимого и перемещается вместе с содержимым, как обычный элемент.
Список элементов.OverlayHeader - заголовок размещается в начале представления.
Список элементов.PullBackHeader - заголовок размещается в начале представления. Заголовок можно отодвинуть, переместив содержимое вперед, и вернуть назад, переместив содержимое назад.

Примечание: Это свойство не влияет на порядок наложения элементов заголовка. Например, если заголовок должен отображаться над элементами делегата при использовании ListView.OverlayHeader, его значение Z должно быть установлено выше, чем у делегатов. Дополнительную информацию см. в разделе Порядок наложения в ListView.

Это свойство QML было добавлено в Qt 5.4.

подсветка : Компонент

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

Экземпляр компонента подсветки создается для каждого списка. Геометрия созданного экземпляра компонента управляется списком, чтобы он оставался с текущим элементом, если свойство highlightFollowsCurrentItem не равно false. По умолчанию порядок наложения элемента подсветки равен 0.

См. также highlightItem, highlightFollowsCurrentItem, Пример подсветки ListView и Порядок наложения в ListView.

подсветкаСледуетЗаТекущимЭлементом : bool

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

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

Вот пример подсветки с движением, определенным элементом SpringAnimation:

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

Обратите внимание, что анимация подсветки также влияет на способ прокрутки представления. Это происходит потому, что представление перемещается для поддержания подсветки в предпочтительном диапазоне подсветки (или видимом области просмотра).

См. также подсветка и highlightMoveVelocity.

выделенныйЭлемент : Элемент

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

highlightItem управляется представлением, если highlightFollowsCurrentItem не установлено в false. По умолчанию порядок наложения элемента подсветки равен 0.

См. также подсветка, highlightFollowsCurrentItem и Порядок наложения в ListView.

highlightMoveDuration : int

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

highlightFollowsCurrentItem должно быть true для того, чтобы эти свойства имели эффект.

Значение по умолчанию для свойств скорости составляет 400 пикселей/секунду. Значение по умолчанию для свойств времени составляет -1, т. е. подсветка займет столько времени, сколько необходимо, чтобы перемещаться с заданной скоростью.

Эти свойства имеют те же характеристики, что и SmoothedAnimation.

См. также highlightFollowsCurrentItem.

highlightMoveVelocity : real

highlightFollowsCurrentItem должно быть true для того, чтобы эти свойства имели эффект.

Эти свойства имеют те же характеристики, что и SmoothedAnimation.

См. также highlightFollowsCurrentItem.

highlightRangeMode : перечисление

Эти свойства определяют предпочтительный диапазон подсветки (для текущего элемента) в представлении. Значение preferredHighlightBegin должно быть меньше значения preferredHighlightEnd.

Эти свойства влияют на положение текущего элемента при прокрутке списка. Например, если при прокрутке представления текущий выбранный элемент должен оставаться посередине списка, установите значения preferredHighlightBegin и preferredHighlightEnd на координаты верхней и нижней границ, где должен находиться средний элемент. Если currentItem изменено программно, список будет автоматически прокручиваться так, чтобы текущий элемент находился посередине представления. Кроме того, поведение индекса текущего элемента будет выполняться независимо от наличия или отсутствия подсветки.

Допустимые значения для highlightRangeMode:

Список элементов.ApplyRange - представление пытается поддерживать подсветку в заданном диапазоне. Однако подсветка может выходить за пределы диапазона в конце списка или из-за взаимодействия с мышкой.
Список элементов.StrictlyEnforceRange - подсветка никогда не выходит за пределы диапазона. Текущий элемент изменяется, если действие с клавиатуры или мыши вызовет выход подсветки за пределы диапазона.
Список элементов.NoHighlightRange - это значение по умолчанию.

highlightResizeDuration : int

highlightFollowsCurrentItem должно быть true для того, чтобы эти свойства имели эффект.

Эти свойства имеют те же характеристики, что и SmoothedAnimation.

См. также highlightFollowsCurrentItem.

highlightResizeVelocity : real

highlightFollowsCurrentItem должно быть true для того, чтобы эти свойства имели эффект.

Эти свойства имеют те же характеристики, что и SmoothedAnimation.

См. также highlightFollowsCurrentItem.

keyNavigationEnabled : bool

Это свойство указывает, включена ли навигация по списку с помощью клавиш.

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

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

Это свойство QML было добавлено в Qt 5.7.

См. также interactive.

keyNavigationWraps : bool

Это свойство указывает, будет ли навигация по списку с помощью клавиш циклической.

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

По умолчанию навигация по клавишам не циклическая.

направлениеРазметки : перечисление

Это свойство содержит направление разметки для горизонтально ориентированного списка.

Возможные значения:

Qt.LeftToRight (по умолчанию) - Элементы будут выстроены слева направо.
Qt.RightToLeft - Элементы будут выстроены справа налево.

Установка этого свойства не оказывает никакого эффекта, если orientation равно Qt.Vertical.

См. также ListView::effectiveLayoutDirection и ListView::verticalLayoutDirection.

модель : модель

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

Модель предоставляет набор данных, используемых для создания элементов в представлении. Модели могут быть созданы непосредственно в QML с помощью ListModel, XmlListModel или VisualItemModel, или предоставлены классами моделей C++. Если используется класс модели C++, он должен быть подклассом QAbstractItemModel или простым списком.

См. также Модели данных.

перемещение : Переход

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

Например, вот представление, которое задает такой переход:

ListView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Всякий раз, когда модель model выполняет операцию перемещения для перемещения определенного набора индексов, соответствующие элементы в представлении будут анимированы до их новых позиций в представлении в течение одной секунды. Переход применяется только к элементам, которые являются предметом операции перемещения в модели; он не применяется к элементам ниже них, которые смещаются в результате операции перемещения. Чтобы анимировать смещенные элементы, установите свойства displaced или moveDisplaced.

Для получения более подробной информации и примеров использования переходов представлений см. документацию ViewTransition.

См. также moveDisplaced и ViewTransition.

moveDisplaced : Transition

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

Например, вот представление, которое задает такой переход:

ListView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Всякий раз, когда модель model выполняет операцию перемещения для перемещения определенного набора индексов, элементы между исходным и целевым индексами операции перемещения смещаются, что приводит к их перемещению вверх или вниз (или вбок, если ориентация горизонтальная) в представлении. Во время этого смещения движение элементов к их новым позициям x, y в представлении будет анимировано с помощью NumberAnimation в течение одной секунды, как указано. Этот переход не применяется к элементам, которые фактически являются предметом операции перемещения; чтобы анимировать перемещаемые элементы, установите свойство move.

Если элемент смещается несколькими типами операций одновременно, не определено, будет ли применен переход addDisplaced, moveDisplaced или removeDisplaced. Кроме того, если нет необходимости указывать разные переходы в зависимости от того, смещается ли элемент в результате добавления, перемещения или удаления, можно установить свойство displaced вместо этого.

См. также displaced, move и ViewTransition.

orientation : enumeration

Это свойство задает ориентацию списка.

Возможные значения:

ListView.Horizontal - Элементы выстраиваются горизонтально
ListView.Vertical (по умолчанию) - Элементы выстраиваются вертикально

Горизонтальная ориентация:

Вертикальная ориентация:

См. также Направление Flickable.

populate : Transition

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

Он применяется ко всем элементам, которые создаются, когда:

Представление создается впервые
Модель представления model изменяется
Модель представления model сброшена, если модель является подклассом QAbstractItemModel

Например, вот представление, которое задает такой переход:

ListView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

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

См. также add и ViewTransition.

preferredHighlightBegin : real

Эти свойства определяют предпочтительный диапазон выделения (для текущего элемента) в представлении. Значение preferredHighlightBegin должно быть меньше значения preferredHighlightEnd.

Эти свойства влияют на позицию текущего элемента при прокрутке списка. Например, если текущий выбранный элемент должен оставаться посередине списка при прокрутке представления, установите значения preferredHighlightBegin и preferredHighlightEnd до координат верхней и нижней части, где находился бы средний элемент. Если currentItem изменено программно, список автоматически прокрутится так, чтобы текущий элемент находился посередине представления. Кроме того, поведение текущего индекса элемента будет происходить независимо от того, существует ли выделение.

Допустимые значения для highlightRangeMode:

ListView.ApplyRange - представление пытается поддерживать выделение в диапазоне. Однако выделение может выходить за пределы диапазона на концах списка или из-за взаимодействия с мышкой.
ListView.StrictlyEnforceRange - выделение никогда не выходит за пределы диапазона. Текущий элемент изменяется, если действие с клавиатуры или мыши приведет к выходу выделения за пределы диапазона.
ListView.NoHighlightRange - это значение по умолчанию.

preferredHighlightEnd : real

Допустимые значения для highlightRangeMode:

ListView.ApplyRange - представление пытается поддерживать выделение в диапазоне. Однако выделение может выходить за пределы диапазона на концах списка или из-за взаимодействия с мышкой.
ListView.StrictlyEnforceRange - выделение никогда не выходит за пределы диапазона. Текущий элемент изменяется, если действие с клавиатуры или мыши приведет к выходу выделения за пределы диапазона.
ListView.NoHighlightRange - это значение по умолчанию.

remove : Transition

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

Например, вот представление, которое задает такой переход:

ListView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

Всякий раз, когда элемент удаляется из представления выше, элемент будет анимирован до позиции (100,100) в течение одной секунды и параллельно также изменит свою непрозрачность на 0. Переход применяется только к элементам, удаляемым из представления; он не применяется к элементам ниже них, смещаемым при удалении элементов. Чтобы анимировать смещенные элементы, установите свойства displaced или removeDisplaced.

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

Кроме того, если для элемента делегата установлено присоединённое свойство delayRemove, переход remove не будет применён, пока delayRemove снова не станет ложным.

См. также removeDisplaced и ViewTransition.

removeDisplaced : Transition

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

Например, вот представление, которое задает такой переход:

ListView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Всякий раз, когда элемент удаляется из представления выше, все элементы под ним смещаются, что приводит к их перемещению вверх (или вбок, если ориентация горизонтальная) в представлении. При этом перемещении движение элементов к их новым позициям x, y в представлении будет анимировано с помощью NumberAnimation в течение одной секунды, как указано. Этот переход не применяется к элементу, который фактически был удален из представления; чтобы анимировать удаленные элементы, установите свойство remove.

Если элемент смещается несколькими типами операций одновременно, не определено, будет ли применён переход addDisplaced, moveDisplaced или removeDisplaced. Кроме того, если нет необходимости указывать разные переходы в зависимости от того, смещается ли элемент в результате добавления, перемещения или удаления, можно установить свойство displaced вместо этого.

См. также displaced, remove и ViewTransition.

section.property : string

Эти свойства определяют выражение, которое должно быть вычислено, и внешний вид меток секций.

section.property содержит имя свойства, которое является основой каждой секции.

section.criteria содержит критерии формирования каждой секции на основе section.property. Это значение может быть одним из:

ViewSection.FullString (по умолчанию) — секции создаются на основе значения section.property.
ViewSection.FirstCharacter — секции создаются на основе первой буквы значения section.property (например, секции 'A', 'B', 'C' и т. д. для адресной книги).

При определении границ секций используется регистронезависимое сравнение.

section.delegate содержит компонент-делегат для каждой секции. По умолчанию порядок размещения экземпляров делегатов секций — 2.

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

ViewSection.InlineLabels — метки секций отображаются в строке между делегатами элементов, разделяющими секции (по умолчанию).
ViewSection.CurrentLabelAtStart — метка текущей секции прилипает к началу представления при ее перемещении.
ViewSection.NextLabelAtEnd — метка следующей секции (за всеми видимыми секциями) прилипает к концу представления при ее перемещении.
Примечание: Включение ViewSection.NextLabelAtEnd требует от представления предварительного сканирования следующей секции, что влияет на производительность, особенно для медленных моделей.

Каждый элемент в списке имеет присоединённые свойства с именами ListView.section, ListView.previousSection и ListView.nextSection.

Например, здесь показан ListView, отображающий список животных, разделенных на секции. Каждый элемент в ListView размещается в другой секции в зависимости от свойства «размер» элемента модели. Компонент делегата sectionHeading обеспечивает светло-синюю полосу, которая отмечает начало каждой секции.

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: container.width
            height: childrenRect.height
            color: "lightsteelblue"

            Text {
                text: section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text { text: name; font.pixelSize: 18 }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

Примечание: Добавление секций в ListView не приводит к автоматическому переупорядочению элементов списка по критериям секции. Если модель не упорядочена по секциям, то созданные секции могут не быть уникальными; каждая граница между разными секциями будет приводить к созданию заголовка секции, даже если эта секция существует где-то ещё.

См. также Примеры ListView и Порядок размещения в ListView.

snapMode : перечисление

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

ListView.NoSnap (по умолчанию) — представление останавливается в любой точке видимой области.
ListView.SnapToItem — представление останавливается с выровненным элементом по началу представления.
ListView.SnapOneItem — представление останавливается не дальше, чем на один элемент от первого видимого элемента в момент отпускания кнопки мыши. Этот режим особенно полезен для перемещения по одной странице за раз.

snapMode не влияет на currentIndex. Чтобы обновить currentIndex при перемещении списка, установите highlightRangeMode в ListView.StrictlyEnforceRange.

См. также highlightRangeMode.

spacing : вещественное

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

Значение по умолчанию — 0.

verticalLayoutDirection : перечисление

Это свойство содержит направление выравнивания для вертикального списка.

Возможные значения:

ListView.TopToBottom (по умолчанию) — элементы выстраиваются сверху вниз.
ListView.BottomToTop — элементы выстраиваются снизу вверх.

Установка этого свойства не оказывает влияния, если orientation равен Qt.Horizontal.

См. также ListView::layoutDirection.

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

ListView.delayRemove : логическое

Это присоединённое свойство указывает, может ли делегат быть уничтожен. Оно прикрепляется к каждому экземпляру делегата. Значение по умолчанию — false.

Иногда требуется отложить уничтожение элемента до завершения анимации. Нижеприведенный пример делегата гарантирует, что анимация завершится до удаления элемента из списка.

Component {
    id: delegate
    Item {
        ListView.onRemove: SequentialAnimation {
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false }
        }
    }
}

Если указана транзиция remove, она не будет применена, пока delayRemove не вернется в false.

ListView.isCurrentItem : логическое

Это присоединённое свойство равно true, если этот делегат является текущим элементом; в противном случае — false.

Оно прикрепляется к каждому экземпляру делегата.

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

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView.nextSection : строка

Это присоединённое свойство содержит секцию следующего элемента.

Оно прикрепляется к каждому экземпляру делегата.

Секция оценивается с использованием свойств section.

ListView.previousSection : строка

Это присоединённое свойство содержит секцию предыдущего элемента.

Оно прикрепляется к каждому экземпляру делегата.

Секция оценивается с использованием свойств section.

ListView.section : строка

Это присоединённое свойство содержит секцию данного элемента.

Оно прикрепляется к каждому экземпляру делегата.

Секция оценивается с использованием свойств section.

ListView.view : ListView

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

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

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

add()

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

Если указана транзиция add, она применяется сразу после обработки этого сигнала.

Соответствующий обработчик — onAdd.

remove()

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

Если указана транзиция remove, она применяется после обработки этого сигнала, при условии, что delayRemove равен false.

Соответствующий обработчик — onRemove.

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

decrementCurrentIndex()

Уменьшает текущий индекс. Текущий индекс будет циклически повторяться, если keyNavigationWraps равен true и он находится в начале. Этот метод не оказывает никакого влияния, если count равен нулю.