输入控件

输入控件负责用户操作、表单录入和参数选择。WidgetKit 的输入控件继承 Qt 原生控件能力，同时增加主题、状态绘制、SVG 图标、布局策略和通用序列化支持。

控件类型

控件	子内容与能力	典型用途
`UIGQPushButton`	文本、普通/悬停/按下图标、背景状态、fade 高亮、SVG 颜色	操作按钮、图标按钮、工具按钮
`UIGQCheckBox`	选中/未选中图标、半选状态、文字、状态样式	多选项、批量选择、布尔配置
`UIGQRadioButton`	单选图标、互斥分组、文字、状态样式	模式切换、分组选择
`UIGQSwitch`	左右文本、滑块、动画、开关状态	启停选项、轻量布尔配置
`UIGQLineEdit`	文本、placeholder、密码模式、快捷键模式、内容边距	搜索、密码、快捷键录入
`UIGQTextEdit`	多行文本、滚动、富文本或纯文本编辑	备注、说明、脚本、日志编辑
`UIGQComboBox`	下拉项、当前项、项高度、弹出列表样式	枚举值、筛选条件、参数选择
`UIGQSpinBox`	数值范围、步长、当前值、前后缀	整数输入、步进调整
`UIGQSlider`	方向、范围、当前值、滑块尺寸、轨道样式	连续数值、比例、阈值调整

类继承关系

QWidget
  ├─ QPushButton
  │   └─ UIGQPushButton + IUIGQWidgetBase
  │       └─ UIGQRibbonPushButton
  ├─ QCheckBox
  │   └─ UIGQCheckBox + IUIGQWidgetBase
  ├─ QRadioButton
  │   └─ UIGQRadioButton + IUIGQWidgetBase
  ├─ UIGQSwitch + IUIGQWidgetBase
  ├─ QLineEdit
  │   └─ UIGQLineEdit + IUIGQWidgetBase
  ├─ QTextEdit
  │   └─ UIGQTextEdit + IUIGQWidgetBase
  ├─ QComboBox
  │   └─ UIGQComboBox + IUIGQWidgetBase
  ├─ QSpinBox
  │   └─ UIGQSpinBox + IUIGQWidgetBase
  └─ QSlider
      └─ UIGQSlider + IUIGQWidgetBase

输入控件继承 Qt 原生交互能力，例如文本输入、选择状态、数值范围和信号槽；IUIGQWidgetBase 负责接入 WidgetKit 的主题、布局比例、透明度等统一能力。

UIGQPushButton

UIGQPushButton 支持 Normal、Hot、Pressed、Disable 状态背景和文字样式，支持 PNG/SVG 图标和 fade 高亮效果。

UIGQPushButton* importButton = new UIGQPushButton(parent);
importButton->setObjectName("importButton");
importButton->setText("Import");
importButton->setThemeName("PrimaryButton");
importButton->setIcon(":/images/import.svg");
importButton->setFadeEnabled(true);

透明图标按钮建议使用不绘制背景的接口：

helpButton->setDrawBackground(false);
helpButton->setIcon(":/images/help.svg");

常用接口：

接口	说明	参数	返回值
`setText(const QString& text)`	设置按钮文本。	`text`：显示文本。	`void`
`setThemeName(const QString& themeName)`	绑定主题。	`themeName`：主题名。	`void`
`setIcon(const QString& iconPath)`	设置普通图标。	`iconPath`：资源或文件路径。	`void`
`setHotIcon(const QString& iconPath)`	设置悬停图标。	`iconPath`：悬停状态图标。	`void`
`setPressedIcon(const QString& iconPath)`	设置按下图标。	`iconPath`：按下状态图标。	`void`
`setUseIcon(bool use)`	控制是否绘制图标。	`use`：是否使用图标。	`void`
`setShowText(bool show)`	控制是否绘制文本。	`show`：是否显示文本。	`void`
`setDrawBackground(bool drawBackground)`	控制是否绘制按钮背景。	`drawBackground`：是否绘制背景。	`void`
`setBackground(CtrlState state, const FillStyle& fillStyle)`	设置状态背景。	`state`：状态；`fillStyle`：背景样式。	`void`
`setTextStyle(CtrlState state, const TextStyleDesc& desc)`	设置状态文字样式。	`state`：状态；`desc`：文字样式。	`void`
`setFadeEnabled(bool enabled)`	设置是否启用渐变高亮。	`enabled`：是否启用。	`void`
`setFadeDuration(int duration)`	设置渐变时间。	`duration`：毫秒。	`void`

UIGQCheckBox 和 UIGQRadioButton

UIGQCheckBox 和 UIGQRadioButton 都支持选中、未选中、禁用和悬停图标，也支持按状态设置文本样式。

UIGQCheckBox* check = new UIGQCheckBox(parent);
check->setText("Remember settings");
check->setThemeName("DefaultCheckBox");
check->setCheckedIcon(":/images/check-on.svg");
check->setUncheckIcon(":/images/check-off.svg");
check->setShowText(true);
check->setShowIcon(true);

常用接口：

接口	说明	参数	返回值
`setText(const QString& text)`	设置选项文本。	`text`：显示文本。	`void`
`setChecked(bool checked)`	设置选中状态。	`checked`：是否选中。	`void`
`isChecked() const`	获取选中状态。	无	`bool`
`setTristate(bool tristate)`	复选框启用三态。	`tristate`：是否启用。	`void`
`setCheckedIcon(const QString& iconPath)`	设置选中图标。	`iconPath`：图标路径。	`void`
`setUncheckIcon(const QString& iconPath)`	设置未选中图标。	`iconPath`：图标路径。	`void`
`setShowIcon(bool show)`	控制是否绘制图标。	`show`：是否显示。	`void`
`setShowText(bool show)`	控制是否绘制文字。	`show`：是否显示。	`void`
`setTextStyle(CtrlState state, const TextStyleDesc& desc)`	设置文字状态样式。	`state`：状态；`desc`：文字样式。	`void`
`toggled(bool checked)`	Qt 标准信号，状态切换时触发。	`checked`：当前状态。	`void`

UIGQSwitch

UIGQSwitch 更适合状态开关，支持滑块大小、边距、动画速度和左右文本。

UIGQSwitch* sw = new UIGQSwitch(parent);
sw->setLeftText("Off");
sw->setRightText("On");
sw->setSwitchToLeft(false);
sw->setSwitchSpeed(180);

常用接口：

接口	说明	参数	返回值
`setLeftText(const QString& text)`	设置左侧文本。	`text`：文本。	`void`
`setRightText(const QString& text)`	设置右侧文本。	`text`：文本。	`void`
`setSwitchToLeft(bool left)`	设置开关位置。	`left`：是否位于左侧。	`void`
`getSwitchToLeft() const`	获取当前开关位置。	无	`bool`
`setSwitchSpeed(int speed)`	设置切换动画速度。	`speed`：速度或时长参数。	`void`
`setSliderSize(int width, int height)`	设置滑块尺寸。	`width/height`：尺寸。	`void`
`setSliderMargin(int margin)`	设置滑块边距。	`margin`：边距。	`void`

UIGQLineEdit 和 UIGQTextEdit

UIGQLineEdit 支持 placeholder、密码模式、快捷键录入模式和内容边距。

UIGQLineEdit* search = new UIGQLineEdit(parent);
search->setThemeName(UIG_THEME_LINE_EDIT);
search->setPlaceholderText("搜索");
search->setEditMargin(8, 8, 12, 12);
search->setHotkeyMode(false);

UIGQTextEdit 用于多行文本，适合备注、日志和脚本文本。

常用接口：

接口	说明	参数	返回值
`setText(const QString& text)`	设置单行输入文本。	`text`：文本。	`void`
`text() const`	获取单行输入文本。	无	`QString`
`setPlainText(const QString& text)`	设置多行纯文本。	`text`：文本。	`void`
`toPlainText() const`	获取多行纯文本。	无	`QString`
`setPlaceholderText(const QString& text)`	设置提示文本。	`text`：提示文本。	`void`
`setIsPassword(bool password)`	设置密码模式。	`password`：是否密码模式。	`void`
`setHotkeyMode(bool hotkeyMode)`	设置快捷键录入模式。	`hotkeyMode`：是否启用。	`void`
`setEditMargin(int top, int bottom, int left, int right)`	设置内容边距。	四个方向边距。	`void`
`textChanged(const QString& text)`	单行文本变化信号。	`text`：变化后的文本。	`void`

UIGQComboBox

UIGQComboBox 适合枚举值和过滤条件。

UIGQComboBox* typeBox = new UIGQComboBox(parent);
typeBox->setThemeName("DefaultComboBox");
typeBox->addItem("Basic");
typeBox->addItem("Advanced");
typeBox->setItemHeight(32);

常用接口：

接口	说明	参数	返回值
`addItem(const QString& text)`	添加一个下拉项。	`text`：显示文本。	`void`
`addItems(const QStringList& texts)`	批量添加下拉项。	`texts`：文本列表。	`void`
`setCurrentIndex(int index)`	设置当前项。	`index`：项索引。	`void`
`currentIndex() const`	获取当前项索引。	无	`int`
`currentText() const`	获取当前项文本。	无	`QString`
`setItemHeight(int height)`	设置下拉项高度。	`height`：高度像素。	`void`
`currentIndexChanged(int index)`	当前项变化信号。	`index`：新索引。	`void`

UIGQSpinBox 和 UIGQSlider

UIGQSpinBox 适合精确整数，UIGQSlider 适合连续数值调整。

UIGQSlider* opacity = new UIGQSlider(parent, Qt::Horizontal);
opacity->setThemeName("DefaultSlider");
opacity->setRange(0, 100);
opacity->setValue(60);
opacity->setThumbSize(16, 16);

常用接口：

接口	说明	参数	返回值
`setRange(int min, int max)`	设置数值范围。	`min/max`：最小值和最大值。	`void`
`setMinimum(int min)`	设置最小值。	`min`：最小值。	`void`
`setMaximum(int max)`	设置最大值。	`max`：最大值。	`void`
`setValue(int value)`	设置当前值。	`value`：当前值。	`void`
`value() const`	获取当前值。	无	`int`
`setSingleStep(int step)`	设置步长。	`step`：步进值。	`void`
`setOrientation(Qt::Orientation orientation)`	设置滑块方向。	`orientation`：水平或垂直。	`void`
`setThumbSize(int width, int height)`	设置滑块尺寸。	`width/height`：滑块尺寸。	`void`
`valueChanged(int value)`	值变化信号。	`value`：新值。	`void`

使用建议

业务按钮优先通过 setThemeName(...) 绑定主题，避免在页面代码里硬编码颜色。
图标按钮需要透明背景时使用 setDrawBackground(false)。
表单输入建议统一设置 UIGQLineEdit 的边距，避免文字贴边。
开关类配置用 UIGQSwitch，多选集合用 UIGQCheckBox，互斥选项用 UIGQRadioButton。

Qt-UI WidgetKit 输入控件

输入控件

输入控件

控件类型

类继承关系

UIGQPushButton

UIGQCheckBox 和 UIGQRadioButton

UIGQSwitch

UIGQLineEdit 和 UIGQTextEdit

UIGQComboBox

UIGQSpinBox 和 UIGQSlider

使用建议