Тип QML ListView

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

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

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

Свойства

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

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

delayRemove : bool
isCurrentItem : bool
nextSection : string
previousSection : string
section : string
view : ListView

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

add()
pooled()
remove()
reused()

Методы

decrementCurrentIndex()
forceLayout()
incrementCurrentIndex()
int indexAt(real x, real y)
Элемент itemAt(real x, real y)
Элемент itemAtIndex(int index)
positionViewAtBeginning()
positionViewAtEnd()
positionViewAtIndex(int index, PositionMode mode)

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

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

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

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, в зависимости от значений перечисленных выше свойств.

ListView с ориентацией Qt.Vertical
Сверху вниз	Снизу вверх
ListView с ориентацией 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.

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

Начиная с версии 5.15, ListView можно настроить на переиспользование элементов вместо создания новых элементов из delegate каждый раз, когда новые строки появляются в поле зрения. Этот подход улучшает производительность в зависимости от сложности делегата. Переиспользование элементов по умолчанию отключено (по соображениям обратной совместимости), но его можно включить, установив свойство reuseItems в true.

Когда элемент исчезает из поля зрения, он перемещается в пул переиспользования, который представляет собой внутренний кэш неиспользуемых элементов. В этом случае посылается сигнал ListView::pooled, чтобы сообщить об этом элементу. Аналогично, при возвращении элемента из пула посылается сигнал ListView::reused.

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

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

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

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

Следующий пример показывает делегат, анимирующий вращающийся прямоугольник. При перемещении в пул анимация временно приостанавливается:

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

См. также QML Модели данных, GridView, PathView и Примеры Qt Quick — Виды.

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

highlightMoveDuration : int

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

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

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

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

Свойства скорости и продолжительности перемещения используются для управления перемещением из-за изменений индекса; например, при вызове incrementCurrentIndex(). При прокрутке пользователем ListView используется скорость прокрутки для управления перемещением.

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

[since QtQuick 2.3] displayMarginBeginning : int

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

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

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

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

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

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

highlightRangeMode : enumeration

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

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

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

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

currentIndex : int

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

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

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

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

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

currentSection : string

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

delegate : Component

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

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

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

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

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

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

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

displaced : Transition

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

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

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

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

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

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

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

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

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

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

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

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

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

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

footerItem : Item

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

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

[since Qt 5.4] footerPositioning : перечисление

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

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

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

Примечание: Если footerPositioning не установлено в ListView.InlineFooter, пользователь не может нажать и провести пальцем по списку от подвала. В любом случае, элемент подвала может содержать элементы или обработчики событий, которые обеспечивают пользовательскую обработку ввода мыши или сенсорного ввода.

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

header : Component

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

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

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

headerItem : Item

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

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

[since Qt 5.4] headerPositioning : перечисление

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

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

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

Примечание: Если headerPositioning не установлено в ListView.InlineHeader, пользователь не может нажать и провести пальцем по списку от заголовка. В любом случае, элемент заголовка может содержать элементы или обработчики событий, которые обеспечивают пользовательскую обработку ввода мыши или сенсорного ввода.

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

highlight : Component

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

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

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

highlightFollowsCurrentItem : 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
}

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

См. также highlight и highlightMoveVelocity.

highlightItem : Item

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

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

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

[since 5.7] keyNavigationEnabled : bool

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

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

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

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

См. также interactive.

keyNavigationWraps : bool

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

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

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

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

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

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

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

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

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

model : model

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

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

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

move : Transition

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

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

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

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

END_OF_DOCUMENT_MARKER

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

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

moveDisplaced : Transition

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

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

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

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

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

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

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

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

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

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

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

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

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

populate : Transition

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

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

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

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

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

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

Однако при последующем прокручивании представления переход populate не выполняется, даже если делегаты создаются по мере появления на экране. Когда модель изменяется таким образом, что становятся видимыми новые делегаты, применяется переход add. Поэтому вы не должны полагаться на переход populate для инициализации свойств в делегате, так как он не применяется ко всем делегатам. Если ваша анимация устанавливает значение to свойства, свойство должно изначально иметь значение to, а анимация должна установить значение from в случае анимации:

ListView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

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

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.

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

[since 5.15] reuseItems : bool

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

Это свойство установлено по умолчанию в false.

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

См. также Повторное использование элементов, pooled() и reused().

section.criteria : перечисление

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

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 помещается в другой раздел в зависимости от свойства "size" элемента модели. Делегат sectionHeading предоставляет светло-голубую полосу, которая обозначает начало каждого раздела.

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

            required property string section

            Text {
                text: parent.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 {
            required property string name
            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 - представление останавливается не более чем на один элемент от первого видимого элемента в момент отпускания кнопки мыши. Этот режим особенно полезен для перемещения по одной странице за раз. Когда включен SnapOneItem, ListView будет проявлять более сильное стремление к соседним элементам при перемещении. Например, кратковременное перетаскивание, которое возвращается к текущему элементу с SnapToItem, может переместиться к соседнему элементу с 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.

pooled()

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

Этот сигнал излучается только если свойство reuseItems равно true.

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

См. также Повторное использование элементов, reuseItems и reused().

remove()

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

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

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

reused()

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

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

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

Этот сигнал излучается только если свойство reuseItems равно true.

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

См. также Повторное использование элементов, reuseItems и pooled().

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

positionViewAtBeginning()

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

Не рекомендуется использовать contentX или contentY для позиционирования представления на определённом индексе. Это ненадёжно, так как удаление элементов из начала списка не приводит к перепозиционированию всех остальных элементов, и фактическое начало представления может варьироваться в зависимости от размера делегатов.

Примечание: методы следует вызывать только после завершения компонента. Для позиционирования представления при запуске этот метод следует вызывать методом Component.onCompleted. Например, для позиционирования представления в конце при запуске:

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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