Тип ListView QML

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

Оператор импорта:	import QtQuick 2.5
Наследует:	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
keyNavigationWraps : bool
layoutDirection : перечисление
model : модель
move : Переход
moveDisplaced : Переход
orientation : перечисление
populate : Переход
preferredHighlightBegin : real
preferredHighlightEnd : real
remove : Переход
removeDisplaced : Переход
section
- section.property : строка
- section.criteria : перечисление
- section.delegate : Компонент
- section.labelPositioning : перечисление
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)
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 для получения дополнительной информации).

Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Они являются дочерними элементами 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
Слева направо	Справа налево

См. также 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

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

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

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

currentItem : Item

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

currentSection : string

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

delegate : Component

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

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

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

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

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

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

displaced : Transition

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

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

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

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

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

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

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

displayMarginBeginning : int

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

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

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

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

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

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

displayMarginEnd : int

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

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

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

effectiveLayoutDirection : enumeration

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

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

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

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

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

См. также header и footerItem.

footerItem : Item

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

См. также footer и headerItem.

footerPositioning : enumeration

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

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

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

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

header : Component

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

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

См. также footer и headerItem.

headerItem : Item

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

См. также header и footerItem.

headerPositioning : enumeration

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

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

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

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

highlight : Component

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

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

См. также highlightItem, highlightFollowsCurrentItem и Пример выделения 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. По умолчанию порядок перекрытия элемента выделения, задаваемый свойством stacking order, составляет 0.

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

highlightMoveDuration : int

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

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

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

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

См. также highlightFollowsCurrentItem.

highlightMoveVelocity : real

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

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

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

См. также highlightFollowsCurrentItem.

highlightRangeMode : enumeration

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

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

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

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

highlightResizeDuration : int

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

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

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

См. также highlightFollowsCurrentItem.

highlightResizeVelocity : real

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

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

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

См. также highlightFollowsCurrentItem.

keyNavigationWraps : bool

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

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

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

layoutDirection : enumeration

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

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

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

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

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

model : model

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

Модель предоставляет набор данных, используемых для создания элементов в представлении. Модели могут быть созданы непосредственно в QML с помощью ListModel, XmlListModel или VisualItemModel, или предоставлены классами моделей 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 вместо этого.

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

orientation : enumeration

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

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

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

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

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

populate : Transition

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

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

Первоначальном создании представления
Изменении модели представления model
Переустановке модели представления model, если модель является подклассом QAbstractItemModel

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

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

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

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

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

preferredHighlightBegin : real

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

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

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

preferredHighlightEnd : real

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

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

remove : Transition

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

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

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

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

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

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

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

removeDisplaced : Transition

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

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

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

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

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

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

section.property : string

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

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

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

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

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

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

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

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

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

Например, вот ListView, который отображает список животных, разделенных на разделы. Каждый элемент в ListView помещается в разные разделы в зависимости от свойства «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.

snapMode : enumeration

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

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

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

См. также highlightRangeMode.

spacing : real

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

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

verticalLayoutDirection : enumeration

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

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

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

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

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

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

ListView.delayRemove : bool

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

Это присоединенное свойство равно 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 : string

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

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

Раздел оценивается с помощью свойств section.

ListView.previousSection : string

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

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

Раздел оценивается с помощью свойств section.

ListView.section : string

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

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

Раздел оценивается с помощью свойств section.

ListView.view : ListView

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

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

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

add()

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

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

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

remove()

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

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

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

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

decrementCurrentIndex()

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