列表视图 QML 类型

currentIndex属性持有当前项目的索引，而currentItem持有当前项目。将currentIndex设置为-1将清除高亮并设置currentItem为null。

如果highlightFollowsCurrentItem设置为true，则设置这两个属性中的任何一个都会平滑地滚动ListView，以便当前项目变为可见。

请注意，当前项目在变为可见之前，其位置只能近似。

这些属性定义了在视图内当前项高亮的偏好范围。必须使preferredHighlightBegin值小于preferredHighlightEnd值。

这些属性影响滚动列表时当前项的位置。例如，如果当前选择的项在滚动视图时应该保持在列表的中间，则将preferredHighlightBegin和preferredHighlightEnd值设置为中间项目应有的顶部和底部坐标。如果通过编程方式更改currentItem，则列表将自动滚动，以便当前项目位于视图的中间。此外，无论是否存在高亮显示，都会发生当前项索引的行为。

highlightRangeMode的有效值是

此属性允许委托在外部视图几何中显示。

如果此值为非零，则视图将在视图开始之前或之后创建额外委托。视图将根据指定的像素大小创建尽可能多的委托。

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

默认值是0。

此属性旨在允许某些UI配置，而非作为性能优化。如果您出于性能原因希望在视图几何形状之外创建代理，那么可能需要使用 cacheBuffer 属性。

此QML属性是在QtQuick 2.3中引入的。

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

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

速度属性的默认值是400像素/秒。持续时间属性的默认值是-1，即高亮将根据所需的速度所需的时间移动。

这些属性具有与 SmoothedAnimation 相同的特点：如果同时设置了速度和持续时间，动画将使用较短的那个。

移动速度和持续时间属性用于控制由于索引变化引起的移动；例如，当调用 incrementCurrentIndex() 时。当用户在 ListView 中滑动手势时，将使用滑动手势的速度来控制移动。

要设置单个属性，其他可以设置为 -1。例如，如果您只想动画化持续时间而不是速度，请使用以下代码

highlightMoveDuration: 1000
highlightMoveVelocity: -1

另请参阅 highlightFollowsCurrentItem。

此属性包含应用于添加到视图中的项的转换。

例如，以下是指定此类转换的视图

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

每当向上述视图中添加项时，项将从（100，100）位置动画到视图中最终的x,y位置，持续一秒钟。此转换仅适用于添加到视图中的新项；它不会应用于由于添加新项而错位的新项。要动画化移位的项，请设置 displaced 或 addDisplaced 属性。

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

另请参阅 addDisplaced、populate 和 ViewTransition。

此属性控制应用于视图中通过添加其他项目引起的位移的项目过渡。

例如，以下是指定此类转换的视图

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

每次向上述视图中添加项目时，新的项目下面的所有项目都将被替换位置，从而导致它们在视图中向下（或如果水平排列则向侧）移动。当发生这种替换时，项目将以其指定的1秒动画移动到视图中新的x,y位置。此过渡不应用于已添加到视图中的新项目；要为添加的项目设置动画，请设置属性。

如果一个项目同时被多种操作所位移，无法定义应用addDisplaced、还是过渡。此外，如果不需要根据一个项目是因添加、移动还是删除操作而产生的位移指定不同的过渡，请考虑设置属性。

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

另请参阅 、、和。

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

如果此值大于零，视图可以保留尽可能多的委托，这些委托可以在指定的缓冲区中适应。例如，如果在一个垂直视图中，委托的高度是20像素，并且将cacheBuffer设置为40，则可能创建并保留直到可见区域上方和下方的2个委托。缓冲的委托异步创建，允许在多个帧之间进行创建，从而减少跳帧的可能性。为了提高绘制性能，Outside the visible area are not painted.

此属性的默认值依赖于平台，但通常将是一个大于零的值。负值将被忽略。

请注意，cacheBuffer不是一个像素缓冲区-它仅维护额外的已实例化委托。

cacheBuffer在由或指定的任何显示边距之外运行。

此属性包含模型中的项目数量。

此属性包含视图开始处的部分。

代理提供了定义由视图实例化的每个项目的模板。索引作为可访问的 index 属性公开。模型属性也根据 数据模型 的类型可用。

代理中的对象和绑定的数量直接影响视图的翻页性能。如果可能的话，将不是用于代理正常显示的功能放在可动态加载组件的 Loader 中。

视图将根据代理中的根项的大小来排列项目。

推荐将代理的大小设置为整数，以避免项目的亚像素对齐。

代理实例的默认堆叠顺序是 1。

另见 ListView 中的堆叠顺序。

此属性包含应用由影响视图的任何模型操作位移的项目的新通用的转换。

这是指定应用任何添加、移动或删除操作的项目的通用转换的便利方式，而无需指定单个 addDisplaced、moveDisplaced 和 removeDisplaced 属性。例如，以下是一个指定位移转换的视图

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

当任何项目在上述视图内部添加、移动或删除时，其下的项目会被位移，导致它们在视图内向下（或如果水平排列则向侧）移动。在位移发生时，项目将根据指定的转换动画 movement 在一秒的时间内将它们移动到新 x，y 位置。

如果视图指定了此通用位移转换以及特定的 addDisplaced、moveDisplaced 或 removeDisplaced 转换，那么在相关操作发生时，将使用更具体的转换而不是通用位移转换，前提是这个更具体的转换没有被禁用（通过将 enabled 设置为 false）。如果确实被禁用了，则应用通用位移转换。

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

另见 addDisplaced、moveDisplaced、removeDisplaced 和 ViewTransition。

此属性包含水平列的有效布局方向。

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

另见 ListView::layoutDirection 和 LayoutMirroring。

此属性包含用作页脚的组件。

为每个视图创建一个页脚组件的实例。页脚位于视图末尾，任何项之后。页脚的默认堆叠顺序是1。

参见头部、页脚项和ListView中的堆叠顺序。

这包含了从页脚组件创建的页脚项。

为每个视图创建一个页脚组件的实例。页脚位于视图末尾，任何项之后。页脚的默认堆叠顺序是1。

参见页脚、头部项和ListView中的堆叠顺序。

此属性确定页脚项的位置。

此属性自Qt 5.4引入。

此属性包含要使用的头部组件。

为每个视图创建一个头部组件的实例。头部位于视图的开始位置，在各项之前。头部默认的堆叠顺序是1。

参见页脚、头部项和ListView中的堆叠顺序。

这包含了从头部组件创建的头部项。

为每个视图创建一个头部组件的实例。头部位于视图的开始位置，在各项之前。头部默认的堆叠顺序是1。

参见头部、页脚项和ListView中的堆叠顺序。

此属性确定头部项的位置。

此属性自Qt 5.4引入。

此属性用于指定用作高亮的组件。

为每个列表创建一个高亮组件实例。结果组件实例的几何形状由列表管理，以保持在当前项目，除非 highlightFollowsCurrentItem 属性为 false。高亮项目的默认 堆叠顺序 为 0。

另请参阅highlightItem、highlightFollowsCurrentItem、ListView Highlight Example 以及 ListView 中的堆叠顺序。

此属性表示高亮是否由视图管理。

如果此属性为真（默认值），则高亮会平滑移动以跟随当前项目。否则，视图不会移动高亮，任何移动都必须由高亮实现。

以下是具有定义动力的高亮的示例，动力由一个 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。

此属性保存从 highlight 组件创建的高亮项目。

除非 highlightFollowsCurrentItem 设置为 false，否则 highlightItem 由视图管理。高亮项目的默认 堆叠顺序 为 0。

另请参阅highlight、highlightFollowsCurrentItem 以及 ListView 中的堆叠顺序。

此属性表示是否启用了列表的关键导航。

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

默认情况下，此属性的值绑定到 interactive，以确保与现有应用程序的行为兼容。当明确设置时，将不再绑定到交互属性。

另请参阅interactive。

此属性表示是否启用列表的键导航循环。

如果为真，则键导航会将当前项目选择移动到列表末尾，反之亦然。

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

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

可能值

如果 布局方向 是 Qt.Vertical，则设置此属性将没有效果。

另请参阅

此属性持有为列表提供数据的模型。

模型提供了用于创建视图项的数据集。模型可以直接在 QML 中通过 ListModel、ObjectModel 或 C++ 模型类提供。如果使用 C++ 模型类，它必须是 QAbstractItemModel 的子类或一个简单的列表。

另请参阅 数据模型。

此属性持有应用于视图项的转换，这些项因视图的 模型 中的移动操作而被移动。

例如，以下是指定此类转换的视图

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

每当模型执行移动操作以移动一组特定索引时，视图中的相应项将动画化到其在视图中的新位置，持续一秒钟。此转换仅适用于模型中移动操作的主题项；它不应用于被移动操作所推挤的项。要动画化推挤项，请设置 displaced 或 moveDisplaced 属性。

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

另请参阅 moveDisplaced 和 ViewTransition。

此属性持有应用于由视图的 模型 中的移动操作所移位的项的转换。

例如，以下是指定此类转换的视图

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

每当模型执行移动操作以移动一组特定索引时，移动操作源索引和目标索引之间的项将被移位，导致它们在视图内向上、向下（或如果水平对齐，则向侧）移动。在此位移发生时，项将按照指定的动画移动到其视图内的新 x,y 位置，持续一秒钟。此转换不应用于实际移动操作的主题项；要动画化被移动的项，请设置 move 属性。

如果项同时被多种类型的操作移位，没有定义 addDisplaced、moveDisplaced 或 removeDisplaced 转换是否应用。此外，如果不需要根据项是否由添加、移动或删除操作所移位而指定不同的转换，请考虑设置 displaced 属性。

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

另请参阅 displaced、move 和 ViewTransition。

此属性持有列表的方向。

可能值

常数	描述
ListView.Horizontal	项目将在水平方向上排列
ListView.Vertical	（默认）项目将在垂直方向上排列

另请参阅 Flickable Direction。

该属性用于存储应用于视图初始化时创建的项目上的转换。

当以下情况发生时应用此转换：

• 视图首次创建时
• 视图的 模型 发生变化，使得可见的代理被完全替换
• 视图的 模型 是 重置 的，如果模型是 QAbstractItemModel 子类

例如，以下是指定此类转换的视图

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

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

然而，当稍后滚动视图时，填充转换不会运行，即使当项目变得可见时会实例化代理。在模型以使新代理变得可见的方式发生变化时，将运行 添加 转换。因此，您不应该依赖 填充 转换来初始化代理中的属性，因为这不适用于每个代理。如果您的动画设置了属性的 to 值，则属性最初应该具有 to 值，并且动画应该设置 case 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 文档。

另请参阅 添加 和 视图转换。

此属性包含应用于从视图中移除的项目上的转换。

例如，以下是指定此类转换的视图

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 和 视图转换。

此属性包含应用于由视图中其他项目移除而位移的项目上的转换。

例如，以下是指定此类转换的视图

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

每次从上述视图中移除项目时，其下方的所有项目都会被位移，使它们在视图中向上（如果是水平方向，则为向侧面）移动。在此位移发生时，项目的移动将在一秒内通过 NumberAnimation 动画到视图中新的 x,y 位置。此转换不应用于实际上已从视图中移除的项目；要动画移除的项目，请设置 移除 属性。

如果一个项目同时被多种类型的操作移位，则无法确定是否应用addDisplaced、moveDisplaced或removeDisplaced过渡。另外，如果不需要根据是否由添加、移动或删除操作来指定不同的过渡，请考虑设置displaced属性。

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

另请参阅 displaced、remove和ViewTransition。

此属性允许您重复使用从delegate实例化的项目。如果设置为false，则任何当前池化的项目都将被销毁。

此属性默认为false。

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

这些属性确定要评估的表达式和部分标签的外观。

section.property包含每个部分的基础属性名称。

section.criteria包含基于section.property形成每个部分的准则。此值可以是以下之一

在确定部分边界时使用不区分大小写的比较。

section.delegate包含每个部分的委托组件。部分委托实例的默认堆叠顺序为2。如果在其中声明名为"section"的required属性，则该属性将包含部分的标题。

section.labelPositioning确定当前部分标签/或下一部分标签是否粘附到视图的开始/或结束，以及标签是否显示为内联。此值可以是以下组合

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

例如，这里是一个ListView，它显示一系列动物，并分为不同的部分。根据模型项的"size"属性，ListView中的每个项都放置在不同的部分中。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示例和ListView的堆叠顺序。

此属性确定拖动或轻扫后视图滚动将如何停止。可能的值有

snapMode不会影响currentIndex。要更新currentIndex以在移动列表时， 设置highlightRangeMode到ListView.StrictlyEnforceRange。

另请参阅 highlightRangeMode。

该属性包含项目之间的间隔。

默认值是0。

该属性持有垂直方向的列表布局方向。

可能值

如果orientation是Qt.Horizontal，则设置此属性无影响。

另请参阅 ListView::layoutDirection。

此附加属性保留是否可以销毁代理。它附加到附加代理的每个实例上。默认值为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，转换才会应用。

如果此代理是当前项则此附加属性为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
}

此附加属性保留下一个元素的标签。

该属性附加到每个代理的实例。

标签是使用section属性来评估的。

该附加属性保存前一个元素的节。

该属性附加到每个代理的实例。

标签是使用section属性来评估的。

该附加属性保存此元素的节。

该属性附加到每个代理的实例。

标签是使用section属性来评估的。

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

它附加到每个委托实例，还包括表头、页脚、节和突出显示委托。

此附加信号在一个项目添加到视图后立即发出。

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

在该项目被添加到循环池之后发出此信号。您可以使用它暂停该项目内的事件或动画，或者释放无法重复使用的资源。

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

另请参阅：重复使用项目、reuseItems 和 reused。

在项目从视图中删除之前立即发出此附加信号。

如果指定了删除过渡，则在处理该信号之后应用过渡，前提是 delayRemove 为 false。

在项目被重复使用之后发出此信号。在此点，该项目已被从池中取出并放置在内容视图中，并且已更新了模型属性，如 index 和 row。

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

当项目被重复使用时发出此信号，而不是第一次创建项目时。

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

另请参阅：重复使用项目、reuseItems 和 pooled。

根据任何表头或页脚定位视图的起始或结束位置。

不建议使用 contentX 或 contentY 在特定索引处定位视图。这是不可靠的，因为从列表的开始位置删除项目不会导致所有其他项目重新定位，并且由于视图的实际起始点可能根据委托的大小而变化。

注意：应该在组件完成之后调用方法。要启动时定位视图，应通过 Component.onCompleted 调用此方法。例如，要启动时将视图定位到末尾

Component.onCompleted: positionViewAtEnd()

递减当前索引。如果 keyNavigationWraps 为 true 且当前位于起始处，则当前索引将循环。如果 count 为零，则此方法不起作用。

注意：应该在组件完成之后调用方法。

对模型变化的响应通常批量处理，以确保仅在每帧发生一次。这意味着，在脚本块内部，底层模型可能已经发生变化，而 ListView 尚未跟上。

此方法强制ListView立即响应模型中悬而未决的任何更改。

注意：应该在组件完成之后调用方法。

增加当前索引。如果keyNavigationWraps为true且当前处于末尾，则当前索引将进行回滚。如果count为零，则此方法无作用。

注意：应该在组件完成之后调用方法。

返回包含内容坐标中点x、y的可见项的索引。如果没有项位于指定的点，或者项不可见，则返回-1。

如果项位于可见区域外，则返回-1，不管项在滚动到视图时那个点是否存在。

注意：应该在组件完成之后调用方法。

返回包含内容坐标中点x、y的可见项。如果没有项位于指定的点，或者项不可见，则返回null。

如果项位于可见区域外，则返回null，不管项在滚动到视图时那个点是否存在。

注意：应该在组件完成之后调用方法。

返回索引为index的项。如果没有该项，例如因为它尚未创建，或者因为它已经滚动出可见区域并被移除缓存，则返回null。

注意：此方法应在组件完成后调用。返回值也不应存储，因为控制退出调用范围后，它可能会变为null，如果视图释放了该项。

将视图定位，以便index位于由mode指定的位置。

如果将视图定位到index会导致在视图的开始或结束时显示空白空间，则视图将定位在边界上。

不推荐使用contentX或contentY来定位视图到特定索引位置。这是不可靠的，因为从列表开头删除项目不会导致所有其他项目重新定位，并且因为视图的实际起始位置可能根据代理的大小而变化。将项目引入视图的正确方法是使用positionViewAtIndex。

注意：应该在组件完成之后调用方法。要在启动时定位视图，应通过Component.onCompleted调用此方法。例如，要将视图定位到末尾

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