Back to Qt.io
Contact Us Blog Download Qt
本页内容

DelegateModel QML Type

封装了一个模型和一个委托。更多...

Import Statement: import QtQml.Models

属性

关联属性

方法

详细说明

DelegateModel 类型封装了一个模型以及将为该模型中的项目实例化的委托。

通常无需创建 DelegateModel。但是，当使用QAbstractItemModel 的子类作为模型时，它对于操作和访问modelIndex 会很有用。此外，DelegateModel 还与Package 配合使用，为多个视图提供委托；并与DelegateModelGroup 配合使用，对委托项进行排序和过滤。

DelegateModel 仅支持一维模型——因此，若将表模型分配给 DelegateModel，再将其分配给TableView ，则只会显示一列。

下面的示例演示了如何将 DelegateModel 与ListView 配合使用。

import QtQuick
import QtQml.Models

Rectangle {
    width: 200; height: 100

    DelegateModel {
        id: visualModel
        model: ListModel {
            ListElement { name: "Apple" }
            ListElement { name: "Orange" }
        }
        delegate: Rectangle {
            height: 25
            width: 100
            Text { text: "Name: " + name}
        }
    }

    ListView {
        anchors.fill: parent
        model: visualModel
    }
}

属性文档

count : int

delegate : Component

该委托提供了一个模板，用于定义视图所实例化的每个项目。索引作为可访问的index 属性对外暴露。根据数据模型的类型不同，模型的属性也可供使用。

delegateModelAccess : enumeration [since 6.10]

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

常量描述
DelegateModel.ReadOnly禁止委托通过上下文属性、model 对象或必填属性写入模型。
DelegateModel.ReadWrite允许委托通过上下文属性、model 对象或必填属性写入模型。
DelegateModel.Qt5ReadWrite允许委托通过model 对象和上下文属性写入模型，但不能通过必填属性写入模型。

默认值为 `DelegateModel.Qt5ReadWrite`。

该属性在 Qt 6.10 中引入。

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

filterOnGroup : string

该属性存储用于过滤委托模型的组名称。

只有属于该组的项目才会显示在视图中。

默认情况下，该组为“items ”。

groups : list<DelegateModelGroup>

该属性存储了委托模型的组定义。

组定义了委托模型中项目的子集，可用于过滤模型。

对于在DelegateModel 中定义的每个组，每个委托项都会添加两个关联的伪属性。第一个属性格式为DelegateModel.inGroupName，用于表示该项是否属于该组；第二个属性DelegateModel.groupNameIndex，用于表示该项在该组中的索引。

以下示例演示了如何使用组在模型中选择项目。

import QtQuick
import QtQml.Models

Rectangle {
    width: 200; height: 100

    DelegateModel {
        id: visualModel
        model: ListModel {
            ListElement { name: "Apple" }
            ListElement { name: "Orange" }
        }

        groups: [
            DelegateModelGroup { name: "selected" }
        ]

        delegate: Rectangle {
            id: item
            height: 25
            width: 200
            Text {
                text: {
                    var text = "Name: " + name
                    if (item.DelegateModel.inSelected)
                        text += " (" + item.DelegateModel.selectedIndex + ")"
                    return text;
                }
            }
            MouseArea {
                anchors.fill: parent
                onClicked: item.DelegateModel.inSelected = !item.DelegateModel.inSelected
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: visualModel
    }
}

警告：与 普通附加属性不同， 这些属性无法通过声明式方式进行设置。以下代码将导致错误：

delegate: Rectangle {
    DelegateModel.inSelected: true
}

items : DelegateModelGroup

此属性指定默认组，所有新项目都将添加到该组中。

model : model

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

该模型提供了一组数据，用于为视图创建项目。对于大型或动态数据集，模型通常由一个 C++ 模型对象提供。该 C++ 模型对象必须是 `QAbstractItemModel ` 的子类，或者是一个简单的列表。

模型也可以直接在 QML 中创建，例如使用 `ListModel`。

另请参阅 “数据模型”。

parts : object

parts 属性用于选择一个DelegateModel ，该对象会根据指定名称生成委托。该属性需与Package 类型配合使用。

例如，以下代码从一个 `Package` 中选择一个模型，该模型会创建名为 `list`的委托：

DelegateModel {
    id: visualModel
    delegate: Package {
        Item { Package.name: "list" }
    }
    model: myModel
}

ListView {
    width: 200; height:200
    model: visualModel.parts.list
}

另请参阅 Package 。

persistedItems : DelegateModelGroup

该属性保存了委托模型的持久化项组。

当视图释放该组中的项目时，这些项目不会被销毁，而是会一直保留，直到从该组中移除为止。

可以通过将DelegateModel.inPersistedItems 属性设置为false，将项目从persistedItems组中移除。如果此时该项目未被任何视图引用，则会被销毁。将项目添加到该组不会创建新的实例。

由QtQml.Models::DelegateModelGroup::create()函数返回的项会自动添加到该组中。

rootIndex : QModelIndex

QAbstractItemModel 提供了一个分层数据树，而 QML 仅处理列表数据。rootIndex 允许由该模型提供QAbstractItemModel 中任意节点的子节点。

此属性仅影响类型为QAbstractItemModel 且具有层次结构（例如树形模型）的模型。

例如，这是一个简单的交互式文件系统浏览器。当点击一个目录名称时，视图的rootIndex 将被设置为所点击目录的QModelIndex 节点，从而更新视图以显示新目录的内容。

main.cpp:

int main(int argc, char ** argv)
{
    QGuiApplication app(argc, argv);

    QQuickView view;

    QFileSystemModel model;
    // start populating the model (doesn't change the model's root)
    model.setRootPath(QDir::currentPath());

    qmlRegisterSingletonInstance("FileSystemModule", 1, 0, "FileSystemModel", &model);
    view.setSource(QUrl::fromLocalFile("view.qml"));
    view.show();

    return app.exec();
}

view.qml:

import QtQuick
import QtQml.Models
import FileSystemModule

pragma ComponentBehavior: Bound

ListView {
    id: view
    width: 300
    height: 400

    model: DelegateModel {
        id: delegateModel
        model: FileSystemModel // singleton

        delegate: Rectangle {
            id: delegate
            required property int index
            required property string filePath
            required property bool hasModelChildren

            width: 300; height: 25
            color: index % 2 ? palette.alternateBase : palette.base

            Text {
                anchors.verticalCenter: parent.verticalCenter
                color: palette.text
                text: delegate.filePath
            }

            TapHandler {
                onTapped: if (delegate.hasModelChildren)
                              delegateModel.rootIndex = delegateModel.modelIndex(delegate.index)
            }
        }
    }
}

如果 `model ` 是 `QAbstractItemModel ` 的子类，则委托还可以引用 `hasModelChildren ` 属性（可选地通过 `model.` 前缀限定），该属性指示委托的模型项是否具有子节点。

另请参阅 modelIndex() 和parentModelIndex()。

附加属性文档

DelegateModel.groups : list<string> [attached]

此附加属性存储了该项目所属的 DelegateModelGroups 的名称。

它附加在每个委托实例上。

DelegateModel.inItems : bool [attached]

此附加属性用于标识该项目是否属于默认的items DelegateModelGroup 。

更改此属性将把该项目添加到项目组中或从项目组中移除。

它附属于委托的每个实例。

DelegateModel.inPersistedItems : bool [attached]

此附加属性用于标识该项是否属于“persistedItems ”组（DelegateModelGroup ）。

更改此属性将把该项目添加到或从项目组中移除。请谨慎操作，因为如果项目未被模型引用，将其从persistedItems 组中移除将销毁当前实例。

该属性附加在委托的每个实例上。

DelegateModel.isUnresolved : bool [attached]

此附加属性用于指示可视化项是否已绑定到数据模型索引。如果该项未绑定到模型，则返回 true；如果已绑定，则返回 false。

未解析的项目可通过调用DelegateModelGroup::resolve()函数与数据模型建立绑定。

该属性附加在委托的每个实例上。

DelegateModel.itemsIndex : int [attached]

此附加属性保存了项目在默认items DelegateModelGroup 中的索引。

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

DelegateModel.model : model [attached]

此附加属性保存了该委托实例所属的数据模型。

它被附加到每个委托实例上。

DelegateModel.persistedItemsIndex : int [attached]

此附加属性存储了该项在persistedItems DelegateModelGroup 中的索引。

它附加在每个委托实例上。

方法文档

QModelIndex modelIndex(int index)

QAbstractItemModel 提供了一个分层数据树，而 QML 仅处理列表数据。该函数有助于在 QML 中使用树模型。

返回指定index 对应的QModelIndex 。该值可赋值给rootIndex 。

另请参阅 rootIndex 。

QModelIndex parentModelIndex()

QAbstractItemModel 提供了一个分层的数据树，而 QML 仅处理列表数据。此函数有助于在 QML 中使用树模型。

返回当前rootIndex 的父节点对应的QModelIndex 。该值可赋值给rootIndex 。

另请参阅 rootIndex 。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.