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

QStyledItemDelegate Class

QStyledItemDelegate 类为模型中的数据项提供了显示和编辑功能。更多内容...

头文件： #include <QStyledItemDelegate>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承自： QAbstractItemDelegate
被继承者：

QSqlRelationalDelegate

公共函数

QStyledItemDelegate(QObject *parent = nullptr)
virtual ~QStyledItemDelegate()
virtual QString displayText(const QVariant &value, const QLocale &locale) const
QItemEditorFactory *itemEditorFactory() const
void setItemEditorFactory(QItemEditorFactory *factory)

重新实现的公共函数

virtual QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void setEditorData(QWidget *editor, const QModelIndex &index) const override
virtual void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override
virtual QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override
virtual void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override

受保护函数

virtual void initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) const

重新实现的受保护函数

virtual bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override
virtual bool eventFilter(QObject *object, QEvent *event) override

详细说明

在 Qt 项目视图（例如QTableView ）中显示模型数据时，各个项目由一个委托对象绘制。此外，当编辑项目时，它会提供一个编辑器小部件，该小部件在编辑过程中会显示在项目视图之上。 QStyledItemDelegate 是所有 Qt 项目视图的默认委托，并在项目视图创建时被安装到它们上。

QStyledItemDelegate 类是模型/视图类之一，属于 Qt的模型/视图框架。该委托使项的显示和编辑能够独立于模型和视图进行开发。

模型中的项目数据会被分配一个ItemDataRole ；每个项目可以为每个角色存储一个QVariant 。QStyledItemDelegate 实现了用户预期中最常见的数据类型的显示和编辑功能，包括布尔值、整数和字符串。

数据的绘制方式将根据其在模型中的角色而有所不同。下表描述了各角色以及委托可处理的对应数据类型。通常只需确保模型为每个角色返回适当的数据，即可确定视图中项目的显示效果。

角色支持的类型
Qt::BackgroundRoleQBrush
Qt::CheckStateRoleQt::CheckState
Qt::DecorationRoleQIcon、QPixmap 、QImage 以及QColor
Qt::DisplayRoleQString 以及具有字符串表示形式的数据类型
Qt::EditRole详情请参见QItemEditorFactory
Qt::FontRoleQFont
Qt::SizeHintRoleQSize
Qt::TextAlignmentRoleQt::Alignment
Qt::ForegroundRoleQBrush

编辑器是通过 `QItemEditorFactory` 创建的；由 `QItemEditorFactory ` 提供的默认静态实例会被安装到所有项委托上。您可以使用 `setItemEditorFactory()` 设置自定义工厂，或使用 `QItemEditorFactory::setDefaultFactory()` 设置新的默认工厂。

QItemEditorFactory *editorFactory = new QItemEditorFactory;
QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>();
editorFactory->registerEditor(QMetaType::QDateTime, creator);

QItemEditorFactory::setDefaultFactory(editorFactory);

设置新工厂后，所有标准项委托都将使用该工厂（即，包括在新默认工厂设置之前创建的委托）。

被编辑的是项目模型中通过EditRole 存储的数据。有关项目编辑器工厂的更高层次介绍，请参阅QItemEditorFactory 类。

继承 QStyledItemDelegate

如果委托不支持所需数据类型的绘制，或者您希望自定义项目的绘制方式，则需要继承 QStyledItemDelegate，并重写paint() 方法，必要时还需重写sizeHint() 方法。paint() 函数会针对每个项目单独调用，而通过sizeHint()，您可以为每个项目指定绘制提示。

在重写paint() 时，通常会处理需要绘制的数据类型，而对于其他类型则使用父类的实现。

复选框指示符的绘制由当前样式负责。该样式还会指定不同数据角色的数据绘制大小及其边界矩形。 项目本身的边界矩形也是由样式计算得出的。因此，在绘制已支持的数据类型时，最好向样式查询这些边界矩形。QStyle 类的描述对此进行了更详细的说明。

如果您希望更改样式计算出的任何边界矩形或复选框指示符的绘制方式，可以继承QStyle 类。但请注意，重写sizeHint() 方法也会影响项的大小。

自定义委托可以在不使用编辑器项工厂的情况下提供编辑器。在这种情况下，必须重写以下虚拟函数：

  • createEditor() 返回用于更改模型中数据的小部件，可重写该方法以自定义编辑行为。
  • setEditorData() 向小部件提供待操作的数据。
  • updateEditorGeometry() 确保编辑器相对于项目视图正确显示。
  • setModelData() 将更新后的数据返回给模型。

“Star Delegate”示例通过重写这些方法来创建编辑器。

QStyledItemDelegate 与 QItemDelegate

自 Qt 4.4 起，有两个委托类：QItemDelegate 和 QStyledItemDelegate。不过，默认的委托是 QStyledItemDelegate。这两个类是独立的替代方案，用于绘制视图中的项目并为其提供编辑器。 它们之间的区别在于，QStyledItemDelegate 使用当前样式来绘制其项目。因此，在实现自定义委托或使用 Qt 样式表时，我们建议将 QStyledItemDelegate 作为基类。除非自定义委托需要使用样式进行绘制，否则这两种类所需的代码应相同。

若要自定义项目视图的绘制效果，应实现自定义样式。详情请参阅QStyle 类的文档。

另请参阅 “委托类”、“QItemDelegate ”、“QAbstractItemDelegate ”、“QStyle ”以及“Star 委托示例”。

成员函数文档

[explicit] QStyledItemDelegate::QStyledItemDelegate(QObject *parent = nullptr)

根据给定的parent 构建一个项目委托。

[virtual noexcept] QStyledItemDelegate::~QStyledItemDelegate()

销毁该项的委托对象。

[override virtual] QWidget *QStyledItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

重写：QAbstractItemDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const。

返回用于编辑由index 指定的项的小部件。parent 小部件和样式option 用于控制编辑器小部件的外观。

另请参阅 QAbstractItemDelegate::createEditor()。

[virtual] QString QStyledItemDelegate::displayText(const QVariant &value, const QLocale &locale) const

该函数返回委托在locale 中用于显示模型Qt::DisplayRole 的字符串。value 是模型提供的Qt::DisplayRole 的值。

默认实现使用QLocale::toString 将value 转换为QString 。

对于空模型索引（即模型返回无效QVariant 的索引），不会调用此函数。

另请参阅 QAbstractItemModel::data()。

[override virtual protected] bool QStyledItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)

重写了：QAbstractItemDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index)。

[override virtual protected] bool QStyledItemDelegate::eventFilter(QObject *object, QEvent *event)

重写了：QObject::eventFilter （QObject *watched, QEvent *event）。

详情请参见QAbstractItemDelegate::handleEditorEvent()。

[virtual protected] void QStyledItemDelegate::initStyleOption(QStyleOptionViewItem *option, const QModelIndex &index) const

使用索引index 中的值初始化option 。当子类需要一个QStyleOptionViewItem ，但又不希望自行填入所有信息时，此方法非常有用。

另请参阅 QStyleOption::initFrom()。

QItemEditorFactory *QStyledItemDelegate::itemEditorFactory() const

返回项目委托所使用的编辑器工厂。如果未设置编辑器工厂，该函数将返回 null。

另请参阅 setItemEditorFactory()。

[override virtual] void QStyledItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const

重写：QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const。

使用给定的painter 和样式option ，为由index 指定的项目渲染委托。

此函数使用视图的QStyle 绘制该项目。

在子类中重写 paint 时，请使用initStyleOption() 以与QStyledItemDelegate 相同的方式设置option 。

在绘制过程中，应尽可能使用option 。特别是应利用其rect 变量来决定绘制位置，并利用其state 来判断该项是否启用或被选中。

绘制完成后，应确保将绘图器恢复到调用此函数时的初始状态。例如，在绘制前调用 `QPainter::save()`，绘制后调用 `QPainter::restore()` 可能会很有帮助。

另请参阅 QItemDelegate::paint()、QStyle::drawControl() 和QStyle::CE_ItemViewItem 。

[override virtual] void QStyledItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const

重写：QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const。

根据模型index 指定的数据模型项，设置editor 要显示和编辑的数据。

默认实现将数据存储在editor 控件的用户属性中。

另请参阅 QMetaProperty::isUser()。

void QStyledItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)

将项目委托所使用的编辑器工厂设置为指定的factory 。如果未设置编辑器工厂，项目委托将使用默认的编辑器工厂。

另请参阅 itemEditorFactory()。

[override virtual] void QStyledItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const

重写：QAbstractItemDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const。

从editor 控件获取数据，并将其存储在指定的model 中，位置为index 。

默认实现从editor 控件的用户属性中获取要存储在数据模型中的值。

另请参阅 QMetaProperty::isUser()。

[override virtual] QSize QStyledItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const

重写：QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const。

返回委托显示由index 指定的项目所需的大小，同时考虑由option 提供的样式信息。

此函数使用视图的QStyle 来确定项的大小。

另请参阅 QStyle::sizeFromContents() 和QStyle::CT_ItemViewItem 。

[override virtual] void QStyledItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const

重写了：QAbstractItemDelegate::updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const。

根据给定的样式option ，更新由index 指定的项目的editor 。

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