GridView QML 类型

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

如果highlightFollowsCurrentItem为true，设置这些属性之一将平滑地滚动GridView，使当前项变得可见。

请注意，当前项的位置在它变得可见之前可能只能是近似值。

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

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

highlightRangeMode 的有效值有

此属性允许代理在视图几何形状之外显示。

如果此值非零，视图将在视图开始之前创建额外的代理，或者在视图之后。视图将创建尽可能多的代理，以适应指定的像素大小。

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

默认值为0。

此属性意在允许某些UI配置，而不是作为性能优化。如果出于性能原因希望在视图几何形状之外创建代理，您可能想改用 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 }
    }
}

每当向上述视图中添加项目时，所有位于新项下方的项目都会发生位移，导致它们在视图中向下（或者如果水平对齐则向侧面）移动。在此位移期间，项目将使用指定的 NumberAnimation 在一秒内动画化到其新的 x,y 位置。此转换不应用于已添加到视图中的新项；要动画化添加的项目，请设置 add 属性。

如果一项被多种类型的操作同时位移，未明确规定是否应用 addDisplaced、moveDisplaced 或 removeDisplaced 转换。此外，如果不需要根据项目是否因添加、移动或删除操作而产生位移来指定不同的转换，请考虑设置 displaced 属性。

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

另请参阅：displaced、add、populate 和 ViewTransition。

此属性确定代理是否保留在视图的可视区域外。

如果此值大于零，视图可能会保留指定缓冲区中可容纳的最多实例化的代理。例如，在一个垂直视图中，如果代理高度为 20 像素，有 3 列，并且 cacheBuffer 设置为 40，则可能创建/保留多达 6 个位于可见区域上方和 6 个位于可见区域下方的代理。缓存的代理是以异步方式创建的，允许在多个帧间创建，从而降低跳帧的可能性。为了提高绘制性能，可视区域外的代理不会被绘制。

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

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

缓存缓冲区在由 displayMarginBeginning 或 displayMarginEnd 指定的任何显示边距之外操作。

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

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

委托中的对象和绑定的数量直接影响视图的翻页性能。如果可能，将不需要用于委托常规显示的功能放在 Loader 中，该 Loader 在需要时可以加载额外的组件。

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

委托实例的默认 堆叠顺序 是 1。

此属性存储应用于由于影响视图的任何模型操作而被移位的项目的通用过渡。

这是一个方便的方法，用于指定通过添加、移动或删除操作移位的项的通用过渡，而无需指定单个 addDisplaced、moveDisplaced 和 removeDisplaced 属性。例如，以下指定了移位过渡的视图

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

在上面的视图中添加、移动或删除任何项时，其下面的项将被移位，导致它们在视图中向下（或如果水平对齐则向侧）移动。在此移位发生时，项目将根据指定的时间在一个秒内由一个 数字动画 动画到它们的新 x, y 位置。

如果视图同时指定了此通用移位过渡以及特定的 addDisplaced、moveDisplaced 或 removeDisplaced 过渡，并且更具体的过渡尚未禁用（通过将 enabled 设置为 false），当发生相关操作时，将使用更具体的过渡而不是通用移位过渡。如果它确实已经禁用，则将应用通用移位过渡。

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

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

该属性用于获取网格的有效布局方向。

当使用附加属性LayoutMirroring::enabled进行区域布局时，网格的视觉布局方向将被反转。但是，属性layoutDirection将保持不变。

另请参阅 GridView::layoutDirection和LayoutMirroring。

该属性用于获取网格的流动方向。

可能的值

此属性用于指定用作脚本的组件。

为每个视图创建一个脚本的组件实例。脚本位于视图的末尾，所有元素之后。脚本的默认堆叠顺序是1。

另请参阅 header和footerItem。

此属性保存由footer组件创建的脚本元素。

为每个视图创建一个脚本的组件实例。脚本位于视图的末尾，所有元素之后。脚本的默认堆叠顺序是1。

另请参阅 footer 和 headerItem。

此属性用于指定用作标题的组件。

为每个视图创建一个标题组件实例。标题位于视图的开始位置，在所有元素之前。标题的默认堆叠顺序是1。

另请参阅 footer 和 headerItem。

保存从header组件创建的标题元素。

为每个视图创建一个标题组件实例。标题位于视图的开始位置，在所有元素之前。标题的默认堆叠顺序是1。

另请参阅 header和footerItem。

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

为每个视图创建一个高亮组件实例。结果组件实例的几何形状将由视图管理，以便始终跟随当前元素，除非设置了highlightFollowsCurrentItem属性。高亮元素的默认堆叠顺序是0。

另请参阅 highlightItem 和 highlightFollowsCurrentItem。

该属性用于设置高亮是否由视图管理。

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

以下是一个通过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 由视图管理。高亮项的默认堆叠顺序是 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。

此属性保存提供网格数据的模型。

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

另请参阅 数据模型。

此属性保存应用于视图中由于在视图的 model 中进行移动操作而移动的项目的过渡。

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

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

无论何时，模型执行移动特定一组索引的操作时，视图中的对应项将动画显示在视图的新位置上，持续时间为1秒。这个过渡仅适用于模型中移动操作涉及的项；不适用于因操作而移位的下面的项。要动画化移位项，请设置displaced或moveDisplaced属性。

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

另请参阅 moveDisplaced和ViewTransition。

该属性存储应用于由视图中的移动操作移位的项的过渡。

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

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

无论何时，模型执行移动特定一组索引的操作，都会导致移动操作的源索引和目标索引之间的项发生移位，导致它们在视图中向上或向下（如果是水平方向，则为向左右）移动。这一移动产生时，项将根据指定的时间通过一个NumberAnimation动画通过一秒的动作转换到视图中新的x,y位置。此过渡不适用于移动操作的真正主体项；为了动画化移动项，请设置move属性。

如果一个项同时受到多种类型操作的影响，则未定义addDisplaced、moveDisplaced或removeDisplaced过渡是否应用。另外，如果不是必须根据项是通过添加、移动还是删除操作移位来确定不同的过渡，则考虑设置displaced属性。

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

另请参阅 displaced、move和ViewTransition。

该属性存储应用于最初为视图创作的项的过渡。

当以下情况发生时应用：

• 视图首次创建时
• 视图的model发生更改，以这种方式替换了可见的委托者
• 如果模型是QAbstractItemModel子类，则视图的model被重置，即beginResetModel

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

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

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

然而，在随后滚动视图时，populate过渡不会执行，即使委托者正逐一实例化。当模型以一种使新委托者可见的方式更改时，会执行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附加属性，则删除转换直到 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时，才会发出此信号。

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

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

如果在处理此信号后指定了移除转换，则只有在delayRemove为false的情况下才会应用。

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

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

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

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

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

将视图定位到开始或结束位置，同时考虑任何标题或页脚。

不建议使用contentX或contentY来定位视图的特定索引。这是不可靠的，因为从列表的起始位置删除项不会导致所有其他项重新定位，并且实际视图的起始位置可能因代理的大小而异。

注意：应该在组件完成之后才调用方法。为了在启动时定位视图，该方法应由Component.onCompleted调用。例如，要使视图在启动时定位到末尾

Component.onCompleted: positionViewAtEnd()

对模型变化的响应通常批量处理，以便每帧只发生一次。这意味着在脚本块内部，底层模型可能会发生变化，但GridView尚未跟上。

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

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

返回包含点x、y的可见项的索引，该点位于内容项坐标中。如果没有项位于指定的点，或项不可见，则返回-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。

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

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

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

另请参阅indexAt。

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

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

在视图中将currentIndex向下移动一个项。如果keyNavigationWraps为true且当前位于末尾，当前索引将循环。如果count为零，则此方法没有任何效果。

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

在视图中将currentIndex向左移动一个项。如果keyNavigationWraps为true且当前位于末尾，当前索引将循环。如果count为零，则此方法没有任何效果。

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

在视图中将currentIndex向右移动一个项。如果keyNavigationWraps为true且当前位于末尾，当前索引将循环。如果count为零，则此方法没有任何效果。

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

将视图中的currentIndex向上移动一个项目。如果keyNavigationWraps为真，并且当前索引位于末尾，则当前索引会循环。如果count为零，则此方法没有效果。

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

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

如果将视图定位在索引会导致视图开头或末尾显示空空间，则视图将定位在边界上。

不建议使用contentX或contentY来将视图定位在特定的索引上。这是不可靠的，因为从视图的开始位置删除项目不会导致所有其他项目重新定位。将项目引入视图的正确方法是使用positionViewAtIndex。

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