Тип 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 : Переход
• section
  • section.property : строка
  • section.criteria : перечисление
  • section.delegate : Компонент
  • section.labelPositioning : перечисление
• snapMode : перечисление
• spacing : real
• verticalLayoutDirection : перечисление

Прикрепленные свойства

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

Прикрепленные сигналы

• add()
• remove()

Методы

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

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

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

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

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

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

import QtQuick 2.0

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

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

import QtQuick 2.0

ListView {
    width: 180; height: 200

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

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

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

Rectangle {
    width: 180; height: 200

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

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

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

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

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

ListView {
    width: 180; height: 200

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

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

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

Макеты ListView

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

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

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

Направление прокрутки

По умолчанию вертикальный ListView устанавливает 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.

См. также QML Data Models, GridView, PathView и Qt Quick Examples - Views.

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

add : Transition

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

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

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

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

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

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

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

addDisplaced : Transition

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

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

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

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

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

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

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

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

cacheBuffer : int

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

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

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

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

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

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

count : int

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

currentIndex : int

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

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

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

currentItem : Item

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

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

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

currentSection : string

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

delegate : Component

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

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

ListView выведет элементы, основываясь на размере корневого элемента в делегате.

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

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

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

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

displaced : Transition

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

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

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

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

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

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

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

displayMarginBeginning : int

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

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

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

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

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

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

displayMarginEnd : int

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

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

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

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

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

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

effectiveLayoutDirection : enumeration

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

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

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

footer : Component

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

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

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

footerItem : Item

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

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

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

footerPositioning : enumeration

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

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

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

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

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

header : Component

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

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

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

headerItem : Item

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

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

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

headerPositioning : enumeration

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

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

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

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

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

highlightMoveDuration : int

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

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

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

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

См. также highlightFollowsCurrentItem.

highlightMoveVelocity : real

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

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

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

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

См. также highlightFollowsCurrentItem.

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

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

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

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

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

highlightResizeDuration : int

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

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

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

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

См. также highlightFollowsCurrentItem.

highlightResizeVelocity : real

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

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

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

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

См. также highlightFollowsCurrentItem.

keyNavigationEnabled : bool

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

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

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

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

См. также interactive.

keyNavigationWraps : bool

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

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

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

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

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

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

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

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

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

model : model

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

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

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

move : Переход

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

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

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

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

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

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

moveDisplaced : Переход

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

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

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

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

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

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

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

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

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

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

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

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

populate : Переход

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

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

• Представление создается впервые
• Модель модели представления изменяется
• Модель модели представления сбрасывается, если модель является подклассом QAbstractItemModel

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

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

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

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

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

preferredHighlightBegin : вещественный

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

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

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

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

preferredHighlightEnd : вещественный

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

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

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

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

remove : Переход

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

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

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

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

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

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

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

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

removeDisplaced : Переход

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

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

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

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

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

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

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

section.property : строка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание: Добавление разделов в ListView не приводит к автоматическому упорядочиванию элементов списка по критериям раздела. Если модель не упорядочена по разделу, то созданные разделы могут оказаться не уникальными; каждая граница между разными разделами приведёт к созданию заголовка раздела, даже если этот раздел существует где-то ещё.

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

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

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

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

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

См. также highlightRangeMode.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ListView {
    width: 180; height: 200

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

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

ListView.nextSection : строка

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

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

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

ListView.previousSection : строка

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

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

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

ListView.section : строка

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

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

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

ListView.view : ListView

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

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

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

add()

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

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

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

remove()

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

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

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

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

decrementCurrentIndex()

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

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

forceLayout()

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

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

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

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

incrementCurrentIndex()

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

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

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

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

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

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

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

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

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

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

positionViewAtBeginning()

positionViewAtEnd()

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)