布局与容器控件

布局控件负责组织页面结构、尺寸策略、滚动区域和多页面切换。建议先用 UIGQContainer 搭出页面骨架，再根据内容复杂度引入 UIGQScrollView、UIGQStackContainer、UIGQSplitter 等控件。

控件类型

控件	子内容与能力	典型用途
`UIGQContainer`	子控件布局、内边距、间距、绝对停靠、自动计算绝对停靠尺寸、主题背景	页面骨架、卡片、工具区、标题栏右侧区域
`UIGQStackContainer`	多页面集合、当前页切换、页面尺寸同步	dashboard、设置页、工作区视图切换
`UIGQScrollView`	内容窗口、水平/垂直滚动条、滚动条主题和尺寸	长表单、列表面板、可滚动内容区
`UIGQSplitter`	可拖动分隔条、左右/上下区域	主从面板、属性区、可调整工作区
`UIGQSpacer`	弹性占位、固定占位	推开控件、对齐工具栏内容
`UIGQGroupBox`	标题、边框、分组内容区	表单分组、设置分组、视觉归类

类继承关系

QWidget
  ├─ UIGQContainer + IUIGQWidgetBase
  ├─ UIGQStackContainer + IUIGQWidgetBase
  ├─ QScrollArea
  │   └─ UIGQScrollView + IUIGQWidgetBase
  │       └─ UIGQPropertyList
  ├─ UIGQSplitter + IUIGQWidgetBase
  ├─ UIGQSpacer + IUIGQWidgetBase
  └─ UIGQGroupBox + IUIGQWidgetBase

布局控件以 QWidget 或 Qt 滚动区域为基础，使用 IUIGQWidgetBase 接入主题、布局比例、尺寸策略和基础序列化能力。UIGQPropertyList 继承自 UIGQScrollView，因此也复用滚动区域能力。

UIGQContainer

UIGQContainer 是 WidgetKit 最常用的布局容器，支持横向、纵向、流式布局和绝对停靠。可通过主题名读取当前主题中的背景样式，也可以通过 C++ 直接设置布局参数。

UIGQContainer* card = new UIGQContainer(parent);
card->setObjectName("settingsCard");
card->setThemeName("CardBg");
card->setChildLayout(UIGQContainer::kVertical);
card->setChildSpace(12);
card->setChildPadding(16, 16, 16, 16);
card->addChildWidget(titleLabel);
card->addChildWidget(formArea, 1);

绝对停靠常用于标题栏按钮、用户信息、浮动工具条等不参与主布局计算的控件。

UIGQContainer* profile = new UIGQContainer(parent);
profile->setChildLayout(UIGQContainer::kHorizontal);
profile->setAbsoluteDock(UIG_RIGHT_BOTTOM, UIG_LEFT_TOP, -184, 8);
profile->setAbsoluteDockAutoSize(true);

常用接口：

接口	说明	参数	返回值
`setChildLayout(AutoChildLayout layout)`	设置子控件排列方式。	`layout`：横向、纵向、横向流式、纵向流式等布局枚举。	`void`
`setChildSpace(int space)`	设置子控件间距。	`space`：间距像素。	`void`
`setChildPadding(int left, int top, int right, int bottom)`	设置容器内边距。	四个方向的像素值。	`void`
`addChildWidget(QWidget* widget, int ratio = 0)`	添加子控件并可设置布局比例。	`widget`：子控件；`ratio`：占比权重。	`void`
`removeChildWidget(QWidget* widget)`	从容器布局中移除子控件。	`widget`：目标子控件。	`void`
`setThemeName(const QString& themeName)`	绑定主题名。	`themeName`：主题配置名称。	`void`
`setDrawBackground(bool draw)`	控制是否绘制容器背景。	`draw`：是否绘制背景。	`void`
`setAbsoluteDock(DockLayoutType hor, DockLayoutType ver, int offsetX = 0, int offsetY = 0)`	设置绝对停靠位置和偏移。	`hor/ver`：水平与垂直停靠；`offsetX/offsetY`：偏移。	`void`
`setAbsoluteDockAutoSize(bool enabled)`	绝对停靠时按子控件计算合适尺寸。	`enabled`：是否启用自动尺寸。	`void`
`forceResize()`	立即重新计算布局和子控件尺寸。	无	`void`

UIGQStackContainer

UIGQStackContainer 用于在一个固定区域内切换多个页面。页面尺寸会跟随当前容器刷新，适合 dashboard、设置页、工作台页签等场景。

UIGQStackContainer* stack = new UIGQStackContainer(parent);
stack->setThemeName("WorkspaceBg");
stack->addWidget(dashboardPage);
stack->addWidget(settingsPage);
stack->setCurrentIndex(0);

常用接口：

接口	说明	参数	返回值
`addWidget(QWidget* widget)`	添加页面。	`widget`：要添加的页面控件。	`int`
`insertWidget(int index, QWidget* widget)`	插入页面。	`index`：插入位置；`widget`：页面控件。	`int`
`removeWidget(QWidget* widget)`	移除页面。	`widget`：要移除的页面控件。	`void`
`setCurrentIndex(int index)`	切换当前页。	`index`：目标页面索引。	`void`
`currentIndex() const`	获取当前页索引。	无	`int`
`currentWidget() const`	获取当前页控件。	无	`QWidget*`
`widget(int index) const`	获取指定页面。	`index`：页面索引。	`QWidget*`

UIGQScrollView

UIGQScrollView 封装滚动区域和自绘滚动条，适合长内容页面。水平滚动条和垂直滚动条应分别设置方向与主题，避免横纵样式混用。

UIGQScrollView* scroll = new UIGQScrollView(parent);
scroll->setThemeName("FormScrollView");
scroll->setScrollbarSize(false, 12); // vertical
scroll->setScrollbarSize(true, 12);  // horizontal
scroll->setVScrollPos(0);

常用接口：

接口	说明	参数	返回值
`setWidget(QWidget* widget)`	设置滚动区域内容控件。	`widget`：内容控件。	`void`
`widget() const`	获取内容控件。	无	`QWidget*`
`setWidgetResizable(bool resizable)`	设置内容控件是否随视口变化。	`resizable`：是否自适应。	`void`
`setVScrollPos(int value)`	设置垂直滚动位置。	`value`：滚动值。	`void`
`setHScrollPos(int value)`	设置水平滚动位置。	`value`：滚动值。	`void`
`setScrollbarSize(bool isHorizontal, int size)`	设置滚动条厚度。	`isHorizontal`：是否水平滚动条；`size`：厚度。	`void`
`setScrollbarBtnSize(bool isHorizontal, int size)`	设置滚动条按钮大小。	`isHorizontal`：是否水平滚动条；`size`：按钮尺寸。	`void`
`setScrollbarBackgroundStyle(bool isHorizontal, const FillStyle& background)`	设置轨道背景。	`isHorizontal`：方向；`background`：轨道背景样式。	`void`
`setScrollbarThumbStyle(bool isHorizontal, CtrlState state, const FillStyle& style)`	设置滑块状态样式。	`isHorizontal`：方向；`state`：状态；`style`：滑块样式。	`void`
`setScrollbarButtonIcon(bool isHorizontal, bool isUpOrLeft, const QString& iconPath)`	设置方向按钮图标。	`isHorizontal`：方向；`isUpOrLeft`：上/左按钮；`iconPath`：图标路径。	`void`

UIGQSplitter

UIGQSplitter 用于把页面拆成可拖动调整的多个区域。

接口	说明	参数	返回值
`addWidget(QWidget* widget)`	添加分区控件。	`widget`：分区内容。	`void`
`insertWidget(int index, QWidget* widget)`	插入分区控件。	`index`：位置；`widget`：分区内容。	`void`
`setOrientation(Qt::Orientation orientation)`	设置横向或纵向拆分。	`orientation`：方向。	`void`
`setSizes(const QList<int>& list)`	设置各分区尺寸。	`list`：尺寸列表。	`void`
`sizes() const`	获取当前分区尺寸。	无	`QList<int>`

UIGQSpacer

UIGQSpacer 作为布局占位控件使用，常放在水平工具栏中把右侧按钮推到末尾。

接口	说明	参数	返回值
`setLayoutRatio(int ratio)`	设置占位权重。	`ratio`：权重值。	`void`
`setWidthPolicy(LayoutSizePolicy policy)`	设置宽度策略。	`policy`：固定、填充或自动策略。	`void`
`setHeightPolicy(LayoutSizePolicy policy)`	设置高度策略。	`policy`：固定、填充或自动策略。	`void`
`setMinimumSize(int w, int h)`	设置最小尺寸。	`w/h`：尺寸像素。	`void`

UIGQGroupBox

UIGQGroupBox 用于把相关控件组合到一个带标题的区域中。

接口	说明	参数	返回值
`setTitle(const QString& title)`	设置分组标题。	`title`：标题文本。	`void`
`title() const`	获取分组标题。	无	`QString`
`setCheckable(bool checkable)`	设置分组是否可勾选。	`checkable`：是否可勾选。	`void`
`setChecked(bool checked)`	设置勾选状态。	`checked`：是否选中。	`void`
`setThemeName(const QString& themeName)`	设置分组主题。	`themeName`：主题名。	`void`

使用建议

页面骨架优先使用 UIGQContainer，保持布局树清晰。
setThemeName(...) 只负责外观主题，布局尺寸仍建议由布局参数控制。
需要浮在右上、右下的区域使用 setAbsoluteDock(...)，内容尺寸不固定时再开启 setAbsoluteDockAutoSize(true)。
长内容不要靠父容器裁剪，使用 UIGQScrollView 承载，并分别配置水平、垂直滚动条。

Qt-UI WidgetKit 布局与容器控件