ListView属性说明

ListView显示model的数据，这些model可以从内建的QML元素ListModel和XmlListModel创建，或者用继承于QAbstractListModel的自定义C++ model类

本文: https://www.lovejia.win/blog/article/ListView.html
参考原文：http://doc.qt.io/qt-5/qml-qtquick-listview.html
参考译文：http://blog.csdn.net/gelin520gelin/article/details/34081135

属性说明

add : Transition

用于指定item添加到view中的过渡动画。

addDisplaced : Transition

用于指定view中item由于新增item而引起位置改变时应用的过渡动画。

cacheBuffer : int

是否保留视图可视区域之外的item实例。如果值比0大，视图将保存cacheBuffer指定尺寸的item实例。
详细可参考GridView的该属性

count : int

这个属性保存view中item的数目

currentIndex : int

属性currentIndex 保存当前项的索引，属性currentItem 保存当前项。设置当前索引为-1将清除高亮并将currentItem设置为null。
如果highlightFollowsCurrentItem为真，设置任一个属性都会平滑滚动ListView使得当前项变为可见。
注意：如果当前项不可见，那它的位置只会是大致的位置。

currentItem : Item

参见currentIndex

currentSection : string

这个属性持有视图开始部分的当前分段。

delegate : Component

delegate提供了一个模板来定义被view实例化的每项。索引被暴露作为可访问的属性index。model的属性的可用性也可依赖Data Model的类型。
delegate中的元素的数目会直接影响视图的flicking性能。如果可能，把不需要为delegate正常显示的功能放进Loader里，Loader能只有需要时加载额外元素。
ListView会基于delegate根项的大小来布局items。
建议delagate的大小是一个整数来避免项的亚像素校准。
注意：delegate可以在任何需要的时候被实例化和析构。State永远不要存储在delegate中。

displaced : Transition

任何模型操作导致视图中的item失去位置时的一般过渡。
详细可参考GridView的该属性

displayMarginBeginning : int

这个属性允许delegates被显示在视图几何的外面。
详细可参考GridView的该属性

displayMarginEnd : int

参见displayMarginBeginning。

effectiveLayoutDirection : enumeration

栅格的有效布局方向。它是只读的。

这个属性持有作为footer的组件。
每个view创建一个footer组件的实例。位于view的结尾，任何item的后面。

footerItem : Item

页脚组件的实例。它是所有页脚实例的父。页脚组件的实例在每个视图被创建。页脚位置在视图的底部，所有组件的后面。默认的增加顺序是1。

footerPositioning : enumeration

这个属性决定了footer item的位置，可以是下面这些值：
ListView.InlineFooter (默认) - 页脚在内容的最后，并且作为一个普通item处理
ListView.OverlayFooter - 页脚固定在视图的底部.
ListView.PullBackFooter - 页脚固定在视图的底部，当向后滑动可以隐藏页脚，向前滑动可以显示页脚.

header : Component

这个属性持有作为header的组件。
每个view创建一个header 组件的实例。位于view的开头，任何item的前面。

headerItem : Item

页眉组件的实例。它是所有页眉实例的父，页眉组件的实例在每个视图被创建。页眉的位置在视图的开始，所有组件之前。默认的增加顺序是1。

headerPositioning : enumeration

header item的位置，可以是下面这些值：
ListView.InlineHeader (默认) - 页眉在内容的开头，并且作为一个普通item处理.
ListView.OverlayHeader - 页眉固定在内容的开头.
ListView.PullBackHeader - 页眉固定在内容的开头，当向前滑动时隐藏页眉，向后滑动时显示页眉。

highlight : Component

这个属性持有用作高亮的组件。
每个列表创建一个高亮组件的实例。最终产生的组件实例的几何由列表来管理以致能保留在当前项，除非highlightFollowsCurrentItem为false。

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  
}

注意高亮的动画对于视频滚动也是有效的。这是因为视图移动来维护高亮在优先高亮的范围（或可视范围）。

highlightItem : Item

这持有hightlight组件创建的高亮项。
highlightItem 由视图管理，除非highlightFollowsCurrentItem为false。

highlightMoveDuration : int

highlight的delegate的移动动画持续时间。只有highlightFollowsCurrentItem设置为真，这个属性才有效，默认持续时间是150ms。

highlightMoveVelocity : real

控制highlight移动或变化的动画速度，默认值是400pixels/second.

highlightRangeMode : enumeration

这些属性定义了当前组件在视图中突显的首选范围。preferredHighlightBegin的值一定比preferredHighlightEnd的值小。该属性可以是以下值：
ListView.ApplyRange - 当前item可以被移出指定范围.
ListView.StrictlyEnforceRange - 当前item不能被移出指定范围，若移出，当前item将会改变.
ListView.NoHighlightRange - 这是默认值.

highlightResizeDuration : int

highlight的delegate的移动动画持续时间。只有highlightFollowsCurrentItem设置为真，这个属性才有效，默认持续时间是150ms。

highlightResizeVelocity : real

控制highlight移动或变化的动画速度，默认值是400pixels/second.

keyNavigationEnabled : bool

这属性持有列表是否可循环键导航。
如果为true，键导航会从最后一项移到第一项。
默认是不循环的。

keyNavigationWraps : bool

栅格是否封装导航键。
如果为真，导航键将移动当前item选择越过视图的一端而不是封装成环，移动选择到视图的另一端。默认导航键不封装。

layoutDirection : enumeration

该属性保存视图排列方向，可以是以下值：
Qt.LeftToRight (默认) - 从左到右排列.
Qt.RightToLeft - 从右到左排列.

model : model

这个属性持有给这个list提供数据的model。
model提供数据集用于创建这个view里的item。model能直接被QML用 ListModel, XmlListModel 或VisualItemModel创建，或由C++model类提供。如果使用C++model类，它必须是QAbstractItemModel的子类，或简单的list。

move : Transition

由于在视图的model中做移动操作的视图中的组件所应用的过渡。

moveDisplaced : Transition

这个属性是过渡，应用于在视图中那些因为移动失去位置的模特实例。

orientation : enumeration

该属性保存视图的方向，可以是以下值：
ListView.Horizontal - 水平方向
ListView.Vertical (默认) - 竖直方向

populate : Transition

在视图创建时，用来填充模型模特实例的动画。
它在下面的时候应用到所有的模型模特实例：
1、视图第一次创建。
2、改变视图的模特模型。注意这是改成另一个模特模型的意思。
3、视图模特模型被复位。模特模型需要是QAbstractItemModel子类。

preferredHighlightBegin : real

该属性定义了当前组件在视图中突显的首选范围。preferredHighlightBegin的值一定比preferredHighlightEnd的值小。
当视图滚动时，这些属性影响当前组件的位置。例如，如果视图滚动时，当前组件应该呆在视图的中间，设置preferredHighlightBegin和preferredHighlightEnd的值为中间组件的顶部和底部的坐标。如果当前组件被程序改动，视图将自动滚动，如此以使当前组件在视图的中央。此外，无论highlight是否存在，当前组件索引的行为将发生。

preferredHighlightEnd : real

参考preferredHighlightBegin

remove : Transition

这个过渡用在组件从视图中移除。

removeDisplaced : Transition

这是为视图中因为移除而失去位置的组件指定的过渡。

section

这些属性持有评估section附加属性的表达式。
section附加属性确保ListView被可视化的分为不同的部分。这些属性决定了分段是如何被创建的。

section.property : string

持有属性的名称，它是每个分段的基础。

section.criteria : enumeration

持有每个基于section.property的分段格式的标准。这个值可能是：
ViewSection.FullString (默认) -分段基于section.property 的值来创建
ViewSection.FirstCharacter -分段是基于section.property的第一字符来创建的。（例如’A’, ‘B’, ‘C’ 分段, 等等。用作地址本）

section.delegate : Component

持有每个分段的delegate组件。
列表中的每项有附加属性： ListView.section, ListView.previousSection 和ListView.nextSection。这些属性可用于为相关的项放置分段的头。

section.labelPositioning : enumeration

描述标签显示方式，可以是下面值的组合：
ViewSection.InlineLabels - 在item间隔处显示标签(默认).
ViewSection.CurrentLabelAtStart - 在视图开头显示当前标签.
ViewSection.NextLabelAtEnd - 在视图结尾显示下一个标签.

snapMode : enumeration

视图将如何跟随拖或挥滚动。它的值是下面这些：
GridView.NoSnap(default) - 视图停止在可见区域的任何位置。
GridView.SnapToRow- 视图停止后，视图的开始为行（当flow为GridView.FlowTopToBottom时，是列）对齐的位置。
GridView.SnapOneRow- 视图不会落在超过一行（当flow为GridView.FlowTopToBottom时，是列）的位置。即使鼠标按钮释放时，从一页的第一个可见行离开，视图也回到一页的第一个可见行。这个模式最常用于一次移动一页。

spacing : real

保存两个item的间距，默认是0。

verticalLayoutDirection : enumeration

栅格的垂直布局方向。可能的值如下：
GridView.TopToBottom(default) -组件从视图的顶部往视图的底部布局。
GridView.BottomToTop-组件从视图的底部往视图的顶部布局。

其他属性

delayRemove : bool

这个关联属性保存delegate实例是否可以被摧毁。它关联到delegate的每一个实例上。默认为假。我们有时(例如销毁)需要推迟组件实例的摧毁以确保动画完成。

isCurrentItem : bool

如果是当前组件实例为真。否色为假。这个属性关联到每个delegate实例。

nextSection : string

下一个标签

previousSection : string

前一个标签

section : string

当前item的标签

view : ListView

保存管理这个delegate实例的视图。它关联到delegate组件，也关联到header，footer和highlight这些组件。

信号说明

add()

在组件加入视图之后，立刻发射这个关联信号。

remove()

在组件移出视图之前，立刻发射这个信号。如果移除过渡被指定，过渡应用在这个信号被处理之后。注意delayRemove需要为假。

方法说明

decrementCurrentIndex()

递减当前item序号

forceLayout()

底层模型发生变化而GridView没有捕捉到时，使用一帧画面处理模型的变化。这个方法让GridView立刻响应模型未完成的变化。
注意，这个方法仅仅在组件完成之后，才能被调用。

incrementCurrentIndex()

递增当前item序号

int indexAt(real x, real y)

获取指定位置item序号

Item itemAt(real x, real y)

获取指定位置item

positionViewAtBeginning()

视图开始或结束的位置，包含了页眉或页脚。不推荐使用contentX和contentY去定位特定索引的视图，这是不可靠的。因为从列表的开始移除组件不会促使其他所有的组件响应，并且视图实际开始可能因为delegates的尺寸变的不同。
注意，这个方法仅仅在组件完成后能被调用。在启动时定位视图，应使用Component.onCompleted调用这个方法。例如启动时定位视图末端：
Component.onCompleted:positionViewAtEnd()。

positionViewAtEnd()

参见positionViewAtBeginning()

positionViewAtIndex(int index, PositionMode mode)

用指定的索引，指定模式定位视图。
GridView.Beginning- 视图的组件实例顶部（水平方向是左边)的位置
GridView.Center- 视图的组件实例中心的位置。
GridView.End-视图的组件实例底部（水平方向则是右边)的位置
GridView.Visible- 如果组件的任何部分可见，没有动作，否则带它入视图。
GridView.Contain- 确保整个组件实例可见，如果item太大，尺寸超过视图，它将定位在视图的顶部（水平方向是左边）。
GridView.SnapPosition- 定位视图到preferredHighlightBegin的组件。这个模式仅仅当highlightRangeMode是StrictlyEnforceRange或snapping经由snapMode打开时有效。
如果使用index定位视图时，在视图的开始或结束产生空白的现实。视图将定位到边界。适用contentX和contentY定位特定索引的视图是不推荐的。因为它不可靠。移除视图开始的组件不会出事其他的全部组件被重定位。带组件到视图的正确方式是使用positionViewAtIndex。
注意：本方法应该在组件完成后调用。在启动时定位视图，使用Component.onCompleted。例如设为视图的顶部。
Component.onCompleted:positionViewAtIndex(count - 1, GridView.Beginning)

功能简述

ListView显示model的数据，这些model可以从内建的QML元素ListModel和XmlListModel创建，或者用继承于QAbstractListModel的自定义C++ model类
一个ListView有一个model和一个delegate，model定义了要被显示的数据，delegate定义了如何显示数据。ListView上Items布局为horizontally 或vertically。因为ListView继承自Flickable，所以列表视图天生flickable。

例

下面的例子显示了定义在ContactModel.qml文件中的简单的list model：

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

另一个组件能显示ListView里的model数据，

import QtQuick 1.0
 ListView {  
     width: 180; height: 200  
     model: ContactModel {}  
     delegate: Text {  
         text: name + ": " + number  
     }  
 }

这里，ListView创建一个ContactModel 组件作为它自己的model，一个Text元素作为它自己的delegate。这视图会为model中的每个item创建一个新的Text组件。注意，delegate能直接访问model的name和number数据。
下面显示了改进的列表视图。这个delegate提高了可视化，移到了独立的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  
     }  
 }

使用highlight属性使得当前选择项为高亮的蓝色矩形框，focus被设置为true可使得列表能通过键盘来导航。列表视图自己就是焦点区域。
delegate可以在任何时候需要的时候被实例化和析构。永远（never）不要在在delegate中存储State。
ListView附加了许多属性给delegate的根项，例如，ListView.isCurrentItem。下面的例子中，delegate的根项可以直接访问这个附加属性如，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  
}

注意：Views不能自动clip。如果这个view不能被另一项或屏幕clip，它必须设置clip:true，为了使得视图项外能被更好的clip。