GridView QML Type

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

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

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

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

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

highlightRangeMode 的有效值是

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

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

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

默认值为 0。

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

此 QML 属性在 QtQuick 2.3 中引入。

这些属性表示网格中每个单元格的宽度和高度。

默认单元格大小为 100x100。

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

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

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

每当一个项目被添加到上述视图中时，该项目将在一秒钟内从视图中的位置 (100,100) 以动画形式移动到其最终的 x,y 位置。该过渡只适用于添加到视图中的新项目，不适用于因添加新项目而移位的下方项目。要为移位的项目设置动画，请设置displaced 或addDisplaced 属性。

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

另请参阅 addDisplaced,populate, 和ViewTransition 。

该属性包含应用于视图中因添加其他项目而移位的项目的转换。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

GridView 的项目大小由cellHeight 和cellWidth 决定。它不会根据委托中根项目的大小来调整项目的大小。

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

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

该属性便于为被添加、移动或移除操作移位的项指定通用转换，而无需指定单独的addDisplaced 、moveDisplaced 和removeDisplaced 属性。例如，下面是一个指定了移位过渡的视图：

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

在上述视图中添加、移动或删除任何项目时，其下方的项目都会发生位移，导致它们在视图中向下移动（或横向移动，如果是水平方向）。随着位移的发生，项目在视图中移动到其新 x、y 位置的动画效果将在一秒钟内以NumberAnimation 的形式呈现。

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

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

另请参阅 addDisplaced,moveDisplaced,removeDisplaced 和ViewTransition 。

该属性保留网格的有效布局方向。

在本地布局中使用附加属性LayoutMirroring::enabled 时，网格的可视化布局方向将被镜像。但是，属性layoutDirection 将保持不变。

另请参阅 GridView::layoutDirection 和LayoutMirroring 。

该属性表示网格的流向。

可能的值：

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

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

另请参阅 header 和footerItem 。

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

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

另请参阅 footer 和headerItem 。

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

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

另请参阅 footer 和headerItem 。

这将保存从header 组件创建的页眉项。

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

另请参阅 header 和footerItem 。

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

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

另请参阅 highlightItem 和highlightFollowsCurrentItem 。

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

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

下面是一个高亮显示，其运动由SpringAnimation 项目定义：

Component {
    id: highlight
    Rectangle {
        width: view.cellWidth; height: view.cellHeight
        color: "lightsteelblue"; radius: 5
        x: view.currentItem.x
        y: view.currentItem.y
        Behavior on x { SpringAnimation { spring: 3; damping: 0.2 } }
        Behavior on y { SpringAnimation { spring: 3; damping: 0.2 } }
    }
}

GridView {
    id: view
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

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

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

另请参阅 highlight 和highlightFollowsCurrentItem 。

该属性保存高亮显示委托的移动动画持续时间。

highlightFollowsCurrentItem 该属性必须为 true 才能生效。

持续时间的默认值为 150ms。

另请参阅 highlightFollowsCurrentItem 。

该属性显示是否启用网格按键导航。

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

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

另请参阅 interactive 。

该属性用于确定网格是否会包裹按键导航

如果设置为 "true"，则按键导航会将当前项目选择移动到视图的一端，并将选择移动到视图的另一端。

默认情况下，按键导航不会被包裹。

此属性保留网格的布局方向。

可能的值

注意：如果GridView::flow 设置为GridView.FlowLeftToRight，则不能与 GridView::layoutDirection 设置为 Qt.RightToLeft 混淆。GridView.FlowLeftToRight 流量值仅表示流量是水平的。

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

该属性包含为网格提供数据的模型。

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

另请参阅 数据模型。

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

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

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

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

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

另请参阅 moveDisplaced 和ViewTransition 。

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

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

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

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

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

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

另请参阅 displaced,move, 和ViewTransition 。

该属性包含应用于为视图初始创建的项目的过渡。

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

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

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

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

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

然而，当稍后滚动视图时，即使委托在可见时被实例化，填充过渡也不会运行。当模型发生变化，新的委托变得可见时，add 过渡就会运行。因此，您不应依赖populate 过渡来初始化委托中的属性，因为它并不适用于每个委托。如果您的动画设置了某个属性的to 值，则该属性的初始值应为to ，动画应设置from 值，以防该属性被动画化：

GridView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default; but don't set 0
        ...
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

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

另请参阅 add 和ViewTransition 。

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

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

GridView {
    ...
    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 。

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

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

GridView {
    ...
    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()。

该属性决定拖动或轻移后视图滚动的稳定方式。可能的值有

此属性保留网格的垂直布局方向。

可能的值

另请参阅 GridView::layoutDirection 。

此附加属性用于保存委托是否可以被销毁。它附加到委托的每个实例。默认值为 false。

有时需要延迟项目的销毁时间，直到动画完成。下面的委托示例可确保在项目从列表中移除之前完成动画。

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

如果指定了remove 过渡，则在 delayRemove 返回false 之前不会应用该过渡。

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

它附加到委托的每个实例。

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

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

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

此附加属性包含管理此委托实例的视图。

它附加到委托的每个实例以及页眉、页脚和突出显示委托。

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

此信号在项目添加到重用池后发出。您可以用它来暂停项目中正在进行的计时器或动画，或释放无法重复使用的资源。

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

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

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

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

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

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

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

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

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

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

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

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

Component.onCompleted: positionViewAtEnd()

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

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

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

Returns the index of the visible item containing the pointx,y incontent item coordinates.如果在指定的点上没有项目，或者项目不可见，则返回-1。

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

GridView {
    id: view
    MouseArea {
        anchors.fill: parent
        onClicked: (mouse) => {
            let posInGridView = Qt.point(mouse.x, mouse.y)
            let posInContentItem = mapToItem(view.contentItem, posInGridView)
            let index = view.indexAt(posInContentItem.x, posInContentItem.y)
        }
    }
}

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

另请参阅 itemAt 。

Returns the visible item containing the pointx,y incontent item coordinates.如果在指定的点上没有项目，或者项目不可见，则返回空值。

如果项目在可见区域之外，则返回 null，无论滚动到视图时该点是否存在项目。

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

另请参阅 indexAt 。

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

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

将currentIndex 在视图中向下移动一个项目。如果keyNavigationWraps 为 true 且当前位于尾部，则当前索引将被包围。如果count 为零，则此方法无效。

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

在视图中将currentIndex 向左移动一个项目。如果keyNavigationWraps 为 true 且当前位于末尾，则当前索引将换行。如果count 为零，则此方法无效。

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

将currentIndex 向右移动视图中的一个项目。如果keyNavigationWraps 为 true 且当前位于末尾，则当前索引将被包围。如果count 为零，则此方法无效。

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

将currentIndex 在视图中向上移动一个项目。如果keyNavigationWraps 为 true 且当前位于末尾，则当前索引将被包围。如果count 为零，则此方法无效。

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

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

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

不建议使用contentX 或contentY 将视图定位在特定索引处。这种方法并不可靠，因为从视图起点移除项目并不会导致所有其他项目重新定位。将项目引入视图的正确方法是使用positionViewAtIndex 。

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

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