ListView QML Type

提供模型所提供项的列表视图。更多...

• 所有成员的列表，包括继承的成员

属性

• add : Transition
• addDisplaced : Transition
• cacheBuffer : int
• count : int
• currentIndex : int
• currentItem : Item
• currentSection : string
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• footer : Component
• footerItem : Item
• footerPositioning : enumeration (since Qt 5.4)
• header : Component
• headerItem : Item
• headerPositioning : enumeration (since Qt 5.4)
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightMoveVelocity : real
• highlightRangeMode : enumeration
• highlightResizeDuration : int
• highlightResizeVelocity : real
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• orientation : enumeration
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• section
  • section.criteria : enumeration
  • section.delegate : Component
  • section.labelPositioning : enumeration
  • section.property : string
• snapMode : enumeration
• spacing : real
• verticalLayoutDirection : enumeration

关联属性

• delayRemove : bool
• isCurrentItem : bool
• nextSection : string
• previousSection : string
• section : string
• view : ListView

附加信号

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

方法

• void decrementCurrentIndex()
• void forceLayout()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

详细说明

ListView 用于显示来自内置 QML 类型（如ListModel 和XmlListModel ）所创建的模型数据，或来自在 C++ 中定义的、继承自QAbstractItemModel 或QAbstractListModel 的自定义模型类所创建的模型数据。

ListView 包含一个model （用于定义要显示的数据）和一个delegate （用于定义数据的显示方式）。ListView 中的项目可水平或垂直排列。由于 ListView 继承自Flickable ，因此其列表视图天生支持滑动操作。

使用示例

以下示例展示了在名为ContactModel.qml 的文件中定义的一个简单列表模型：

import QtQuick

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

ListView {
    width: 180; height: 200

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

在此，ListView 为其模型创建了一个ContactModel 组件，并为其委托创建了一个Text 项。视图将为模型中的每个项创建一个新的Text 组件。请注意，委托能够直接访问模型的name 和number 数据。

下图展示了一个经过改进的列表视图。委托的视觉效果得到了优化，并被移至一个独立的contactDelegate 组件中。

Rectangle {
    width: 180; height: 200

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

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

当前选中的项目通过highlight 属性使用蓝色Rectangle 进行高亮显示，并将focus 设置为true ，以便为列表视图启用键盘导航。列表视图本身是一个焦点范围（更多详细信息请参阅 Qt Quick 中的“键盘焦点”）。

委托会根据需要实例化，并可能随时被销毁。因此， state should never be stored in a delegate. 委托通常隶属于 ListView 的contentItem ，但通常取决于它在视图中是否可见，其父对象可能会发生变化，有时甚至可能是null 。正因如此，不建议在委托内部绑定到父对象的属性。 如果您希望委托占据 ListView 的整个宽度，请考虑改用以下方法之一：

ListView {
    id: listView
    // ...

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

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

ListView 会在委托的根项目上附加若干属性，例如ListView.isCurrentItem 。在下面的示例中，根委托项目可以直接通过ListView.isCurrentItem 访问此附加属性，而子contactInfo 对象则必须通过wrapper.ListView.isCurrentItem 引用该属性。

ListView {
    width: 180; height: 200

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

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

ListView 布局

ListView 中项目的布局可通过以下属性进行控制：

• orientation - 控制项目是水平排列还是垂直排列。该值可以是 Qt.Horizontal 或 Qt.Vertical。
• layoutDirection - 控制水平布局视图的水平布局方向：即项目是从视图左侧向右侧排列，还是反之。该值可以是 Qt.LeftToRight 或 Qt.RightToLeft。
• verticalLayoutDirection - 控制垂直取向视图的水平布局方向：即项目是从视图顶部向底部排列，还是反之。该值可以是 ListView.TopToBottom 或 ListView.BottomToTop。

默认情况下，ListView 采用垂直方向，项目从上到下排列。下表展示了根据上述属性的不同值，ListView 可能采用的各种布局。

可滑动方向

默认情况下，垂直 ListView 将 `flickableDirection ` 设置为`Flickable.Vertical`，而水平 ListView 则将其设置为 `Flickable.Horizontal`。此外，垂直 ListView 仅计算（估算）contentHeight ，而水平 ListView 仅计算contentWidth 。另一维度的值则设置为-1。

自 Qt 5.9（Qt Quick 2.9）起，可以创建一个支持双向滑动的 ListView。 要实现这一点，可将flickableDirection 设置为Flickable.AutoFlickDirection或 Flickable.AutoFlickIfNeeded，并必须提供所需的内容宽度（contentWidth）或内容高度（contentHeight）。

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

ListView 中的堆叠顺序

项目的Z value 值决定了它们是在其他项目上方还是下方渲染。ListView会根据创建的项目类型使用几种不同的默认Z值：

如果该项的Z值为0 ，则会采用这些默认值，因此将这些项的Z值设置为0 将不会产生任何效果。请注意，Z值的类型为real ，因此可以设置小数值，例如0.1 。

项的复用

自 5.15 版本起，ListView 可以配置为在通过轻扫将新行滑入视图时，复用现有项，而不是从delegate 重新实例化。根据委托的复杂程度，这种方法可以提高性能。出于向后兼容性的考虑，项的复用功能默认处于关闭状态，但可以通过将reuseItems 属性设置为true 来启用。

当项目被滑出视图时，它会被移至重用池——这是一个存放未使用项目的内部缓存。此时，会发出ListView::pooled 信号以通知该项目。同样地，当项目从重用池移回视图时，会发出ListView::reused 信号。

当项被重用时，所有源自模型的项属性都会被更新。这包括 `index ` 和 `row`，同时也包括任何模型角色。

如果项包含定时器或动画，请考虑在接收到ListView::pooled 信号时暂停它们。这样可以避免为不可见的项消耗CPU资源。同样，如果项包含无法复用的资源，可以将其释放。

以下示例展示了一个用于动画化旋转矩形的委托。当该矩形被放入池中时，动画会暂时暂停：

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
            }
        }
    }
}

可变委托大小与分区标签

可变的委托大小可能会导致重新调整大小，并导致任何附加的ScrollBar 被跳过。这是因为ListView根据已分配的项目（通常仅限于可见项目，其余项目被假定为大小相似）来估算其内容大小，而可变的委托大小会妨碍准确估算。 为减轻此影响，可将cacheBuffer 设置为较大值，这会有效生成更多项目并改善未分配项目的大小估算，但会消耗额外的内存。Sections 具有相同效果，因为它们会将分区标签附加并延伸至该分区内的第一个项目。

避免在委托中存储状态

ListView 的委托会按需实例化，并在超出视图范围时被销毁。要了解这一点，请运行以下示例：

ListView {
    anchors.fill: parent
    model: 3
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)

        required property int index
        property bool channelActivated

        onClicked: channelActivated = checked
    }
}

当点击某项时，channelActivated 会被设置为true 。然而，由于委托可能被reused 并销毁，当视图移动到足够远的位置时，所有状态都会丢失。当委托再次可见时，它将恢复其默认的、未修改的状态（或者，如果是被重用的项，则恢复来自前一个项的旧状态）。

为避免这种情况，应将状态存储在模型中：

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement {
            channelActivated: true
        }
        // ...
    }
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)
        checked: model.channelActivated

        required property int index
        required property var model

        onClicked: model.channelActivated = checked
    }
}

隐藏委托

将委托的 `visible ` 属性设置为 `false ` 将隐藏该项，但其在视图中占用的空间将保留。可以将该项的 `height ` 属性设置为 `0 `（对于vertical 的 ListView）：

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement { hidden: false }
        ListElement { hidden: false }
        ListElement { hidden: false }
        // ...
    }
    delegate: ItemDelegate {
        text: qsTr("Item %1").arg(index)
        visible: !model.hidden
        height: visible ? implicitHeight : 0

        required property int index
        required property var model

        onClicked: model.hidden = true
    }
}

请注意，隐藏状态会存储在模型中，这遵循了Avoid Storing State in Delegates 部分中的建议。

但是，如果spacing 不为零，委托之间会出现间距不均的情况。

更好的做法是通过过滤模型，确保不应显示的项目根本不会被视图加载。这可以通过 `QSortFilterProxyModel` 实现。

另一种方法是使用disable 处理委托对象，而不是将其隐藏。

另请参阅 QML 数据模型、GridView 、PathView 以及Qt Quick 示例 - 视图。

属性文档

add : Transition

该属性用于指定要应用于添加到视图中的项的过渡效果。

例如，以下是一个指定此类转场的视图：

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

每当有项目被添加到上述视图中时，该项目将从位置 (100,100) 开始，在 1 秒内通过动画过渡到其在视图内的最终 x、y 位置。 该过渡效果仅适用于新添加到视图中的项；对于因新增项而被挤出位置的下方项，该效果不适用。若要对被挤出的项进行动画处理，请设置 `displaced ` 或 `addDisplaced ` 属性。

有关如何使用视图过渡的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 addDisplaced 、populate 以及ViewTransition 。

addDisplaced : Transition

该属性用于指定当视图中因添加其他项目而导致现有项目位置发生偏移时，应应用于这些项目的过渡效果。

例如，以下是一个指定此类过渡效果的视图：

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

每当向上述视图中添加一个项目时，新项目下方的所有项目都会被挤出，导致它们在视图内向下移动（如果是水平方向的视图，则向侧面移动）。 当发生这种位移时，项目在视图内移动至新 x、y 位置的过程将按照指定设置，通过“NumberAnimation ”过渡效果在 1 秒内完成动画显示。此过渡效果不适用于新添加到视图中的项目；若要为新增项目添加动画效果，请设置 `add ` 属性。

如果一个项目同时受到多种操作的位移影响，则无法确定将应用 addDisplaced、moveDisplaced 还是removeDisplaced 过渡效果。此外，如果无需根据项目是因添加、移动还是移除操作而发生位移来指定不同的过渡效果，建议改设displaced 属性。

有关如何使用视图过渡的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 displaced 、add 、populate 以及ViewTransition 。

cacheBuffer : int

此属性用于确定是否在视图的可见区域之外保留委托对象。

如果该值大于零，视图可能会保留尽可能多的委托实例，直到其数量填满指定的缓冲区为止。例如，如果在一个垂直视图中，委托的高度为 20 像素，且 `cacheBuffer ` 设置为 40，那么在可见区域上方和下方最多可能分别创建/保留 2 个委托。 缓冲的委托对象会异步创建，从而允许在多个帧内进行创建，并降低跳帧的可能性。为了提高绘制性能，可见区域外的委托对象不会被绘制。

该属性的默认值取决于平台，但通常为大于零的数值。负值将被忽略。

请注意，cacheBuffer 并非像素缓冲区——它仅用于维护额外的已实例化代理。

cacheBuffer 的作用范围不包括由 `displayMarginBeginning ` 或 `displayMarginEnd` 指定的任何显示边距。

count : int [read-only]

该属性反映了“ListView ”模型中的项的数量，无论这些项是否可见，或是否作为委托组件的Item 被实例化。

currentIndex 属性保存当前项的索引，currentItem 保存当前项。将currentIndex 设置为 -1 将清除高亮并使currentItem 变为 null。

如果highlightFollowsCurrentItem 等于true ，则设置其中任何一个属性都会使ListView 平滑滚动，以便当前项目进入可见范围。

请注意，在当前项目在视图中可见之前，其位置可能只是近似值。

由于currentItem 需要与任何委托配合使用，因此其类型为Item 。不过，ListView 通常仅与一种类型的委托配合使用。在这种情况下，将currentItem 强制转换为委托的类型有助于工具辅助开发，并能提高代码效率：

component Message : Item {
    required property string sender
    required property string text
}
ListView {
    id: messageView
    delegate: Message {}
    model: messageModel
}
Button {
    text: "Reply to %1".arg((messageView.currentItem) as Message).sender
}

currentSection : string [read-only]

该属性存储当前位于视图开头的段。

delegate : Component

该委托提供了一个模板，用于定义由视图实例化的每个项目。索引作为可访问的index 属性对外暴露。根据数据模型的类型，模型的属性也可供使用。

委托中的对象和绑定数量会直接影响视图的翻动性能。如果可能的话，请将委托中正常显示所不需要的功能放置在Loader 中，该 可在需要时加载额外的组件。

ListView 将根据委托中根项的大小来布局各项。

建议将委托的大小设置为整数，以避免项目出现亚像素对齐的情况。

委托实例的默认stacking order 是1 。

另请参阅 Stacking Order in ListView 。

delegateModelAccess : enumeration [since 6.10]

此属性决定了委托如何访问模型。

默认值为 `DelegateModel.Qt5ReadWrite`。

该属性在 Qt 6.10 中引入。

另请参阅 《Qt Quick 中的模型和视图》#更改模型数据。

displaced : Transition

该属性存储了要应用于因任何影响视图的模型操作而被替换的项目的通用过渡。

这为指定应用于因添加、移动或移除操作而被位移的任何项的通用过渡提供了便利，无需分别指定addDisplaced 、moveDisplaced 和removeDisplaced 属性。例如，以下视图指定了位移过渡：

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

当上述视图中添加、移动或移除任何项目时，其下方的项目会被挤出，导致它们在视图内向下移动（如果是水平方向的视图，则向侧面移动）。当发生这种位移时，项目向视图内新的 x、y 位置的移动将按照指定，通过NumberAnimation 过渡效果在 1 秒内完成动画效果。

如果一个视图既指定了此通用位移过渡，又指定了具体的addDisplaced 、moveDisplaced 或removeDisplaced 过渡，那么在发生相关操作时，系统将使用更具体的过渡（而非通用位移过渡），前提是该更具体的过渡未被禁用（通过将enabled 设置为false）。如果该过渡确实已被禁用，则会应用通用位移过渡。

有关如何使用视图转换的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 addDisplaced 、moveDisplaced 、removeDisplaced 以及ViewTransition 。

此属性允许在视图几何范围之外显示委托对象。

如果该值不为零，视图将在视图起始位置之前或结束位置之后创建额外的委托。视图将创建尽可能多的委托，直到其数量达到指定像素大小所能容纳的上限。

例如，如果在垂直视图中，委托的高度为 20 像素，且 `displayMarginBeginning ` 和 `displayMarginEnd ` 均设置为 40，则将在上方和下方各创建并显示 2 个委托。

默认值为 0。

此属性旨在支持特定的 UI 配置，而非用于性能优化。如果您出于性能考虑希望在视图几何范围之外创建委托，建议改用cacheBuffer 属性。

这些属性是在 QtQuick 2.3 中引入的。

effectiveLayoutDirection : enumeration [read-only]

该属性用于指定水平布局列表的有效布局方向。

当使用附加属性 `LayoutMirroring::enabled ` 进行区域设置布局时，水平列表的视觉布局方向将被镜像。但是，属性 `layoutDirection ` 将保持不变。

另请参阅 ListView::layoutDirection 和LayoutMirroring 。

footer : Component

该属性用于指定用作页脚的组件。

每个视图都会创建一个页脚组件的实例。页脚位于视图末尾，在所有项目之后。页脚的默认stacking order 为1 。

另请参阅 header 、footerItem 和Stacking Order in ListView 。

footerItem : Item [read-only]

此处包含由footer 组件生成的页脚项。

每个视图都会创建一个页脚组件的实例。页脚位于视图末尾，在所有项目之后。页脚的默认stacking order 为1 。

另请参阅 footer 、headerItem 和Stacking Order in ListView 。

footerPositioning : enumeration [since Qt 5.4]

此属性用于确定footer item 的位置。

该属性在 Qt 5.4 中引入。

header : Component

该属性用于指定用作页眉的组件。

每个视图都会创建一个标题组件的实例。标题位于视图的开头，在任何项目之前。标题的默认stacking order 为1 。

另请参阅 footer 、headerItem 和Stacking Order in ListView 。

headerItem : Item [read-only]

此处存放由header 组件生成的标题项。

每个视图都会创建一个标题组件的实例。标题位于视图的开头，在所有项目之前。标题的默认stacking order 为1 。

另请参阅 header 、footerItem 和Stacking Order in ListView 。

headerPositioning : enumeration [since Qt 5.4]

此属性用于确定header item 的位置。

该属性在 Qt 5.4 中引入。

highlight : Component

该属性用于指定用作高亮效果的组件。

每个列表都会创建一个高亮组件的实例。生成的组件实例的几何属性由列表管理，以确保其始终与当前项目保持同步，除非highlightFollowsCurrentItem 属性设置为false。高亮项的默认stacking order 为0 。

另请参阅 highlightItem 、highlightFollowsCurrentItem 、ListView 高亮示例以及Stacking Order in 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 [read-only]

此处保存了由highlight 组件生成的高亮项。

除非将 `highlightFollowsCurrentItem ` 设置为 `false`，否则 `highlightItem ` 由视图管理。高亮项的默认 `stacking order ` 为 `0`。

另请参阅 highlight 、highlightFollowsCurrentItem 和Stacking Order in ListView 。

这些属性控制高亮委托的移动和调整大小动画的速度。

highlightFollowsCurrentItem 这些属性必须设置为 true 才能生效。

速度属性的默认值为 400 像素/秒。持续时间属性的默认值为 -1，即高亮将花费必要的时间以设定的速度移动。

这些属性与SmoothedAnimation 具有相同的特性：如果同时设置了velocity和duration，动画将采用两者中持续时间较短的那一个。

“移动速度”和“持续时间”属性用于控制因索引变化而产生的移动；例如，在调用 `incrementCurrentIndex()` 时。当用户轻扫 `ListView` 时，则使用轻扫产生的速度来控制移动。

若仅需设置其中一个属性，则可将另一个属性设为-1 。例如，若仅需对持续时间进行动画效果而无需调整速度，请使用以下代码：

highlightMoveDuration: 1000
highlightMoveVelocity: -1

另请参阅 highlightFollowsCurrentItem 。

这些属性定义了视图中（当前项目）高亮显示的首选范围。preferredHighlightBegin 的值必须小于preferredHighlightEnd 的值。

这些属性会影响列表滚动时当前项的位置。例如，如果希望在视图滚动时当前选中的项始终位于列表中间，请将preferredHighlightBegin 和preferredHighlightEnd 的值分别设置为中间项所在位置的顶部和底部坐标。 如果通过编程方式更改了currentItem ，列表将自动滚动，使当前项目位于视图中央。此外，无论是否存在高亮标记，当前项目索引的行为都会生效。

highlightRangeMode 的有效值包括：

keyNavigationEnabled : bool

该属性用于控制列表的键盘导航功能是否启用。

如果该属性值为true ，则用户可以使用键盘在视图中进行导航。这对于需要选择性地启用或禁用鼠标和键盘交互的应用程序非常有用。

默认情况下，该属性的值与interactive 绑定，以确保与现有应用程序的行为兼容。当显式设置时，它将不再与interactive属性绑定。

另请参阅 interactive 。

keyNavigationWraps : bool

该属性用于指定列表是否在键导航时进行循环。

如果该属性为真，原本会将当前选中项移动到列表末尾之后的键导航操作，将转为循环至列表开头，反之亦然。

默认情况下，键导航不会循环。

layoutDirection : enumeration

此属性用于指定水平布局列表的布局方向。

可能的取值：

如果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

该属性用于指定在视图的model 中，由移动操作导致的项目位移应应用的过渡效果。

例如，以下是一个指定此类过渡的视图：

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

每当model 执行移动操作以移动特定索引集合时，位于该移动操作源索引与目标索引之间的项目会被位移，导致它们在视图内向上或向下移动（若为水平方向，则向侧面移动）。 当发生这种位移时，项目向视图内新 x、y 位置的移动将按照指定，通过NumberAnimation 在1秒内完成动画效果。此过渡效果不适用于移动操作的实际目标项目；若要为已移动的项目添加动画，请设置move 属性。

如果一个项目同时受到多种类型操作的位移，则未明确规定将应用addDisplaced 、moveDisplaced还是removeDisplaced 过渡效果。此外，如果无需根据项目是由添加、移动还是移除操作引起的位移来指定不同的过渡效果，建议改设displaced 属性。

有关如何使用视图过渡的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 displaced 、move 以及ViewTransition 。

orientation : enumeration

该属性用于指定列表的排列方向。

可能的取值：

常量	描述
ListView.Horizontal	项目水平排列
ListView.Vertical	（默认）项目垂直排列

另请参阅 Flickable Direction 。

populate : Transition

此属性用于指定应应用于视图中初始创建的项目的过渡效果。

当出现以下情况时，该过渡将应用于所有创建的项：

• 首次创建视图时
• 视图的model 发生变化，导致可见的委托被完全替换
• 当视图的model 为reset 时（若模型是QAbstractItemModel 的子类）

例如，以下是一个指定此类过渡的视图：

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

当视图初始化时，视图将创建所有必要的项目，然后在1秒内通过动画将它们移动到视图内的正确位置。

然而，随后在滚动视图时，“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 附加属性，则“移除”过渡效果将不会应用，直到delayRemove 再次变为false为止。

有关如何使用视图转换的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 removeDisplaced 和ViewTransition 。

removeDisplaced : Transition

该属性用于指定当视图中的其他项目被移除时，应应用于因移除而位置发生变化的视图中项目的过渡效果。

例如，以下是一个指定此类过渡效果的视图：

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

每当从上述视图中移除一个项目时，其下方的所有项目都会发生位移，导致它们在视图内向上移动（如果是水平方向的视图，则向侧面移动）。 当发生这种位移时，项目在视图内移动至新的 x、y 位置的过程将按照指定设置，通过“NumberAnimation ”过渡效果在 1 秒内完成动画显示。此过渡效果不适用于实际从视图中移除的项目；若要为被移除的项目添加动画效果，请设置remove 属性。

如果一个项目同时受到多种操作的位移影响，则未明确规定应应用addDisplaced 、moveDisplaced 还是removeDisplaced过渡效果。此外，如果无需根据项目是受添加、移动还是移除操作影响而指定不同的过渡效果，建议改设displaced 属性。

有关如何使用视图过渡的更多详细信息和示例，请参阅ViewTransition 文档。

另请参阅 displaced 、remove 以及ViewTransition 。

reuseItems : bool

此属性允许您重用从delegate 实例化的项目。如果将其设置为false ，则会销毁当前池中的所有项目。

该属性的默认值为false 。

另请参阅 Reusing items 、pooled() 和reused()。

section group

这些属性决定了待求值的表达式以及章节标签的显示形式。

section.property 包含作为每个章节基础的属性名称。

section.criteria 包含基于section.property 形成各部分的标准。该值可以是以下之一：

确定分区边界时采用不区分大小写的比较方式。

section.delegate 包含每个部分的委托组件。部分委托实例的默认stacking order 为2 。如果您在其中声明了一个名为“section”的required 属性，该属性将包含该部分的标题。

section.labelPositioning 用于确定当前和/或下一个章节标签是否紧贴视图的起始/结束位置，以及标签是否以内联方式显示。该值可以是以下选项的组合：

列表中的每个项目都附有名为ListView.section 、ListView.previousSection 和ListView.nextSection 的属性。

例如，以下是一个将动物列表按部分划分的“ListView ”。ListView 中的每个项目都会根据模型项的“size”属性被放置在不同的部分中。sectionHeading 委托组件提供了标记每个部分起点的浅蓝色条。

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: ListView.view.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 示例和Stacking Order in ListView 。

snapMode : enumeration

此属性决定了在拖动或轻扫操作后，视图滚动将如何稳定下来。可选值包括：

snapMode 不影响currentIndex 。若要在列表移动时更新currentIndex ，请将highlightRangeMode 设置为ListView.StrictlyEnforceRange 。

另请参阅 highlightRangeMode 。

spacing : real

该属性控制项目之间的间距。

默认值为 0。

verticalLayoutDirection : enumeration

此属性用于指定垂直排列列表的布局方向。

可能的取值：

如果orientation 为Qt.Horizontal，则设置此属性无效。

另请参阅 ListView::layoutDirection 。

附加属性文档

ListView.delayRemove : bool [attached]

此附加属性用于指定委托是否可以被销毁。它附加在委托的每个实例上。默认值为 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 : bool [read-only attached]

如果该委托是当前项，则此附加属性为 true；否则为 false。

它附加在每个委托实例上。

该属性可用于调整当前项的外观，例如：

ListView {
    width: 180; height: 200

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

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

ListView.nextSection : string [read-only attached]

此附加属性保存下一个元素的段落。

它附加在委托的每个实例上。

该部分通过section 属性进行评估。

ListView.previousSection : string [read-only attached]

此附加属性保存了前一个元素的片段。

它附属于委托的每个实例。

该片段通过section 属性进行评估。

ListView.section : string [read-only attached]

此附加属性保存了该元素的段落内容。

它附加在委托的每个实例上。

该部分通过section 属性进行评估。

ListView.view : ListView [read-only attached]

该附加属性保存了管理此委托实例的视图。

它附加在每个委托实例上，同时也附加在页眉、页脚、章节和突出显示委托上。

“Attached Signal”文档

[attached] add()

当项目被添加到视图后，会立即触发此附加信号。

如果指定了添加过渡效果，则会在处理此信号后立即应用该过渡效果。

[attached] pooled()

当一个项被添加到重用池后，会触发此信号。您可以利用它来暂停该项内部正在运行的计时器或动画，或者释放无法重用的资源。

仅当reuseItems 属性为true 时，才会发出此信号。

另请参阅 Reusing items 、reuseItems 以及reused()。

[attached] remove()

当视图中某项内容被移除之前，会立即触发此附加信号。

如果已指定移除过渡效果，则在处理此信号后应用该过渡效果，前提是delayRemove 为false。

[attached] reused()

该信号在项目被重用后触发。此时，该项目已被从资源池中取出并放入内容视图中，且模型属性（如index 和row ）已更新。

当项目被复用时，模型未提供的其他属性不会发生变化。您应避免在委托内部存储任何状态，但如果确实存储了，请在接收到此信号时手动重置该状态。

该信号在项目被重用时发出，而非项目首次创建时。

只有当reuseItems 属性为true 时，才会发出此信号。

另请参阅 Reusing items 、reuseItems 和pooled()。

方法文档

void decrementCurrentIndex()

将当前索引递减。如果keyNavigationWraps 为true且当前索引位于起始位置，则当前索引将回环。如果count 为零，则此方法无效。

注意：仅应在组件（Component）完成加载后才调用这些方法。

void forceLayout()

对模型变化的响应通常以批处理方式进行，每帧仅执行一次。这意味着在脚本块内部，底层模型可能已经发生变化，但ListView 尚未更新。

此方法会强制ListView 立即响应模型中任何未处理的变更。

注意：应在组件（Component）处理完成后才调用这些方法。

void incrementCurrentIndex()

将当前索引递增。如果keyNavigationWraps 为true且当前索引已到达末尾，则当前索引将回环。如果count 为零，则此方法无效。

注意：仅应在组件（Component）完成加载后才调用这些方法。

int indexAt(real x, real y)

返回包含点x 、y （以内容坐标计）的可见项的索引。如果指定点处不存在项，或者该项不可见，则返回 -1。

如果该项目位于可见区域之外，则返回 -1，无论在滚动至该位置时该处是否存在项目。

注意：仅应在组件完成加载后才调用这些方法。

Item itemAt(real x, real y)

返回包含坐标x 、y （以内容坐标系计）的可见项目。如果指定位置不存在项目，或者该项目不可见，则返回null。

如果该项目位于可见区域之外，则返回 null，无论滚动至该位置时该处是否存在项目。

注意：仅应在组件完成加载后才调用这些方法。

Item itemAtIndex(int index)

返回index 对应的项。如果该索引下没有对应的项（例如，因为该项尚未创建，或者因平移操作已超出可见区域并从缓存中移除），则返回null。

注意：此方法仅应在组件完成加载后调用。此外，不应存储返回值，因为一旦控件超出调用作用域，如果视图释放了该项，返回值可能会立即变为 null。

将视图定位在开头或结尾，同时考虑任何页眉或页脚。

不建议使用 `contentX ` 或 `contentY ` 方法将视图定位在特定索引位置。此方法不可靠，因为从列表开头删除项目不会导致所有其他项目重新定位，而且视图的实际起始位置可能会因委托对象的大小而有所不同。

注意：仅应在组件完成加载后调用这些方法。若要在启动时定位视图，应由 Component.onCompleted 调用此方法。例如，要在启动时将视图定位到末尾：

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

将视图定位，使index 位于mode 指定的位置：

如果将视图定位在index 会导致视图开头或结尾处显示空白区域，则视图将定位在边界处。

不建议使用contentX 或contentY 将视图定位到特定索引位置。这种做法不可靠，因为从列表开头删除项目不会导致所有其他项目重新定位，而且视图的实际起始位置可能会因委托对象的大小而变化。将项目纳入视图的正确方法是使用positionViewAtIndex 。

注意：这些方法应仅在 Component 完成加载后调用。若要在启动时定位视图，应由 Component.onCompleted 调用此方法。例如，若要将视图定位在末尾：

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