Тип 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
}

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

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

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

Примечание: Избегайте хранения состояния внутри делегата. Если это необходимо, переустановите его вручную при получении сигнала ListView::reused.

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

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

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

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 должно быть истинным для того, чтобы эти свойства имели эффект.

Значение по умолчанию для свойств скорости составляет 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.

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

footer : Component

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

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

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

footerItem : Item

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

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

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

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

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

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

Примечание: Если footerPositioning не установлено в ListView.InlineFooter, пользователь не сможет нажимать и поворачивать список с помощью подвала. В любом случае, элемент подвала может содержать элементы или обработчики событий, которые обеспечивают пользовательскую обработку ввода мыши или сенсорного ввода.

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

header : Component

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

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

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

headerItem : Item

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

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

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

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

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

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

Примечание: Если headerPositioning не установлено в ListView.InlineHeader, пользователь не сможет нажимать и поворачивать список с помощью заголовка. В любом случае, элемент заголовка может содержать элементы или обработчики событий, которые обеспечивают пользовательскую обработку ввода мыши или сенсорного ввода.

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

highlight : Component

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

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

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

highlightFollowsCurrentItem : bool

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

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

Вот пример выделения с его движением, определённым элементом SpringAnimation:

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

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

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

highlightItem : Item

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

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

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

[since 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 : Transition

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

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

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

Всякий раз, когда model выполняет операцию перемещения для перемещения определённого набора индексов, соответствующие элементы в списке будут анимированы до новых позиций в списке за одну секунду. Переход применяется только к элементам, которые являются объектом операции перемещения в модели; он не применяется к элементам под ними, смещённым в результате операции перемещения. Чтобы анимировать смещённые элементы, установите свойства 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 (по умолчанию) - Элементы выстраиваются по вертикали

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

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

Для получения более подробной информации и примеров использования переходов между представлениями, см. документацию 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.

Например, вот ListView, отображающий список животных, разделённых на разделы. Каждый элемент в ListView помещается в другой раздел в зависимости от свойства "size" элемента модели. Делегат 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 и Порядок стекирования в 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 {
        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()
    }
}

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

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

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

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

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

ListView {
    width: 180; height: 200

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

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

ListView.nextSection : строка

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

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

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

ListView.previousSection : строка

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

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

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

ListView.section : строка

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

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

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

ListView.view : ListView

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

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

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

add()

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

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

Примечание: Соответствующий обработчик — 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 равен нулю.

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

целое число indexAt(вещественное x, вещественное y)

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

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

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

Элемент itemAt(вещественное x, вещественное y)

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

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

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

[since 5.13] Элемент itemAtIndex(целое index)

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

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

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

positionViewAtIndex(целое 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)