QItemDelegate Class
QItemDelegate 类为模型中的数据项提供了显示和编辑功能。更多内容...
| 头文件： | #include <QItemDelegate> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QAbstractItemDelegate |
属性
- clipping : bool
公共函数
| QItemDelegate(QObject *parent = nullptr) | |
| virtual | ~QItemDelegate() |
| bool | hasClipping() const |
| QItemEditorFactory * | itemEditorFactory() const |
| void | setClipping(bool clip) |
| 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 |
受保护函数
| void | drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const |
| virtual void | drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const |
| virtual void | drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const |
| virtual void | drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const |
| virtual void | drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const |
重新实现的受保护函数
| virtual bool | editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override |
| virtual bool | eventFilter(QObject *object, QEvent *event) override |
详细说明
QItemDelegate 可用于为基于QAbstractItemView 子类的项目视图提供自定义显示功能和编辑器控件。为此目的使用委托，可以实现独立于模型和视图的显示与编辑机制的自定义和开发。
QItemDelegate类是模型/视图类之一，属于Qt的模型/视图框架。请注意，QStyledItemDelegate 已接管了绘制Qt项目视图的任务。我们建议在创建新委托时使用QStyledItemDelegate 。
在标准视图中显示来自自定义模型的项目时，通常只需确保模型为每个roles 返回适当的数据，这些 决定了项目在视图中的外观。 Qt 标准视图使用的默认委托会利用这些角色信息，以用户期望的大多数常见形式显示项目。不过，有时需要对项目的外观进行比默认委托所能提供的更精细的控制。
本类提供了在视图中绘制项目数据以及编辑项目模型数据的函数的默认实现。QAbstractItemDelegate 中定义了paint()和sizeHint()虚拟函数的默认实现，以确保委托能够实现视图所期望的正确基本行为。您可以在子类中重写这些函数，以自定义项目的外观。
在项目视图中编辑数据时，QItemDelegate 会提供一个编辑器控件，该控件在编辑过程中会显示在视图上方。 编辑器通过QItemEditorFactory 创建；由QItemEditorFactory 提供的默认静态实例会被安装到所有项目委托上。您可以使用setItemEditorFactory()设置自定义工厂，或使用QItemEditorFactory::setDefaultFactory()设置新的默认工厂。被编辑的是项目模型中通过Qt::EditRole 存储的数据。
此处仅重写了基于小部件的委托的标准编辑函数：
- createEditor() 返回用于更改模型中数据的控件，可重写该方法以自定义编辑行为。
- setEditorData() 向控件提供待操作的数据。
- updateEditorGeometry() 确保编辑器在项目视图中正确显示。
- setModelData() 将更新后的数据返回给模型。
closeEditor() 信号表示用户已完成数据编辑，编辑器控件可以被销毁。
标准角色和数据类型
Qt 随附的标准视图所使用的默认委托将每个标准角色（由Qt::ItemDataRole 定义）与特定的数据类型相关联。如下表所述，返回这些类型数据的模型会影响委托的外观。
如果默认委托无法满足您在显示或数据编辑方面的自定义需求，可以继承 QItemDelegate 来实现所需的行为。
继承
在继承 QItemDelegate 以创建一个使用自定义渲染器显示项目的委托时，必须确保该委托能够针对所有必需的状态（例如：选中、禁用、勾选）正确渲染项目。paint() 函数的文档中包含了一些提示，说明了如何实现这一点。
您可以通过使用 `QItemEditorFactory` 提供自定义编辑器。以下代码演示了如何通过默认项目编辑器工厂，使自定义编辑器可供委托使用。
QItemEditorFactory *editorFactory = new QItemEditorFactory;
QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>();
editorFactory->registerEditor(QMetaType::QDateTime, creator);
QItemEditorFactory::setDefaultFactory(editorFactory);设置默认工厂后，所有标准项目委托都会使用它（包括在设置默认工厂之前创建的委托）。
这样，您就可以避免继承 QItemDelegate，并且指定类型（例如QMetaType::QDateTime ）的所有值都将使用提供的编辑器进行编辑（如上例中的MyFancyDateTimeEdit ）。
另一种方法是重写createEditor()、setEditorData()、setModelData() 和updateEditorGeometry()。此过程在“模型/视图编程”概述文档中进行了说明。
QStyledItemDelegate 与 QItemDelegate
自 Qt 4.4 起，存在两个委托类：QItemDelegate 和QStyledItemDelegate 。不过，默认委托类是QStyledItemDelegate 。这两个类是独立的替代方案，分别用于绘制视图中的项目以及为其提供编辑器。 它们之间的区别在于，QStyledItemDelegate 使用当前样式来绘制其项目。因此，在实现自定义委托或使用 Qt 样式表时，我们建议将QStyledItemDelegate 作为基类。除非自定义委托需要使用样式进行绘制，否则这两种类所需的代码应是相同的。
另请参阅 “委托类”、QStyledItemDelegate 以及QAbstractItemDelegate 。
属性文档
clipping : bool
是否应由委托截断绘制事件
此属性将把绘制裁剪范围设置为项目的大小。默认值为启用。当图像尺寸大于项目尺寸时，此属性非常有用。
访问函数：
| bool | hasClipping() const |
| void | setClipping(bool clip) |
成员函数文档
[explicit] QItemDelegate::QItemDelegate(QObject *parent = nullptr)
根据给定的parent 构建一个项目委托。
[virtual noexcept] QItemDelegate::~QItemDelegate()
销毁该项的委托对象。
[override virtual] QWidget *QItemDelegate::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()。
[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
根据给定的index ，使用给定的painter 和样式option 渲染该项的背景。
[virtual protected] void QItemDelegate::drawCheck(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, Qt::CheckState state) const
在由rect 指定的矩形内绘制一个复选标记，使用给定的painter 和样式option ，并采用给定的state 。
[virtual protected] void QItemDelegate::drawDecoration(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QPixmap &pixmap) const
使用给定的painter 和样式option ，在由rect 指定的矩形内渲染装饰元素pixmap 。
[virtual protected] void QItemDelegate::drawDisplay(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect, const QString &text) const
使用给定的painter 和样式option ，在由rect 指定的矩形内渲染项视图text 。
[virtual protected] void QItemDelegate::drawFocus(QPainter *painter, const QStyleOptionViewItem &option, const QRect &rect) const
渲染由rect 指定的矩形区域，并使用给定的painter 和样式option ，以表明该区域处于焦点状态。
[override virtual protected] bool QItemDelegate::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 QItemDelegate::eventFilter(QObject *object, QEvent *event)
重写了：QObject::eventFilter （QObject *watched, QEvent *event）。
详情请参见QAbstractItemDelegate::handleEditorEvent()。
QItemEditorFactory *QItemDelegate::itemEditorFactory() const
返回项目委托所使用的编辑器工厂。如果未设置编辑器工厂，该函数将返回 null。
另请参阅 setItemEditorFactory()。
[override virtual] void QItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
重写：QAbstractItemDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const。
使用给定的painter 和样式option 渲染由index 指定的项的委托。
在子类中重写此函数时，应使用选项的state 变量来确定要显示的项的状态，并据此调整绘制方式，同时更新选项的rect 变量所占用的区域。
例如，已选中的项目可能需要与未选中的项目以不同的方式显示，如下面的代码所示：
if (option.state & QStyle::State_Selected)
painter->fillRect(option.rect, option.palette.highlight());绘制完成后，应确保将绘制器恢复到调用此函数时的初始状态。例如，在绘制前调用QPainter::save()，绘制后调用QPainter::restore() 可能会很有帮助。
另请参阅 QStyle::State 。
[override virtual] void QItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
重写：QAbstractItemDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const。
根据模型index 指定的数据模型项，设置editor 要显示和编辑的数据。
默认实现将数据存储在editor 小部件的用户属性中。
另请参阅 QMetaProperty::isUser()。
void QItemDelegate::setItemEditorFactory(QItemEditorFactory *factory)
将项目委托所使用的编辑器工厂设置为指定的factory 。如果未设置编辑器工厂，项目委托将使用默认的编辑器工厂。
另请参阅 itemEditorFactory()。
[override virtual] void QItemDelegate::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 QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
重写：QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const。
返回委托显示由index 指定的项目所需的大小，同时考虑由option 提供的样式信息。
在重写此函数时，请注意：对于文本项，QItemDelegate 会向文本长度添加一个边距（即 2 *QStyle::PM_FocusFrameHMargin ）。
[override virtual] void QItemDelegate::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.
