QItemDelegate Class
QItemDelegate 类为模型中的数据项提供显示和编辑功能。更多
| Header： | #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 *editor, 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 XML 提供的标准视图使用的默认委托会将每个标准角色（由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 起，有两个委托类：QStyledItemDelegate不过，默认委托是QStyledItemDelegate 。这两个类是为视图中的项目绘制和提供编辑器的独立替代类。它们之间的区别在于，QStyledItemDelegate 使用当前样式来绘制项目。因此，我们建议在实现自定义委托或使用 Qt XML 样式表时使用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 所指定项目的 widget。parent widget 和样式option 用于控制编辑器 widget 的显示方式。
另请参阅 QAbstractItemDelegate::createEditor().
[protected] void QItemDelegate::drawBackground(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
s 为给定的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
使用给定的painter 和样式option 渲染rect 指定的矩形内的区域，表示该区域有焦点。
[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 *editor, QEvent *event)
重实现：QObject::eventFilter(QObject *watched, QEvent *event)。
如果给定的editor 是有效的QWidget ，且给定的event 已处理，则返回true ；否则返回false 。默认情况下会处理以下按键事件：
- Tab
- Backtab
- Enter
- Return
- Esc
对于Tab 、Backtab 、Enter 和Return 按键事件，editor 的数据将提交到模型中，编辑器将关闭。如果event 是Tab 按键，视图将在视图中的下一个项目上打开编辑器。同样，如果event 是Backtab 按键，视图将打开视图中上一个项目的编辑器。
如果事件是Esc 按键按下事件，则editor 将关闭，不会提交数据。
另请参阅 commitData() 和closeEditor()。
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 指定的项目渲染委托。
在子类中重新实现此函数时，应更新选项的rect 变量持有的区域，使用选项的state 变量确定要显示的项目的状态，并相应调整绘制方式。
例如，选中项与未选中项的显示方式可能不同，如下代码所示：
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 widget 的用户属性中。
另请参阅 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 widget 获取数据并存储到指定的model 项目index 中。
默认实现是从editor widget 的用户属性中获取要存储在数据模型中的值。
另请参阅 QMetaProperty::isUser() 。
[override virtual] QSize QItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
重实现：QAbstractItemDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) 常量。
根据option 提供的样式信息，返回委托显示index 指定的项目所需的大小。
重新实现此函数时，请注意如果是文本项目，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 。
© 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.
