qt6-desktop-ux

Qt6 桌面 UX 模式

1. QDockWidget（可停靠面板）

适用场景

• 导航器面板
• 属性面板
• 日志面板
• 任意侧边面板

模式

QDockWidget* dock = new QDockWidget(tr("Panel Title"), parent);
dock->setObjectName("uniquePanelName");  // for state persistence
dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);
dock->setFeatures(QDockWidget::DockWidgetMovable |
                  QDockWidget::DockWidgetClosable |
                  QDockWidget::DockWidgetFloatable);

QWidget* content = new QWidget();
// ... setup content layout
dock->setWidget(content);

parent->addDockWidget(Qt::RightDockWidgetArea, dock);

2. QGroupBox（视觉分组）

适用场景

• 将相关控件分组
• 设置分区
• 表单分区

模式

QGroupBox* group = new QGroupBox(tr("Section Title"));
QVBoxLayout* groupLayout = new QVBoxLayout(group);

// Add controls to groupLayout
groupLayout->addWidget(control1);
groupLayout->addWidget(control2);

// Add group to parent layout
mainLayout->addWidget(group);

3. 间距和边距

标准值

• 控件之间：6px
• 分组边距：11px
• 对话框边距：11px

模式

layout->setSpacing(6);
layout->setContentsMargins(11, 11, 11, 11);

4. QSizePolicy

策略

策略	行为
Fixed	固定大小，不拉伸
Preferred	首选大小，可缩小或放大
Expanding	填满可用空间
Minimum	不小于最小大小
Maximum	不超过最大大小

模式

widget->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Fixed);

5. 拉伸因子

在布局中

layout->addWidget(widget1, 0);  // fixed
layout->addWidget(widget2, 1);  // fills remaining space
layout->addStretch(1);          // spacer that expands

6. QDialog（模态窗口）

模式

class MyDialog : public QDialog {
    Q_OBJECT
public:
    explicit MyDialog(QWidget* parent = nullptr);

private:
    void setupUI();
    void createConnections();

    // Controls as members
    QLineEdit* m_nameEdit;
    QDialogButtonBox* m_buttonBox;
};

MyDialog::MyDialog(QWidget* parent)
    : QDialog(parent)
{
    setWindowTitle(tr("Dialog Title"));
    setupUI();
    createConnections();
}

void MyDialog::setupUI() {
    QVBoxLayout* mainLayout = new QVBoxLayout(this);

    // Content
    m_nameEdit = new QLineEdit();
    mainLayout->addWidget(m_nameEdit);

    // Standard buttons
    m_buttonBox = new QDialogButtonBox(
        QDialogButtonBox::Ok | QDialogButtonBox::Cancel);
    mainLayout->addWidget(m_buttonBox);
}

void MyDialog::createConnections() {
    connect(m_buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
    connect(m_buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);
}

7. 无障碍访问

所有控件都必须满足

widget->setToolTip(tr("Descriptive tooltip"));
widget->setWhatsThis(tr("Detailed help text"));
widget->setAccessibleName(tr("Name for screen readers"));

Tab 顺序

setTabOrder(widget1, widget2);
setTabOrder(widget2, widget3);

8. 响应式设计

最小尺寸

widget->setMinimumWidth(200);
widget->setMinimumHeight(100);

最大尺寸（需要时）

widget->setMaximumWidth(400);

9. QToolBar

模式

QToolBar* toolbar = new QToolBar(tr("Main Toolbar"), parent);
toolbar->setObjectName("mainToolbar");
toolbar->setMovable(true);
toolbar->setIconSize(QSize(24, 24));

// Add actions (use ArtProvider!)
QAction* action = core::ArtProvider::getInstance().createAction("file.new", tr("New"), toolbar);
toolbar->addAction(action);
toolbar->addSeparator();

10. 主题集成

连接主题更改

connect(&core::ThemeManager::getInstance(), &core::ThemeManager::themeChanged,
        this, &MyWidget::onThemeChanged);

void MyWidget::onThemeChanged() {
    // Update colors, refresh UI
    update();
}

添加新的主题颜色

当组件需要新的自定义颜色时，请使用自动化脚本：

python scripts/add_theme_color.py colorName "#darkHex" "#lightHex" -d "description" -s

完整文档请参阅 kalahari-coding 技能。

11. Qt6 文档（Context7 MCP）

不确定 Qt6 API、信号、槽或属性时，务必先查阅 Context7：

步骤 1：解析 Qt6 库 ID（每个会话一次）

mcp__context7__resolve-library-id("Qt6")

返回：/qt/qtdoc 或类似内容

步骤 2：获取特定主题的文档

mcp__context7__query-docs(
    context7CompatibleLibraryID="/qt/qtdoc",
    topic="QDockWidget"
)

常见的 Qt6 查询主题：

主题	适用场景
QDockWidget	创建可停靠面板
QDialog	模态对话框
QLayout	布局管理
QSizePolicy	控件尺寸行为
signals slots	信号/槽连接
QToolBar	创建工具栏
QAction	动作/命令模式
QStyle	样式和主题

适用 Context7 的场景：

• ✅ 不确定方法参数
• ✅ 需要了解可用的信号/槽
• ✅ 查找 Qt6 专属模式
• ✅ 检查弃用状态