Repeater QML Type

使用提供的模型实例化若干基于 Item 的组件。更多...

• 所有成员的列表，包括继承的成员

属性

• count : int
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• model : var

信号

• itemAdded(int index, Item item)
• itemRemoved(int index, Item item)

方法

• Item itemAt(index)

详细说明

“重复器”（Repeater）类型用于创建大量相似的项目。与其他视图类型一样，重复器具有一个“数据源”（model ）和一个“数据模型”（delegate ）：对于模型中的每一条记录，该委托都会在一个已通过模型数据初始化的上下文中被实例化。 “重复器”项通常被封装在定位器类型（如Row 或Column ）中，以便对“重复器”生成的多个委托项进行视觉定位。

以下 Repeater 会在Row 中创建三个Rectangle 项的实例：

import QtQuick

Row {
    Repeater {
        model: 3
        Rectangle {
            width: 100; height: 40
            border.width: 1
            color: "yellow"
        }
    }
}

Repeater 的model 可以是任何受支持的数据模型。此外，与其他视图的委托类似，Repeater 委托可以访问其在 Repeater 中的索引，以及与该委托相关的模型数据。详情请参阅delegate 属性的文档。

由 Repeater 实例化的项目将按顺序作为 Repeater 父节点的子节点插入。 插入操作将从 Repeater 在其父级堆叠列表中的位置之后立即开始。这使得 Repeater 能够用于布局中。例如，以下 Repeater 的项被堆叠在红色矩形和蓝色矩形之间：

Row {
    Rectangle { width: 10; height: 20; color: "red" }
    Repeater {
        model: 10
        Rectangle { width: 20; height: 20; radius: 10; color: "green" }
    }
    Rectangle { width: 10; height: 20; color: "blue" }
}

使用 Repeater 时的注意事项

Repeater 类型会在首次创建时生成所有委托项。如果委托项数量庞大，且并非所有项都需要同时显示，则这种做法可能效率低下。 如果出现这种情况，请考虑使用其他视图类型，例如ListView （该控件仅在委托项被滚动到视图中时才创建），或者使用Dynamic Object Creation 方法按需创建项目。

此外，请注意 Repeater 基于 `Item`，且只能重复显示从 `Item` 派生的对象。例如，它无法用于重复显示 QtObject：

// bad code:
Item {
    // Can't repeat QtObject as it doesn't derive from Item.
    Repeater {
        model: 10
        QtObject {}
    }
}

属性文档

count : int [read-only]

该属性存储model 中的项目数量。

count 的值并不总是与已实例化的delegates 的数量一致；请使用itemAt()来检查给定索引处的委托是否存在。如果该委托尚未实例化，则返回null 。

• 当 Repeater 正在实例化委托（在启动时，或因model 发生变化）时，每创建一个委托都会触发itemAdded 信号，随后count 属性也会随之变化。
• 如果 Repeater 不属于已完成的可视化层级结构的一部分，则 `count ` 会反映模型大小，但不会创建任何委托。
• 如果 Repeater 因model 发生变化而销毁委托，则会为每个委托发出itemRemoved() 信号，随后count 属性也会发生变化。
• 如果 Repeater 被移出视觉层次结构（例如通过设置parent = null ），则委托将被销毁，每个委托都会发出itemRemoved() 信号，但count 不会发生变化。

另请参阅 itemAt()、itemAdded() 和itemRemoved()。

delegate : Component [default]

该委托提供了一个模板，用于定义由重复器实例化的每个项目。

委托会暴露一个只读的 `index ` 属性，该属性指示委托在重复器中的索引。例如，以下 `Text ` 委托会显示每个重复项的索引：

Column {
    Repeater {
        model: 10
        Text {
            required property int index
            text: "I'm item " + index
        }
    }
}

如果 `model ` 是字符串列表或对象列表，则委托还会暴露一个只读的 `modelData ` 属性，用于存储字符串或对象数据。例如：

Column {
    Repeater {
        model: ["apples", "oranges", "pears"]
        Text {
            required property string modelData
            text: "Data: " + modelData
        }
    }
}

如果model 是模型对象（例如ListModel ），则委托可以像对ListView 等视图类那样，通过命名属性访问所有模型角色。

另请参阅 QML 数据模型。

delegateModelAccess : enumeration [since 6.10]

此属性决定了委托如何访问模型。

默认值为 `DelegateModel.Qt5ReadWrite`。

该属性在 Qt 6.10 中引入。

另请参阅 《Qt Quick 中的模型和视图》中的“#更改模型数据”。

model : var

为中继器提供数据的模型。

该属性可设置为任何受支持的数据模型：

• 一个数字，表示重复器将创建的委托对象数量
• 一个模型（例如ListModel 项，或QAbstractItemModel 的子类）
• 一个字符串列表
• 一个对象列表

模型的类型会影响向delegate 公开的属性。

另请参阅 “数据模型”。

信号文档

itemAdded(int index, Item item)

当向重复器中添加一个项目时，会触发此信号。index 参数存储该项目在重复器中被插入的索引位置，而item 参数则存储已添加的Item 。

itemRemoved(int index, Item item)

当从中继器中移除一个项目时，会发出此信号。index 参数保存该项目从中继器中被移除时的索引，而item 参数保存被移除的Item 。

如果 `item ` 是由该重复器创建的，请不要保留对其的引用，因为在这种情况下，该对象将在信号处理完成后不久被删除。

方法文档

Item itemAt(index)

返回在指定index 处创建的Item ，或者如果index 处不存在该项，则返回null 。