QStandardItem的函数介绍

Qt版本

6.8.0

枚举

enum QStandardItem::ItemType

• QStandardItem::Type 标准项目的默认类型
• QStandardItem::UserType 自定义类型的最低值。低于 UserType 的值由 Qt 保留。

公共函数

1. QStandardItem()

• 作用：创建空项，无文本、图标，初始无子项。
• 参数：无。
• 返回值：QStandardItem 对象指针。
• 示例：

  QStandardItem *item = new QStandardItem();
  

2. QStandardItem(const QString &text)

• 作用：创建包含文本的项。
• 参数：
  • text：项的显示文本（Qt::DisplayRole）。
• 返回值：QStandardItem 对象指针。
• 示例：

  QStandardItem *item = new QStandardItem("Apple");
  

3. QStandardItem(const QIcon &icon, const QString &text)

• 作用：创建包含图标和文本的项。
• 参数：
  • icon：项的图标（Qt::DecorationRole）。
  • text：项的显示文本。
• 返回值：QStandardItem 对象指针。
• 示例：

  QIcon icon(":/images/apple.png");
  QStandardItem *item = new QStandardItem(icon, "Apple");
  

4. QStandardItem(int rows, int columns = 1)

• 作用：创建预分配子项空间的项（用于树形结构）。
• 参数：
  • rows：子项的行数。
  • columns：子项的列数（默认1）。
• 返回值：QStandardItem 对象指针。
• 示例：

  QStandardItem *parent = new QStandardItem(3, 2); // 预留3行2列子项空间
  

5. virtual ~QStandardItem()

• 作用：析构函数，销毁项及其所有子项。
• 参数：无。
• 返回值：无。

---

6. QString accessibleDescription() const

• 作用：返回辅助功能描述（Qt::AccessibleDescriptionRole）。
• 参数：无。
• 返回值：描述文本。
• 示例：

  QString desc = item->accessibleDescription();
  

7. QString accessibleText() const

• 作用：返回辅助功能文本（Qt::AccessibleTextRole）。
• 参数：无。
• 返回值：文本内容。
• 示例：

  QString text = item->accessibleText();
  

8. void appendColumn(const QList<QStandardItem *> &items)

• 作用：在末尾添加一列子项。
• 参数：
  • items：子项列表（按行填充）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> column;
  column << new QStandardItem("A") << new QStandardItem("B");
  parent->appendColumn(column); // 添加一列
  

9. void appendRow(const QList<QStandardItem *> &items)

• 作用：在末尾添加一行多列子项。
• 参数：
  • items：子项列表（按列填充）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> row;
  row << new QStandardItem("Name") << new QStandardItem("Age");
  parent->appendRow(row);
  

10. void appendRow(QStandardItem *item)

• 作用：在末尾添加一行单列子项（位于第0列）。
• 参数：
  • item：子项指针。
• 返回值：无。
• 示例：

  parent->appendRow(new QStandardItem("Child"));
  

11. void appendRows(const QList<QStandardItem *> &items)

• 作用：在末尾添加多行子项（每行单列）。
• 参数：
  • items：子项列表（每项占一行）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> rows;
  rows << new QStandardItem("Row1") << new QStandardItem("Row2");
  parent->appendRows(rows); // 添加两行
  

12. QBrush background() const

• 作用：返回项的背景颜色（Qt::BackgroundRole）。
• 参数：无。
• 返回值：背景画刷。
• 示例：

  QBrush brush = item->background();
  

13. Qt::CheckState checkState() const

• 作用：返回项的勾选状态（Qt::CheckStateRole）。
• 参数：无。
• 返回值：Qt::Unchecked、Qt::PartiallyChecked 或 Qt::Checked。
• 示例：

  Qt::CheckState state = item->checkState();
  

14. QStandardItem *child(int row, int column = 0) const

• 作用：获取指定位置的子项。
• 参数：
  • row：行索引。
  • column：列索引（默认0）。
• 返回值：子项指针，不存在则返回 nullptr。
• 示例：

  QStandardItem *child = parent->child(0, 1); // 获取第0行第1列的子项
  

15. void clearData()

• 作用：清除项的所有数据（重置所有角色为默认值）。
• 参数：无。
• 返回值：无。
• 示例：

  item->clearData(); // 清空文本、图标等
  

16. virtual QStandardItem *clone() const

• 作用：创建项的深拷贝。
• 参数：无。
• 返回值：克隆后的新项指针。
• 示例：

  QStandardItem *clone = item->clone();
  

17. int column() const

• 作用：返回项在其父项中的列索引。
• 参数：无。
• 返回值：列索引（若无父项返回0）。
• 示例：

  int col = item->column();
  

18. int columnCount() const

• 作用：返回项的子项列数。
• 参数：无。
• 返回值：子项列数。
• 示例：

  int cols = parent->columnCount(); // 例如返回2
  

19. virtual QVariant data(int role = Qt::UserRole + 1) const

• 作用：获取指定角色的数据。
• 参数：
  • role：数据角色（如 Qt::DisplayRole）。
• 返回值：存储数据的 QVariant。
• 示例：

  QVariant text = item->data(Qt::DisplayRole); // 等同于 item->text()
  

20. Qt::ItemFlags flags() const

• 作用：返回项的交互标志（如是否可编辑）。
• 参数：无。
• 返回值：Qt::ItemFlags 的组合。
• 示例：

  Qt::ItemFlags flags = item->flags();
  

21. QFont font() const

• 作用：返回项的字体（Qt::FontRole）。
• 参数：无。
• 返回值：字体对象。
• 示例：

  QFont font = item->font();
  

22. QBrush foreground() const

• 作用：返回项的文本颜色（Qt::ForegroundRole）。
• 参数：无。
• 返回值：前景画刷。
• 示例：

  QBrush color = item->foreground();
  

23. bool hasChildren() const

• 作用：返回项是否有子项。
• 参数：无。
• 返回值：true 表示有子项。
• 示例：

  if (parent->hasChildren()) { /* ... */ }
  

24. QIcon icon() const

• 作用：返回项的图标（Qt::DecorationRole）。
• 参数：无。
• 返回值：图标对象。
• 示例：

  QIcon icon = item->icon();
  

25. QModelIndex index() const

• 作用：返回项在模型中的索引。
• 参数：无。
• 返回值：QModelIndex 对象。
• 示例：

  QModelIndex idx = item->index();
  

26. void insertColumn(int column, const QList<QStandardItem *> &items)

• 作用：在指定列插入子项。
• 参数：
  • column：列索引。
  • items：子项列表（按行填充）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> columnData;
  columnData << new QStandardItem("X") << new QStandardItem("Y");
  parent->insertColumn(1, columnData); // 在第1列插入两行数据
  

27. void insertColumns(int column, int count)

• 作用：在指定列插入空列。
• 参数：
  • column：起始列索引。
  • count：插入的列数。
• 返回值：无。
• 示例：

  parent->insertColumns(1, 2); // 在第1列插入2个空列
  

28. void insertRow(int row, const QList<QStandardItem *> &items)

• 作用：在指定行插入多列子项。
• 参数：
  • row：行索引。
  • items：子项列表（按列填充）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> rowItems;
  rowItems << new QStandardItem("A") << new QStandardItem("B");
  parent->insertRow(0, rowItems); // 在第0行插入两列
  

29. void insertRow(int row, QStandardItem *item)

• 作用：在指定行插入单列子项。
• 参数：
  • row：行索引。
  • item：子项指针。
• 返回值：无。
• 示例：

  parent->insertRow(0, new QStandardItem("New Item"));
  

30. void insertRows(int row, const QList<QStandardItem *> &items)

• 作用：在指定行插入多行单列子项。
• 参数：
  • row：起始行索引。
  • items：子项列表（每个项占一行）。
• 返回值：无。
• 示例：

  QList<QStandardItem*> rows;
  rows << new QStandardItem("Row1") << new QStandardItem("Row2");
  parent->insertRows(0, rows); // 在第0行插入两行
  

31. void insertRows(int row, int count)

• 作用：在指定行插入空行。
• 参数：
  • row：起始行索引。
  • count：插入的行数。
• 返回值：无。
• 示例：

  parent->insertRows(0, 3); // 在第0行插入3个空行
  

32. bool isAutoTristate() const

• 作用：返回项是否自动三态（子项勾选状态变化时父项自动更新）。
• 参数：无。
• 返回值：true 表示启用自动三态。
• 示例：

  if (item->isAutoTristate()) { /* ... */ }
  

33. bool isCheckable() const

• 作用：返回项是否可勾选。
• 参数：无。
• 返回值：true 表示可勾选。
• 示例：

  if (item->isCheckable()) { /* ... */ }
  

34. bool isDragEnabled() const

• 作用：返回项是否允许拖动。
• 参数：无。
• 返回值：true 表示允许拖动。
• 示例：

  if (item->isDragEnabled()) { /* ... */ }
  

35. bool isDropEnabled() const

• 作用：返回项是否允许接收拖放数据。
• 参数：无。
• 返回值：true 表示允许接收。
• 示例：

  if (item->isDropEnabled()) { /* ... */ }
  

36. bool isEditable() const

• 作用：返回项是否可编辑。
• 参数：无。
• 返回值：true 表示可编辑。
• 示例：

  if (item->isEditable()) { /* ... */ }
  

37. bool isEnabled() const

• 作用：返回项是否启用（可交互）。
• 参数：无。
• 返回值：true 表示启用。
• 示例：

  if (item->isEnabled()) { /* ... */ }
  

38. bool isSelectable() const

• 作用：返回项是否可选择。
• 参数：无。
• 返回值：true 表示可选择。
• 示例：

  if (item->isSelectable()) { /* ... */ }
  

39. bool isUserTristate() const

• 作用：返回项是否允许用户切换三态（Qt::PartiallyChecked）。
• 参数：无。
• 返回值：true 表示允许。
• 示例：

  if (item->isUserTristate()) { /* ... */ }
  

40. QStandardItemModel *model() const

• 作用：返回项所属的模型。
• 参数：无。
• 返回值：模型指针，若项未附加到模型则返回 nullptr。
• 示例：

  QStandardItemModel *model = item->model();
  

41. virtual void multiData(QModelRoleDataSpan roleDataSpan) const (Qt 6.0+)

• 作用：批量获取多项角色数据（优化性能）。
• 参数：
  • roleDataSpan：角色数据跨度对象。
• 返回值：无。
• 示例（高级用法）：

  // 通常由模型内部调用，用户较少直接使用
  

42. QStandardItem *parent() const

• 作用：返回项的父项。
• 参数：无。
• 返回值：父项指针，若无父项返回 nullptr。
• 示例：

  QStandardItem *parent = child->parent();
  

43. virtual void read(QDataStream &in)

• 作用：从数据流中读取项的数据（用于序列化）。
• 参数：
  • in：输入数据流。
• 返回值：无。
• 示例：

  QDataStream stream(&file);
  item->read(stream);
  

44. void removeColumn(int column)

• 作用：移除指定列的所有子项。
• 参数：
  • column：列索引。
• 返回值：无。
• 示例：

  parent->removeColumn(1); // 移除第1列
  

45. void removeColumns(int column, int count)

• 作用：移除从指定列开始的多个列。
• 参数：
  • column：起始列索引。
  • count：移除的列数。
• 返回值：无。
• 示例：

  parent->removeColumns(1, 2); // 移除第1列和第2列
  

46. void removeRow(int row)

• 作用：移除指定行的所有子项。
• 参数：
  • row：行索引。
• 返回值：无。
• 示例：

  parent->removeRow(0); // 移除第0行
  

47. void removeRows(int row, int count)

• 作用：移除从指定行开始的多个行。
• 参数：
  • row：起始行索引。
  • count：移除的行数。
• 返回值：无。
• 示例：

  parent->removeRows(0, 2); // 移除第0行和第1行
  

48. int row() const

• 作用：返回项在其父项中的行索引。
• 参数：无。
• 返回值：行索引（若无父项返回0）。
• 示例：

  int row = child->row(); // 例如返回0
  

49. int rowCount() const

• 作用：返回该项下有多少行子项（即有多少子节点）。
• 参数：无
• 返回值：子项的行数（int）
• 应用：用于遍历树形结构或表格结构的子项。
• 示例：

  int rows = item->rowCount(); // 获取item下有多少行子项
  

---

50. void setAccessibleDescription(const QString &accessibleDescription)

• 作用：为无障碍辅助技术（如屏幕阅读器）设置描述信息。
• 参数：accessibleDescription：描述文本
• 返回值：无
• 应用：提升应用的可访问性。
• 示例：

  item->setAccessibleDescription("这是一个文件夹节点");
  

---

51. void setAccessibleText(const QString &accessibleText)

• 作用：为无障碍辅助技术设置主要文本。
• 参数：accessibleText：主要文本
• 返回值：无
• 应用：辅助残障人士理解界面内容。
• 示例：

  item->setAccessibleText("文件夹");
  

---

4. void setAutoTristate(bool tristate)

• 作用：设置复选框是否自动支持三态（未选中、部分选中、选中）。
• 参数：tristate：是否三态
• 返回值：无
• 应用：树形控件的父节点复选框常用。
• 示例：

  item->setAutoTristate(true);
  

---

5. void setBackground(const QBrush &brush)

• 作用：设置项的背景色或背景画刷。
• 参数：brush：QBrush对象
• 返回值：无
• 应用：高亮、分组等视觉效果。
• 示例：

  item->setBackground(QBrush(Qt::yellow));
  

---

6. void setCheckState(Qt::CheckState state)

• 作用：设置复选框的状态（选中、未选中、部分选中）。
• 参数：state：Qt::Unchecked, Qt::PartiallyChecked, Qt::Checked
• 返回值：无
• 应用：树形控件的多选场景。
• 示例：

  item->setCheckState(Qt::Checked);
  

---

7. void setCheckable(bool checkable)

• 作用：设置该项是否带有复选框。
• 参数：checkable：是否可勾选
• 返回值：无
• 应用：需要用户选择的场景。
• 示例：

  item->setCheckable(true);
  

---

8. void setChild(int row, int column, QStandardItem *item)

• 作用：在指定行列设置子项。
• 参数：row、column、item
• 返回值：无
• 应用：构建树或表格结构。
• 示例：

  QStandardItem *child = new QStandardItem("子项");
  item->setChild(0, 0, child);
  

---

9. void setChild(int row, QStandardItem *item)

• 作用：在指定行第0列设置子项。
• 参数：row、item
• 返回值：无
• 应用：树结构常用。
• 示例：

  item->setChild(0, new QStandardItem("子项"));
  

---

10. void setColumnCount(int columns)

• 作用：设置该项的列数。
• 参数：columns：列数
• 返回值：无
• 应用：表格或多列树结构。
• 示例：

  item->setColumnCount(3);
  

---

11. virtual void setData(const QVariant &value, int role = Qt::UserRole + 1)

• 作用：为该项设置数据，可指定不同的角色（如显示、编辑、用户自定义等）。
• 参数：value：数据，role：角色
• 返回值：无
• 应用：自定义数据存储、显示内容等。
• 示例：

  item->setData("自定义数据", Qt::UserRole + 1);
  

---

12. void setDragEnabled(bool dragEnabled)

• 作用：设置该项是否可被拖拽。
• 参数：dragEnabled：是否可拖拽
• 返回值：无
• 应用：拖拽排序、拖拽到其他控件。
• 示例：

  item->setDragEnabled(true);
  

---

13. void setDropEnabled(bool dropEnabled)

• 作用：设置该项是否可作为拖拽目标。
• 参数：dropEnabled：是否可放置
• 返回值：无
• 应用：拖拽到该项上时能否接收。
• 示例：

  item->setDropEnabled(true);
  

---

14. void setEditable(bool editable)

• 作用：设置该项是否可编辑。
• 参数：editable：是否可编辑
• 返回值：无
• 应用：用户是否能直接修改内容。
• 示例：

  item->setEditable(false);
  

---

15. void setEnabled(bool enabled)

• 作用：设置该项是否可用（灰化/激活）。
• 参数：enabled：是否可用
• 返回值：无
• 应用：禁用某些项。
• 示例：

  item->setEnabled(false);
  

---

16. void setFlags(Qt::ItemFlags flags)

• 作用：设置项的标志（可选、可编辑、可拖拽等）。
• 参数：flags：标志位
• 返回值：无
• 应用：自定义项的行为。
• 示例：

  item->setFlags(Qt::ItemIsSelectable | Qt::ItemIsEditable);
  

---

17. void setFont(const QFont &font)

• 作用：设置项的字体。
• 参数：font：字体
• 返回值：无
• 应用：突出显示、区分不同项。
• 示例：

  item->setFont(QFont("Arial", 12));
  

---

18. void setForeground(const QBrush &brush)

• 作用：设置项的前景色（通常是文本颜色）。
• 参数：brush：画刷
• 返回值：无
• 应用：高亮、警告等。
• 示例：

  item->setForeground(QBrush(Qt::red));
  

---

19. void setIcon(const QIcon &icon)

• 作用：设置项的图标。
• 参数：icon：图标
• 返回值：无
• 应用：文件、文件夹等有图标的场景。
• 示例：

  item->setIcon(QIcon(":/icon.png"));
  

---

20. void setRowCount(int rows)

• 作用：设置该项的行数（子项行数）。
• 参数：rows：行数
• 返回值：无
• 应用：预分配子项空间。
• 示例：

  item->setRowCount(5);
  

---

21. void setSelectable(bool selectable)

• 作用：设置该项是否可被选中。
• 参数：selectable：是否可选
• 返回值：无
• 应用：只读项、分组项等。
• 示例：

  item->setSelectable(false);
  

---

22. void setSizeHint(const QSize &size)

• 作用：设置项的建议显示大小。
• 参数：size：QSize对象
• 返回值：无
• 应用：自定义行高、列宽。
• 示例：

  item->setSizeHint(QSize(100, 30));
  

---

23. void setStatusTip(const QString &statusTip)

• 作用：设置鼠标悬停时状态栏显示的提示。
• 参数：statusTip：提示文本
• 返回值：无
• 应用：辅助用户理解项的作用。
• 示例：

  item->setStatusTip("这是状态栏提示");
  

---

24. void setText(const QString &text)

• 作用：设置项的显示文本。
• 参数：text：文本
• 返回值：无
• 应用：显示内容。
• 示例：

  item->setText("新文本");
  

---

25. void setTextAlignment(Qt::Alignment alignment)

• 作用：设置文本的对齐方式。
• 参数：alignment：对齐方式
• 返回值：无
• 应用：居中、右对齐等。
• 示例：

  item->setTextAlignment(Qt::AlignCenter);
  

---

26. void setToolTip(const QString &toolTip)

• 作用：设置鼠标悬停时的提示文本。
• 参数：toolTip：提示文本
• 返回值：无
• 应用：补充说明。
• 示例：

  item->setToolTip("这是悬浮提示");
  

---

27. void setUserTristate(bool tristate)

• 作用：设置用户是否可以手动设置三态复选框。
• 参数：tristate：是否允许
• 返回值：无
• 应用：树形控件三态复选框。
• 示例：

  item->setUserTristate(true);
  

---

28. void setWhatsThis(const QString &whatsThis)

• 作用：设置 What’s This 帮助文本（Shift+F1）。
• 参数：whatsThis：帮助文本
• 返回值：无
• 应用：详细帮助说明。
• 示例：

  item->setWhatsThis("详细帮助信息");
  

---

29. QSize sizeHint() const

• 作用：获取项的建议显示大小。
• 参数：无
• 返回值：QSize对象
• 应用：自定义行高、列宽时使用。
• 示例：

  QSize sz = item->sizeHint();
  

---

30. void sortChildren(int column, Qt::SortOrder order = Qt::AscendingOrder)

• 作用：对子项按指定列排序。
• 参数：column：列，order：排序顺序
• 返回值：无
• 应用：树形控件排序。
• 示例：

  item->sortChildren(0, Qt::DescendingOrder);
  

---

31. QString statusTip() const

• 作用：获取状态栏提示文本。
• 参数：无
• 返回值：QString
• 应用：显示状态栏提示。
• 示例：

  QString tip = item->statusTip();
  

---

32. QStandardItem *takeChild(int row, int column = 0)

• 作用：移除并返回指定位置的子项。
• 参数：row、column
• 返回值：QStandardItem*，被移除的子项
• 应用：动态修改树结构。
• 示例：

  QStandardItem *child = item->takeChild(0, 0);
  

---

33. QList<QStandardItem *> takeColumn(int column)

• 作用：移除并返回指定列的所有子项。
• 参数：column
• 返回值：QList<QStandardItem*>
• 应用：批量操作。
• 示例：

  QList<QStandardItem*> col = item->takeColumn(1);
  

---

34. QList<QStandardItem *> takeRow(int row)

• 作用：移除并返回指定行的所有子项。
• 参数：row
• 返回值：QList<QStandardItem*>
• 应用：批量操作。
• 示例：

  QList<QStandardItem*> row = item->takeRow(0);
  

---

35. QString text() const

• 作用：获取项的显示文本。
• 参数：无
• 返回值：QString
• 应用：读取内容。
• 示例：

  QString t = item->text();
  

---

36. Qt::Alignment textAlignment() const

• 作用：获取文本对齐方式。
• 参数：无
• 返回值：Qt::Alignment
• 应用：布局相关。
• 示例：

  Qt::Alignment align = item->textAlignment();
  

---

37. QString toolTip() const

• 作用：获取悬浮提示文本。
• 参数：无
• 返回值：QString
• 应用：显示提示。
• 示例：

  QString tip = item->toolTip();
  

---

38. virtual int type() const

• 作用：返回项的类型（可用于区分自定义子类）。
• 参数：无
• 返回值：int
• 应用：多态、类型判断。
• 示例：

  int t = item->type();
  

---

39. QString whatsThis() const

• 作用：获取 What’s This 帮助文本。
• 参数：无
• 返回值：QString
• 应用：帮助系统。
• 示例：

  QString help = item->whatsThis();
  

---

40. virtual void write(QDataStream &out) const

• 作用：将项的数据写入数据流（序列化）。
• 参数：out：QDataStream
• 返回值：无
• 应用：保存、导出。
• 示例：

  QDataStream out(&file);
  item->write(out);
  

---

41. virtual bool operator<(const QStandardItem &other) const

• 作用：比较两个项的大小（排序用）。
• 参数：other：另一个项
• 返回值：bool
• 应用：自定义排序。
• 示例：

  bool less = (*item1 < *item2);
  

---

保护函数

42. QStandardItem(const QStandardItem &other)

• 作用：拷贝构造函数，复制一个项。
• 参数：other
• 返回值：无
• 应用：复制项。
• 示例：

  QStandardItem copy(*item);
  

---

43. void emitDataChanged()

• 作用：发出数据已更改的信号（通常在自定义子类中用）。
• 参数：无
• 返回值：无
• 应用：通知视图刷新。

---

44. QStandardItem & operator=(const QStandardItem &other)

• 作用：赋值运算符，复制另一个项的内容。
• 参数：other
• 返回值：自身引用
• 应用：赋值。
• 示例：

  *item1 = *item2;