数据控件

数据控件用于展示列表、表格、树和属性面板。它们通常需要同时处理数据模型、滚动条、行高、选中状态和单元格样式。

控件类型

控件	子内容与能力	典型用途
`UIGQTableView`	表头、行项、复选框列、滚动条、自定义列控件、Model/View 数据	表格、业务列表、明细矩阵
`UIGQTreeView`	层级节点、表头、行高、展开折叠、滚动条	目录树、组织结构、配置树
`UIGQListView`	条目模板、选中状态、行高/列宽、滚动条	消息列表、模板列表、结果集合
`UIGQList`	简单列表项、选中状态、基础列表操作	简单选项列表、轻量数据集合
`UIGQPropertyList`	属性行、名称值结构、滚动区域	参数面板、对象配置、属性表

类继承关系

QWidget
  ├─ QTableView
  │   └─ UIGQTableView + IUIGQWidgetBase
  ├─ QTreeView
  │   └─ UIGQTreeView + IUIGQWidgetBase
  ├─ QListView
  │   └─ UIGQListView + IUIGQWidgetBase
  ├─ QListWidget
  │   └─ UIGQList + IUIGQWidgetBase
  └─ QScrollArea
      └─ UIGQScrollView + IUIGQWidgetBase
          └─ UIGQPropertyList

数据控件保留 Qt Model/View 或列表控件能力，WidgetKit 扩展表头、滚动条、行项样式、自定义列控件和主题配置。

UIGQTableView

UIGQTableView 基于 QTableView，增加自绘表头、行项样式、复选框列、滚动条样式和自定义列控件。

UIGQTableView* table = new UIGQTableView(parent);
table->setThemeName("DefaultTable");
table->setItemHeight(36);
table->setCheckstyle(true);
table->setScrollbarSize(false, 12);
table->setScrollbarSize(true, 12);
table->setModel(model);

常用接口：

接口	说明	参数	返回值
`setModel(QAbstractItemModel* model)`	设置表格数据模型。	`model`：Qt 数据模型。	`void`
`model() const`	获取当前数据模型。	无	`QAbstractItemModel*`
`setItemHeight(int height)`	设置行高。	`height`：行高像素。	`void`
`setCheckstyle(bool enabled)`	开启表格复选框样式。	`enabled`：是否启用。	`void`
`setColumnWidget(int column, UIGQContainer* widget)`	为列配置自定义控件。	`column`：列索引；`widget`：自定义容器。	`void`
`setScrollbarSize(bool isHorizontal, int size)`	设置滚动条厚度。	`isHorizontal`：是否水平；`size`：厚度。	`void`
`selectedRows()`	获取当前选择行。	无	`QList<int>`
`selectRow(int row)`	选择指定行。	`row`：行索引。	`void`
`headerCheckedChanged(bool checked)`	表头复选框变化信号。	`checked`：表头是否选中。	`void`
`customControlClicked(int row, QString name)`	自定义单元格控件点击信号。	`row`：行索引；`name`：控件名称。	`void`

UIGQTreeView

UIGQTreeView 适合目录、分组、配置树和层级数据，支持表头样式、项样式、行高和滚动条主题。

UIGQTreeView* tree = new UIGQTreeView(parent);
tree->setThemeName("DefaultTree");
tree->setItemHeight(30);
tree->setScrollbarSize(false, 12);
tree->setModel(model);

常用接口：

接口	说明	参数	返回值
`setModel(QAbstractItemModel* model)`	设置树数据模型。	`model`：Qt 数据模型。	`void`
`expand(const QModelIndex& index)`	展开节点。	`index`：节点索引。	`void`
`collapse(const QModelIndex& index)`	折叠节点。	`index`：节点索引。	`void`
`expandAll()`	展开全部节点。	无	`void`
`collapseAll()`	折叠全部节点。	无	`void`
`setHeaderHidden(bool hide)`	设置是否隐藏表头。	`hide`：是否隐藏。	`void`
`setItemHeight(int height)`	设置节点行高。	`height`：行高像素。	`void`
`setScrollbarSize(bool isHorizontal, int size)`	设置滚动条厚度。	`isHorizontal`：是否水平；`size`：厚度。	`void`

UIGQListView

UIGQListView 适合结果列表、消息列表和卡片式条目。可配置 item 模板、宽高、选中状态和滚动条。

UIGQListView* list = new UIGQListView(parent);
list->setThemeName("DefaultListView");
list->setItemHeight(48);
list->setItemWidth(280);
list->setEnableSelection(true);
list->setModel(model);

常用接口：

接口	说明	参数	返回值
`setModel(QAbstractItemModel* model)`	设置列表数据模型。	`model`：Qt 数据模型。	`void`
`setItemHeight(int height)`	设置条目高度。	`height`：高度像素。	`void`
`setItemWidth(int width)`	设置条目宽度。	`width`：宽度像素。	`void`
`setEnableSelection(bool enabled)`	设置是否允许选中。	`enabled`：是否允许。	`void`
`setCurrentIndex(const QModelIndex& index)`	设置当前项。	`index`：模型索引。	`void`
`currentIndex() const`	获取当前项。	无	`QModelIndex`
`clicked(const QModelIndex& index)`	条目点击信号。	`index`：模型索引。	`void`

UIGQList

UIGQList 是更轻量的列表封装，适合简单项集合。

接口	说明	参数	返回值
`addItem(const QString& text)`	添加文本项。	`text`：文本。	`void`
`addItems(const QStringList& labels)`	批量添加文本项。	`labels`：文本列表。	`void`
`clear()`	清空列表。	无	`void`
`setCurrentRow(int row)`	设置当前行。	`row`：行索引。	`void`
`currentRow() const`	获取当前行。	无	`int`
`itemClicked(QListWidgetItem* item)`	项点击信号。	`item`：点击项。	`void`

UIGQPropertyList

UIGQPropertyList 适合属性编辑和对象参数展示，继承滚动区域能力。

接口	说明	参数	返回值
`setThemeName(const QString& themeName)`	设置属性表主题。	`themeName`：主题名。	`void`
`setWidget(QWidget* widget)`	设置属性内容容器。	`widget`：内容控件。	`void`
`setWidgetResizable(bool resizable)`	内容是否跟随视口。	`resizable`：是否自适应。	`void`
`setScrollbarSize(bool isHorizontal, int size)`	设置滚动条厚度。	`isHorizontal`：是否水平；`size`：厚度。	`void`

使用建议

大数据列表保持 Qt Model/View 分层，WidgetKit 负责外观和交互一致性。
表格中需要操作按钮时，优先使用自定义列控件，避免把所有操作塞进文本。
横向内容较宽时显式配置水平滚动条主题，避免宽列被挤压。
属性面板适合低频配置，不建议承载大量实时数据。

Qt-UI WidgetKit 数据控件

数据控件

数据控件

控件类型

类继承关系

UIGQTableView

UIGQTreeView

UIGQListView

UIGQList

UIGQPropertyList

使用建议