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 属性公开。根据数据模型的类型，模型的属性也是可用的。


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，可将项目从 persistentItems 组中移除。如果该项目当时未被视图引用，则会被销毁。向该组添加项目不会创建新实例。

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


rootIndex : QModelIndex

QAbstractItemModel 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.prefix 限定），该属性指示委托的模型项是否有任何子节点。

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


附加属性文档

DelegateModel.groups : stringlist

此附加属性保存项目所属 DelegateModelGroups 的名称。

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


DelegateModel.inItems : bool

此附加属性保存项目是否属于默认的items DelegateModelGroup 。

更改此属性将从项目组中添加或删除项目。

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


DelegateModel.inPersistedItems : bool

此附加属性保留了项目是否属于persistedItems DelegateModelGroup 。

更改该属性将从项目组中添加或删除项目。请谨慎更改，因为从persistedItems 组中移除项目会破坏当前实例（如果该实例未被模型引用）。

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


DelegateModel.isUnresolved : bool

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

未解决的项目可以使用DelegateModelGroup::resolve() 函数绑定到数据模型。

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


DelegateModel.itemsIndex : int

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

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


DelegateModel.model : model

此附加属性包含此委托实例所属的数据模型。

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


DelegateModel.persistedItemsIndex : int

该附加属性保存项目在persistedItems DelegateModelGroup 中的索引。

它附加到每个委托实例。


方法文档

QModelIndex modelIndex(int index)

QAbstractItemModel 提供了分层的树状数据，而 QML 只操作列表数据。此函数有助于在 QML 中使用树模型。

返回指定index 的QModelIndex 。该值可分配给rootIndex 。

另请参阅 rootIndex 。


QModelIndex parentModelIndex()

QAbstractItemModel 而 QML 只操作列表数据。此函数有助于在 QML 中使用树模型。

Returns aQModelIndex for the parent of the currentrootIndex.该值可分配给rootIndex.

另请参阅 rootIndex 。


© 2025 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.