Тип QML ListView

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

Заявление об импорте:	import QtQuick 2.12
Наследует:	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 : Переход
раздел
- свойство раздела : строка
- критерии раздела : перечисление
- делегат раздела : Компонент
- позиционирование метки раздела : перечисление
snapMode : перечисление
интервал : real
направление вертикального макета : перечисление

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

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

добавить()
удалить()

Методы

уменьшить текущий индекс()
принудительный макет()
увеличить текущий индекс()
int индекс в(real x, real y)
Элемент элемент в(real x, real y)
позиционировать представление в начале()
позиционировать представление в конце()
позиционировать представление по индексу(int index, PositionMode mode)

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

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

A ListView имеет model, который определяет отображаемые данные, и delegate, который определяет, как следует отображать данные. Элементы в ListView выстраиваются горизонтально или вертикально. Просмотры списков по своей природе являются flickable, потому что 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 для получения дополнительной информации).

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

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. Если представление не обрезается другим элементом или экраном, необходимо установить 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 Модели данных, GridView, PathView и Примеры Qt Quick - Представления.

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

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 : строка

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

delegate : Компонент

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

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

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

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

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

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

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

displaced : Переход

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

Это удобный способ указать универсальный переход, который нужно применить ко всем элементам, которые смещаются операциями добавления, перемещения или удаления, без необходимости указывать отдельные свойства 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 : целое

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

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

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

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

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

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

displayMarginEnd : целое

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

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

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

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

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

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

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

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

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

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

footerItem : Элемент

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

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

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

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

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

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

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

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

header : Компонент

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

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

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

headerItem : Элемент

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

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

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

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

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

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

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

Это свойство было введено в 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.

highlightMoveDuration : int

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

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

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

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

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

highlightMoveVelocity : real

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

highlightRangeMode : enumeration

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

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

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

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

highlightResizeDuration : int

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

highlightResizeVelocity : real

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

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, XmlListModel или ObjectModel, или предоставлены классами моделей на C++. Если используется класс модели на C++, он должен быть подклассом QAbstractItemModel или простым списком.

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

move : Transition

Это свойство содержит анимацию, применяемую к элементам в представлении, которые перемещаются из-за операции перемещения в модели представления 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 вместо этого.

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

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

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

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

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

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

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

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

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

populate : Transition

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

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

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

Например, вот представление, которое задаёт такую анимацию:

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

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

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

См. также 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, переход удаления не будет применён, пока delayRemove не станет снова ложью.

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

См. также 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 помещается в разных разделах в зависимости от свойства "size" элемента модели. Компонент делегата 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 - представление останавливается не дальше чем на один элемент от первого видимого элемента в момент отпускания кнопки мыши. Этот режим особенно полезен для перемещения по одной странице за раз. При включенном SnapOneItem представление будет сильнее тяготеть к соседним элементам при перемещении. Например, короткое перетаскивание, которое возвращается к текущему элементу с 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 : логическое

Это присоединённое свойство имеет значение 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.

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

positionViewAtBeginning()

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

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

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

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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