Тип QML ListView

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

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

Свойства

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

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

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

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

• add()
• pooled()
• remove()
• reused()

Методы

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

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

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

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

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

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

import QtQuick 2.0

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

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

import QtQuick 2.0

ListView {
    width: 180; height: 200

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

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

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

Rectangle {
    width: 180; height: 200

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

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

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

Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Следовательно, состояние никогда не должно храниться в делегате. Делегаты обычно являются потомками contentItem ListView, но обычно, в зависимости от того, виден ли он в представлении или нет, родитель может измениться, и иногда быть null. Из-за этого привязка к свойствам родителя изнутри делегата не рекомендуется. Если вы хотите, чтобы делегат заполнял ширину ListView, рассмотрите один из следующих подходов вместо этого:

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

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

ListView {
    width: 180; height: 200

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

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

Макеты ListView

Макет элементов в ListView можно контролировать с помощью этих свойств:

• orientation - управляет тем, как элементы выстраиваются — по горизонтали или вертикали. Это значение может быть либо Qt.Horizontal, либо Qt.Vertical.
• layoutDirection - управляет направлением горизонтального выстраивания элементов в горизонтально ориентированном представлении: то есть, выстраиваются ли элементы слева направо или наоборот. Это значение может быть либо Qt.LeftToRight, либо Qt.RightToLeft.
• verticalLayoutDirection - управляет направлением вертикального выстраивания элементов в вертикально ориентированном представлении: то есть, выстраиваются ли элементы сверху вниз или наоборот. Это значение может быть либо ListView.TopToBottom, либо ListView.BottomToTop.

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

Направление скроллинга

По умолчанию вертикальный 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 элемента равно 0, поэтому установка значения Z этих элементов в 0 не повлияет. Обратите внимание, что значение Z имеет тип real, поэтому можно задавать дробные значения, например 0.1.

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

Начиная с версии 5.15, ListView можно настроить на переиспользование элементов вместо создания новых из delegate каждый раз, когда новые строки попадают в область просмотра. Этот подход повышает производительность, в зависимости от сложности delegate. Переиспользование элементов по умолчанию выключено (по соображениям обратной совместимости), но его можно включить, установив свойство reuseItems в значение true.

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

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

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

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

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

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

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

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

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

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

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

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

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

highlightMoveDuration: 1000
highlightMoveVelocity: -1

См. также highlightFollowsCurrentItem.

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

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

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

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

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

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

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

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

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

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

Свойство 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.

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

addDisplaced : Transition

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

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

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

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

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

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

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

cacheBuffer : int

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

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

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

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

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

count : int

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

currentSection : string

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

delegate : Component

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

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

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

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

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

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

footer : Component

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

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

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

footerItem : Item

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

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

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

[с Qt 5.4] footerPositioning : перечисление

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

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

header : Компонент

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

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

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

headerItem : Элемент

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

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

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

[с Qt 5.4] headerPositioning : перечисление

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

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

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

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

move : Переход

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

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

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

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

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

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

moveDisplaced : Transition

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

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

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

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

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

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

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

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

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

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

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

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

populate : Transition

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

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

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

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

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

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

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

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

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

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

remove : Transition

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

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

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

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

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

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

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

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

removeDisplaced : Transition

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

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

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

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

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

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

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

[since 5.15] reuseItems : bool

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

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

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

См. также Повторное использование элементов, pooled() и reused().

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

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

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

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

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

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

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

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

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

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

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

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

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

            required property string section

            Text {
                text: parent.section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text {
            required property string name
            text: name
            font.pixelSize: 18
        }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

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

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

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

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

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

См. также highlightRangeMode.

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

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

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

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

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

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

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

Установка этого свойства не оказывает влияния, если ориентация равна Qt.Horizontal.

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

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

ListView.delayRemove : логическое

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

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

Component {
    id: delegate
    Item {
        SequentialAnimation {
            id: removeAnimation
            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 }
        }
        ListView.onRemove: removeAnimation.start()
    }
}

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

ListView.isCurrentItem : логическое

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

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

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

ListView {
    width: 180; height: 200

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

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

ListView.nextSection : строка

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

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

Секция вычисляется с помощью свойств section.

ListView.previousSection : строка

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

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

Секция вычисляется с помощью свойств section.

ListView.section : строка

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

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

Секция вычисляется с помощью свойств section.

ListView.view : ListView

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

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

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

add()

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

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

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

pooled()

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

Этот сигнал испускается только если свойство reuseItems равно true.

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

См. также Использование повторно элементов, reuseItems и reused().

remove()

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

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

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

reused()

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

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

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

Этот сигнал испускается только если свойство reuseItems равно true.

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

См. также Использование повторно элементов, reuseItems и pooled().

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

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

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

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

Component.onCompleted: positionViewAtEnd()

decrementCurrentIndex()

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

Примечание: методы следует вызывать только после завершения компонента.

[since 5.1] forceLayout()

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

Этот метод заставляет ListView немедленно отреагировать на любые незавершенные изменения в модели.

Примечание: методы следует вызывать только после завершения компонента.

Этот метод был представлен в Qt 5.1.

incrementCurrentIndex()

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

Примечание: методы следует вызывать только после завершения компонента.

int indexAt(real x, real y)

Возвращает индекс видимого элемента, содержащего точку x, y в координатах содержимого. Если в указанной точке нет элемента или элемент не виден, возвращается -1.

Если элемент находится за пределами видимой области, возвращается -1, независимо от того, будет ли в этой точке элемент при прокрутке в область видимости.

Примечание: методы следует вызывать только после завершения компонента.

Item itemAt(real x, real y)

Возвращает видимый элемент, содержащий точку x, y в координатах содержимого. Если в указанной точке нет элемента или элемент не виден, возвращается null.

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

Примечание: методы следует вызывать только после завершения компонента.

[since 5.13] Item itemAtIndex(int index)

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

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

Этот метод был введён в Qt 5.13.

positionViewAtIndex(int index, PositionMode mode)

Размещает представление так, что элемент с индексом index находится в позиции, указанной параметром mode:

• ListView.Начало - размещает элемент в верхней части (или слева для горизонтальной ориентации) представления.
• ListView.Центр - размещает элемент по центру представления.
• ListView.Конец - размещает элемент в нижней части (или справа для горизонтальной ориентации) представления.
• ListView.Видно - если любая часть элемента видна, то никаких действий не выполняется, в противном случае элемент приводится в область видимости.
• ListView.Содержит - обеспечивает видимость всего элемента. Если элемент больше, чем представление, элемент размещается в верхней части (или слева для горизонтальной ориентации) представления.
• ListView.ФиксированнаяПозиция - размещает элемент в позиции preferredHighlightBegin. Этот режим допустим только если highlightRangeMode равен StrictlyEnforceRange или открепление включено через snapMode.

Если размещение представления в индексе index приведет к появлению пустого места в начале или конце представления, представление будет размещено на границе.

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

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

Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning)