Тип ListView QML

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

Заявление об импорте:	import QtQuick 2.13
Наследует:	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 индекс в(x, real y)
Элемент элемент в(x, real y)
Элемент элемент по индексу(index)
разместить представление в начале()
разместить представление в конце()
разместить представление по индексу(index, PositionMode mode)

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

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

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

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

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

import QtQuick 2.0

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

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

import QtQuick 2.0

ListView {
    width: 180; height: 200

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

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

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

Rectangle {
    width: 180; height: 200

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

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

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

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

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

ListView {
    width: 180; height: 200

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

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

Примечание: Представления не включают clip автоматически. Если представление не обрезается другим элементом или экраном, необходимо установить 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.

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

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

highlightMoveVelocity : real

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

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

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

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

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

displayMarginBeginning : int

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

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

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

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

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

Эта документация была введена в QtQuick 2.3.

preferredHighlightBegin : real

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

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

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

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

currentIndex : int

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

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

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

add : Transition

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

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

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

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

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

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

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

addDisplaced : Transition

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

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

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

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

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

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

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

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

cacheBuffer : int

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

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

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

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

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

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

count : int

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

currentSection : string

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

delegate : Component

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

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

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

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

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

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

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

displaced : Transition

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

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

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

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

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

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

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

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

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

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

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

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

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

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

footerItem : Item

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

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

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

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

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

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

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

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

header : Component

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

Для каждого представления создается экземпляр компонента заголовка. Заголовок размещается в начале представления, перед элементами. Стандартный порядок наложения заголовка — 1.

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

headerItem : Элемент

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

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

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

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

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

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

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

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

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

highlight : Компонент

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

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

См. также highlightItem, highlightFollowsCurrentItem, пример ListView highlight и Порядок расположения элементов в 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
}

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

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

highlightItem : Элемент

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

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

См. также highlight, 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 : Переход

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

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

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 (по умолчанию) - Элементы выложены по вертикали

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

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

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

populate : Переход

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

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

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

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

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

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

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

remove : Переход

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

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

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 : Переход

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

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

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

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

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

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

section.property : строка

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

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

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

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

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

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

ListView.isCurrentItem : булево

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

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

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

ListView {
    width: 180; height: 200

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

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

ListView.nextSection : string

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

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

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

ListView.previousSection : string

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

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

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

ListView.section : string

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

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

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

ListView.view : ListView

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

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

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

add()

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

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

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

remove()

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

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

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

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

positionViewAtBeginning()

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

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

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

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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