ListView QML Type

currentIndex 属性保存当前项目的索引，currentItem 保存当前项目。将currentIndex 设置为-1 将清除高亮显示，并将currentItem 设置为空。

如果highlightFollowsCurrentItem 是true ，设置这两个属性中的任何一个都将平滑滚动ListView ，使当前项目可见。

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

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

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

highlightRangeMode 的有效值是

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

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

例如，如果在垂直视图中，代表高度为 20 像素，而displayMarginBeginning 和displayMarginEnd 都设置为 40，那么将创建并显示上方 2 个代表和下方 2 个代表。

默认值为 0。

此属性旨在允许某些用户界面配置，而不是作为性能优化。如果出于性能考虑，您希望在视图几何图形之外创建代表，您可能需要使用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 }
    }
}

每当在上述视图中添加一个项目时，新项目下方的所有项目都会发生位移，导致它们在视图中向下移动（如果水平方向，则向侧边移动）。随着位移的发生，这些项目在视图中移动到新的 x、y 位置的动画效果将在一秒钟内以NumberAnimation 指定。此过渡并不适用于已添加到视图中的新项目；要为添加的项目设置动画，请设置add 属性。

如果一个项目同时被多种类型的操作移位，则不会定义是应用 addDisplaced、moveDisplaced 还是removeDisplaced 过渡。此外，如果不需要根据项目是被添加、移动还是移除操作移位来指定不同的过渡，可以考虑设置displaced 属性。

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

另请参阅 displaced,add,populate 和ViewTransition 。

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

如果该值大于零，则视图可以在指定的缓冲区内尽可能多地保留已实例化的委托。例如，如果在垂直视图中，代表高度为 20 像素，而cacheBuffer 设置为 40，那么最多可以在可见区域上方创建/保留 2 个代表，在可见区域下方创建/保留 2 个代表。缓冲委派是异步创建的，允许在多个帧中创建，从而降低了跳帧的可能性。为了提高绘制性能，不绘制可见区域外的代表。

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

请注意，cacheBuffer 并非像素缓冲区，它只维护附加的实例化代表。

cacheBuffer 在displayMarginBeginning 或displayMarginEnd 指定的显示边距之外运行。

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

该属性保存当前视图开头的部分。

委托组件提供了一个模板，定义了视图实例化的每个项目。索引作为可访问的index 属性公开。根据数据模型的类型，模型的属性也是可用的。

委托中对象和绑定的数量会直接影响视图的闪烁性能。如果可能，请将正常显示委托时不需要的功能放在Loader 中，以便在需要时加载其他组件。

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

建议委托的大小为整数，以避免项目的亚像素对齐。

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

另请参阅 Stacking Order in ListView 。

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

该属性便于指定应用于被添加、移动或移除操作移位的任何项的通用转换，而无需指定单独的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 。

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

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

另请参阅 ListView::layoutDirection 和LayoutMirroring 。

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

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

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

这是由footer 组件创建的页脚项。

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

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

该属性决定footer item 的位置。

该属性在 Qt 5.4 中引入。

该属性包含用作页眉的组件。

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

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

这是由header 组件创建的页眉项。

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

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

该属性决定header item 的位置。

此属性在 Qt 5.4 中引入。

该属性包含用作高亮显示的组件。

每个列表都会创建一个高亮组件实例。除非highlightFollowsCurrentItem 属性为 false，否则生成的组件实例的几何形状将由列表管理，以便与当前项目保持一致。高亮显示项的默认stacking order 是0 。

另请参阅 highlightItem,highlightFollowsCurrentItem,ListView 高亮示例和Stacking Order in ListView 。

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

如果该属性为 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 。

这是由highlight 组件创建的高亮显示项。

highlightItem 由视图管理，除非highlightFollowsCurrentItem 设置为 false。高亮显示项的默认stacking order 是0 。

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

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

如果设置为true ，用户就可以使用键盘导航视图。这对需要有选择地启用或禁用鼠标和键盘交互的应用程序非常有用。

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

另请参阅 interactive 。

该属性用于确定列表是否包裹按键导航。

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

默认情况下，按键导航不会缠绕。

该属性是水平方向列表的布局方向。

可能的值

如果orientation 是 Qt.Vertical，则设置此属性无效。

另请参阅 ListView::effectiveLayoutDirection 和ListView::verticalLayoutDirection 。

此属性包含为列表提供数据的模型。

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

另请参阅 数据模型。

该属性包含应用于视图中因视图model 中的移动操作而移动的项目的转换。

例如，下面是一个指定了这种过渡的视图：

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

每当model 执行移动操作移动特定索引集时，视图中的相应项将在一秒钟内以动画形式移动到其在视图中的新位置。该过渡只适用于模型中作为移动操作对象的项，不适用于其下方被移动操作移位的项。要将移位的项目制成动画，请设置displaced 或moveDisplaced 属性。

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

另请参阅 moveDisplaced 和ViewTransition 。

该属性包含应用于视图model 中被移动操作移位的项目的过渡。

例如，下面是一个指定了这种转换的视图：

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

每当model 执行移动操作以移动特定索引集时，移动操作的源索引和目标索引之间的项就会发生位移，导致它们在视图中向上或向下移动（或横向移动，如果是水平方向）。在发生位移时，项目在视图中移动到新 x、y 位置的动画效果将在一秒钟内以NumberAnimation 的形式呈现。此过渡并不适用于移动操作的实际对象项目；要为移动的项目设置动画，请设置move 属性。

如果一个项目同时被多种类型的操作移动，则不会定义是应用addDisplaced 、moveDisplaced 还是removeDisplaced 过渡。此外，如果不需要根据项目是被添加、移动还是移除操作移位来指定不同的转换，可以考虑设置displaced 属性。

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

另请参阅 displaced,move, 和ViewTransition 。

该属性用于保存列表的方向。

可能的值：

常量	说明
ListView.Horizontal	项目水平排列
ListView.Vertical	(默认）项目垂直排列

另请参阅 Flickable Direction 。

此属性保留了应用于为视图初始创建的项目的过渡。

它适用于以下情况下创建的所有项目：

• 视图首次创建
• 视图的model 发生变化，从而完全替换了可见委托
• 视图的model 是reset ，如果模型是QAbstractItemModel 子类

例如，这里有一个视图指定了这样的转换：

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

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

然而，当稍后滚动视图时，即使委托在可见时被实例化，填充过渡也不会运行。当模型发生变化，新的委托变得可见时，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 。

该属性包含应用于从视图中移除的项目的过渡。

例如，下面的视图就指定了这样一个过渡：

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 attached 属性，则移除转换将不会应用，直到delayRemove 再次变为 false。

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

另请参阅 removeDisplaced 和ViewTransition 。

该属性包含应用于视图中因移除其他项目而被移除的项目的过渡。

例如，下面是一个指定了这种转换的视图：

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

每当从上述视图中移除一个项目时，其下方的所有项目都会发生位移，导致它们在视图中向上（或向侧（如果水平方向））移动。随着位移的发生，项目在视图中移动到新的 x、y 位置的动画效果将在一秒钟内以NumberAnimation 的形式呈现。此转换不会应用于实际从视图中移除的项目；要为移除的项目制作动画，请设置remove 属性。

如果一个项目同时被多种类型的操作移除，则不会定义是应用addDisplaced 、moveDisplaced 还是 removeDisplaced 过渡。此外，如果不需要根据项目是被添加、移动还是移除操作移位来指定不同的过渡，可以考虑设置displaced 属性。

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

另请参阅 displaced 、remove 和ViewTransition 。

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

该属性默认为false 。

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

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

section.property 保存作为各部分基础的属性名称。

section.criteria 保存根据 形成每个部分的标准。该值可以是section.property

在确定分区边界时，使用大小写不敏感比较法。

section.delegate 持有各部分的委托组件。小节委托实例的默认 是 。如果在其中声明名为 "小节 "的 属性，该属性将包含小节的标题。stacking order 2 required

section.labelPositioning 决定当前和/或下一章节标签是否贴在视图的开始/结束位置，以及标签是否内嵌显示。该值可以是以下值的组合

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

例如，下面是一个显示动物列表的ListView ，该列表分为多个部分。根据模型项的 "大小 "属性，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 示例和Stacking Order in 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 时，才会发出该信号。

另请参阅 Reusing items,reuseItems, 和reused() 。

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

如果指定了移除转换，则会在处理此信号后应用该转换，前提是delayRemove 为 false。

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

项目被重复使用时，模型不提供的其他属性不会改变。应避免在委托中存储任何状态，如果要存储，请在收到此信号时手动重置该状态。

该信号在项目被重复使用时发出，而不是在首次创建项目时发出。

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

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

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

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

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

Component.onCompleted: positionViewAtEnd()

减少当前索引。如果keyNavigationWraps 为 true 且当前位于开始位置，则当前索引将被包围。如果count 为零，此方法将不起作用。

注意：方法只能在组件完成后调用。

对模型变化的响应通常是分批进行的，每帧只发生一次。这意味着在脚本块内，底层模型有可能已经改变，但ListView 还没有跟上。

此方法可强制ListView 立即响应模型中任何未完成的更改。

注意：方法只能在组件完成后调用。

递增当前索引。如果keyNavigationWraps 为 true 且当前处于尾部，则当前索引将被包围。如果count 为零，则此方法无效。

注意：方法只能在组件完成后调用。

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

如果项目位于可视区域之外，无论滚动到视图时该点是否存在项目，都将返回-1。

注意：方法只能在组件完成后调用。

返回包含点x 的可见项目，y 以内容坐标表示。如果在指定的点上没有项目，或者项目不可见，则返回空值。

如果项目不在可见区域内，无论滚动到视图时该点是否存在项目，都将返回 null。

注意：方法只能在组件完成后调用。

返回index 的项目。如果该索引没有项目，例如因为尚未创建，或者因为已从可见区域平移并从缓存中删除，则返回 null。

注意：此方法只能在组件完成后调用。也不应存储返回值，因为如果视图释放了该项目，一旦控件离开调用范围，返回值就会变为空值。

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

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

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

注意：方法只能在组件完成后调用。要在启动时定位视图，应通过 Component.onCompleted 调用该方法。例如，在结束时定位视图：

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