Тип QML ListView

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

Оператор импорта:	import QtQuick 2.14
Наследует:	Flickable

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

Свойства

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

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

delayRemove : bool
isCurrentItem : bool
nextSection : строка
previousSection : строка
раздел : строка
view : ListView

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

add()
remove()

Методы

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

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

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

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 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 можно контролировать с помощью этих свойств:

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

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

highlightMoveDuration : int

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

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.

highlightRangeMode : enumeration

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

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

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

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

currentIndex : int

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

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

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

add : Transition

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

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

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

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

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

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

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

addDisplaced : Transition

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

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

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

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

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

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

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

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

cacheBuffer : int

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

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

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

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

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

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

count : int

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

currentSection : string

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

delegate : Component

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

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

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

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

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

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

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

displaced : Transition

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

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

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

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

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

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

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

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

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

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

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

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

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

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

footerItem : Item

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

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

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 и Порядок расположения элементов в 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 : Элемент

Содержит выделенный элемент, созданный из компонента 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 : model

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

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

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

move : Переход

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

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

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

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

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

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

moveDisplaced : Переход

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

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

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

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

populate : Переход

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

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

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

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

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

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

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

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

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

См. также 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 снова не станет ложным.

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

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

removeDisplaced : Переход

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, вот ListView, который отображает список животных, разделённых на секции. Каждый элемент в ListView помещается в другую секцию в зависимости от свойства "size" элемента модели. Делегат компонента sectionHeading обеспечивает светлосинюю полосу, которая отмечает начало каждой секции.

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

            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 ListView сильнее тяготеет к соседним элементам при перемещении. Например, короткое перетаскивание, которое возвращает представление к текущему элементу с помощью SnapToItem, может переместиться к соседнему элементу с помощью SnapOneItem.

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

См. также highlightRangeMode.

spacing : вещественное

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

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

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

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

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

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.

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

positionViewAtBeginning()

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

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

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

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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