Тип QML ListView

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

Заявление об импорте:	import QtQuick 2.15
Наследует:	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 : 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 : строка
snapMode : перечисление
spacing : real
verticalLayoutDirection : перечисление

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

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

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

add()
remove()

Методы

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 каждый раз, когда новые строки входят в область просмотра. Этот подход улучшает производительность, в зависимости от сложности delegate. Переиспользование элементов отключено по умолчанию (по соображениям обратной совместимости), но его можно включить, установив свойство reuseItems в true.

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

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

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

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

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

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

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

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

highlightMoveDuration : int

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

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

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

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

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

displayMarginBeginning : int

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

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

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

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

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

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

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

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

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

Стандартный порядок сортировки по Z экземпляров делегата — 1.

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

См. также Порядок сортировки по Z в 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.

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

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

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

footerItem : Item

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

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

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

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

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

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

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

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

header : Компонент

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

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

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

headerItem : Элемент

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

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

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

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

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

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

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

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

highlight : Компонент

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

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

См. также элемент выделения, 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
}

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

См. также выделение и highlightMoveVelocity.

highlightItem : Элемент

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

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

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

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 : модель

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

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

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

move : Переход

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

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

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

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

Для получения более подробной информации и примеров использования переходов просмотров, см. документацию по 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.

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

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

reuseItems : bool

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

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

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

См. также Повторное использование элементов, ListView::pooled и ListView::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 : булево

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

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

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 : булево

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

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

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

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 ложь.

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

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

positionViewAtBeginning()

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

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

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

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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