[0203] 增加侧边栏收缩功能 (#3390)

Author: GatsbyUSTC

devel/0203.md

@@ -0,0 +1,121 @@
+# [0203] Chat Tab 侧边栏收起/展开功能
+
+## 相关文档
+- [docs/demand.md](../docs/demand.md) - Chat Tab UI 需求文档与实现方案
+
+## 任务相关的代码文件
+- `src/Plugins/Qt/qt_chat_tab_widget.hpp`
+- `src/Plugins/Qt/qt_chat_tab_widget.cpp`
+
+## 如何测试
+
+### 确定性测试（单元测试）
+暂无单元测试。
+
+### 非确定性测试（文档验证）
+1. 启动 Mogan STEM，切换到 Chat Tab
+2. 观察左侧边栏默认处于展开状态，底部"收缩"按钮可见
+3. 点击底部"收缩"按钮，确认：
+   - 侧边栏立即缩为窄条（48px 宽）
+   - 窄条底部显示一个 "<" 展开按钮，原有内容（标题、会话列表等）不可见
+4. 点击窄条底部的 "<" 按钮，确认：
+   - 侧边栏立即恢复原有宽度
+   - 原有内容（标题、会话列表等）重新显示，窄条隐藏
+5. 在展开/收起状态下切换会话、发送消息，确认右侧内容区布局正常
+
+## 如何提交
+
+提交前执行以下最少步骤：
+
+```bash
+xmake b stem
+```
+
+确认编译通过后提交并推送：
+
+```bash
+git add -A
+git commit -m "[0203] Chat Tab 侧边栏收起/展开功能"
+git push origin hongwei/0202/chat-tab
+```
+
+## What
+
+为 Chat Tab 的左侧边栏实现收起/展开功能。收起时 sidebar 缩为一小条窄栏（底部仅含展开按钮），展开时恢复完整内容，切换无动画（避免卡顿）。
+
+修改内容：
+1. `qt_chat_tab_widget.hpp`：
+   - 新增 `collapseButton_` 成员，引用展开态底部的收缩按钮
+   - 新增 `sidebarNormalContent_` 成员，展开时的内容容器
+   - 新增 `sidebarCollapsedBar_` 成员，收起时的窄条容器
+   - 新增 `sidebarCollapsed_` 标志，记录当前收起状态
+   - 新增 `sidebarExpandedWidth_` 成员，保存展开时的原始宽度
+   - 新增 `toggle_sidebar()` 私有方法
+
+2. `qt_chat_tab_widget.cpp`：
+   - 新增常量 `kSidebarCollapsedWidth = 48`，定义窄条宽度
+   - 构造函数中初始化新成员，并在创建侧边栏后记录 `sidebarExpandedWidth_`
+   - 重构 `setup_left_sidebar()`：将原有内容包进 `sidebarNormalContent_` 容器，收缩按钮移至底部；新增 `sidebarCollapsedBar_` 窄条容器（底部含 "<" 展开按钮），默认隐藏
+   - 新增 `toggle_sidebar()` 实现：直接切换两个容器的可见性并 `setFixedWidth`，无动画
+
+## Why
+
+需求文档中明确要求侧边栏支持收起/展开（P1 优先级），以提升 Chat Tab 在窄屏或小窗口下的可用性，让用户可以把更多可视区域留给聊天内容。
+
+关键设计决策：
+1. 收起后 sidebar 不完全消失，而是缩为一小条窄栏，窄栏底部保留展开按钮——用户始终知道侧边栏的位置，可以随时点回来
+2. 收缩/展开按钮放在 sidebar 底部而非顶部——符合"设置/系统操作放底部"的常见 UI 惯例
+3. 不使用过渡动画——动画在当前实现中会造成卡顿感，直接切换更干脆
+
+## How
+
+### 双容器结构
+
+sidebar 内部维护两个互斥的 QWidget 容器：
+
+```
+sidebarWidget_ (sidebarLayout)
+  ├── sidebarNormalContent_  ← 展开时显示
+  │     ├── "Chat" 标题
+  │     ├── "New chat" 按钮
+  │     ├── "Conversations (N)" 标签
+  │     ├── 会话列表
+  │     ├── stretch
+  │     └── "收缩" 按钮（底部）
+  └── sidebarCollapsedBar_   ← 收起时显示
+        ├── stretch
+        └── "<" 按钮（底部）
+```
+
+### 切换逻辑
+
+```cpp
+void
+QTChatTabWidget::toggle_sidebar () {
+  if (!sidebarWidget_) return;
+
+  if (sidebarCollapsed_) {
+    // 展开：显示正常内容，隐藏窄条，恢复宽度
+    if (sidebarNormalContent_) sidebarNormalContent_->show ();
+    if (sidebarCollapsedBar_) sidebarCollapsedBar_->hide ();
+    sidebarWidget_->setFixedWidth (sidebarExpandedWidth_);
+    sidebarCollapsed_= false;
+  }
+  else {
+    // 收起：隐藏正常内容，显示窄条，缩为窄条
+    if (sidebarNormalContent_) sidebarNormalContent_->hide ();
+    if (sidebarCollapsedBar_) sidebarCollapsedBar_->show ();
+    sidebarWidget_->setFixedWidth (DpiUtils::scaled (kSidebarCollapsedWidth));
+    sidebarCollapsed_= true;
+  }
+}
+```
+
+## 影响范围确认
+
+本次修改仅涉及 `QTChatTabWidget` 类的内部实现，不影响：
+- 会话创建、切换、发送消息等核心逻辑
+- Scheme 层 API
+- 其他 Qt 插件或窗口组件
+
+唯一的外部可见变化是侧边栏底部"收缩"按钮从无效状态变为可交互状态，点击后 sidebar 缩为窄条并在底部显示展开按钮。

src/Plugins/Qt/qt_chat_tab_widget.cpp

@@ -114,6 +114,8 @@ is_empty_document_body (tree body) {
 
 /// 左侧边栏最小宽度（像素）。
 constexpr int kSidebarMinWidth= 200;
+/// 左侧边栏收起后的窄条宽度（像素）。
+constexpr int kSidebarCollapsedWidth= 48;
 /// 边栏布局水平边距。
 constexpr int kSidebarMarginX= 12;
 /// 边栏布局垂直边距。
@@ -201,9 +203,12 @@ QTChatTabWidget::QTChatTabWidget (QWidget* parent)
     : QWidget (parent), sidebarWidget_ (nullptr), contentWidget_ (nullptr),
       conversationCountLabel_ (nullptr), conversationListWidget_ (nullptr),
       conversationListLayout_ (nullptr), newChatButton_ (nullptr),
-      conversationStack_ (nullptr), activeConversation_ (nullptr),
-      nextConversationTitleId_ (1), chatMenuToolBar_ (nullptr),
-      chatModeToolBar_ (nullptr), chatFocusToolBar_ (nullptr) {
+      collapseButton_ (nullptr), sidebarNormalContent_ (nullptr),
+      sidebarCollapsedBar_ (nullptr), conversationStack_ (nullptr),
+      activeConversation_ (nullptr), nextConversationTitleId_ (1),
+      sidebarCollapsed_ (false), sidebarExpandedWidth_ (0),
+      chatMenuToolBar_ (nullptr), chatModeToolBar_ (nullptr),
+      chatFocusToolBar_ (nullptr) {
   setFocusPolicy (Qt::StrongFocus);
 
   QHBoxLayout* mainLayout= new QHBoxLayout (this);
@@ -227,8 +232,9 @@ QTChatTabWidget::QTChatTabWidget (QWidget* parent)
   setup_left_sidebar (sidebarLayout);
   sidebar->adjustSize ();
   const int contentWidth= sidebar->sizeHint ().width ();
-  sidebar->setFixedWidth (
-      qMax (DpiUtils::scaled (kSidebarMinWidth), contentWidth));
+  sidebarExpandedWidth_=
+      qMax (DpiUtils::scaled (kSidebarMinWidth), contentWidth);
+  sidebar->setFixedWidth (sidebarExpandedWidth_);
   mainLayout->addWidget (sidebar);
 
   // 右侧内容区
@@ -251,34 +257,21 @@ QTChatTabWidget::~QTChatTabWidget () {
  */
 void
 QTChatTabWidget::setup_left_sidebar (QVBoxLayout* sidebarLayout) {
-  // 顶部行：标题 + 收缩按钮
-  QHBoxLayout* headerLayout= new QHBoxLayout ();
-  headerLayout->setSpacing (0);
-
-  QLabel* navTitle= new QLabel ("Chat", this);
+  // ---- 展开态：正常内容容器 ----
+  QWidget* normalContent= new QWidget (sidebarWidget_);
+  normalContent->setObjectName ("chat-tab-sidebar-normal");
+  QVBoxLayout* normalLayout= new QVBoxLayout (normalContent);
+  normalLayout->setContentsMargins (0, 0, 0, 0);
+  normalLayout->setSpacing (DpiUtils::scaled (kSidebarSpacing));
+
+  // 顶部标题
+  QLabel* navTitle= new QLabel ("Chat", normalContent);
   navTitle->setObjectName ("chat-tab-nav-title");
   DpiUtils::applyScaledFont (navTitle, kNavTitleFontPx);
-  headerLayout->addWidget (navTitle);
-
-  headerLayout->addStretch ();
-
-  QPushButton* collapseBtn= new QPushButton ("收缩", this);
-  collapseBtn->setObjectName ("chat-tab-collapse-btn");
-  collapseBtn->setFocusPolicy (Qt::NoFocus);
-  collapseBtn->setCursor (Qt::PointingHandCursor);
-  DpiUtils::applyScaledFont (collapseBtn, kCollapseFontPx);
-  collapseBtn->setStyleSheet (
-      QString ("QPushButton { border: 1px solid #cccccc; border-radius: %1px; "
-               "padding: %2px %3px; background-color: #ffffff; }")
-          .arg (DpiUtils::scaled (kCollapseBorderRadius))
-          .arg (DpiUtils::scaled (kCollapsePadY))
-          .arg (DpiUtils::scaled (kCollapsePadX)));
-  headerLayout->addWidget (collapseBtn);
-
-  sidebarLayout->addLayout (headerLayout);
+  normalLayout->addWidget (navTitle);
 
   // New chat 按钮
-  newChatButton_= new QPushButton ("New chat", this);
+  newChatButton_= new QPushButton ("New chat", normalContent);
   newChatButton_->setObjectName ("chat-tab-new-btn");
   newChatButton_->setFocusPolicy (Qt::NoFocus);
   newChatButton_->setCursor (Qt::PointingHandCursor);
@@ -288,22 +281,71 @@ QTChatTabWidget::setup_left_sidebar (QVBoxLayout* sidebarLayout) {
                                      .arg (DpiUtils::scaled (kNavButtonPadX)));
   connect (newChatButton_, &QPushButton::clicked, this,
            [this] () { create_new_conversation (); });
-  sidebarLayout->addWidget (newChatButton_);
+  normalLayout->addWidget (newChatButton_);
 
-  conversationCountLabel_= new QLabel ("Conversations (0)", this);
+  conversationCountLabel_= new QLabel ("Conversations (0)", normalContent);
   conversationCountLabel_->setObjectName ("chat-tab-conversation-count");
   DpiUtils::applyScaledFont (conversationCountLabel_, kNavTitleFontPx);
   conversationCountLabel_->setStyleSheet ("color: #666666;");
-  sidebarLayout->addWidget (conversationCountLabel_);
+  normalLayout->addWidget (conversationCountLabel_);
 
-  conversationListWidget_= new QWidget (this);
+  conversationListWidget_= new QWidget (normalContent);
   conversationListWidget_->setObjectName ("chat-tab-conversation-list");
   conversationListLayout_= new QVBoxLayout (conversationListWidget_);
   conversationListLayout_->setContentsMargins (0, 0, 0, 0);
   conversationListLayout_->setSpacing (DpiUtils::scaled (kSidebarSpacing));
-  sidebarLayout->addWidget (conversationListWidget_);
+  normalLayout->addWidget (conversationListWidget_);
+
+  normalLayout->addStretch ();
 
-  sidebarLayout->addStretch ();
+  // 底部收缩按钮
+  QPushButton* collapseBtn= new QPushButton ("收缩", normalContent);
+  collapseBtn->setObjectName ("chat-tab-collapse-btn");
+  collapseBtn->setFocusPolicy (Qt::NoFocus);
+  collapseBtn->setCursor (Qt::PointingHandCursor);
+  DpiUtils::applyScaledFont (collapseBtn, kCollapseFontPx);
+  collapseBtn->setStyleSheet (
+      QString ("QPushButton { border: 1px solid #cccccc; border-radius: %1px; "
+               "padding: %2px %3px; background-color: #ffffff; }")
+          .arg (DpiUtils::scaled (kCollapseBorderRadius))
+          .arg (DpiUtils::scaled (kCollapsePadY))
+          .arg (DpiUtils::scaled (kCollapsePadX)));
+  connect (collapseBtn, &QPushButton::clicked, this,
+           [this] () { toggle_sidebar (); });
+  collapseButton_= collapseBtn;
+  normalLayout->addWidget (collapseBtn);
+
+  sidebarNormalContent_= normalContent;
+  sidebarLayout->addWidget (normalContent);
+
+  // ---- 收起态：窄条容器，底部展开按钮 ----
+  QWidget* collapsedBar= new QWidget (sidebarWidget_);
+  collapsedBar->setObjectName ("chat-tab-sidebar-collapsed");
+  QVBoxLayout* collapsedLayout= new QVBoxLayout (collapsedBar);
+  collapsedLayout->setContentsMargins (0, 0, 0,
+                                       DpiUtils::scaled (kSidebarMarginY));
+  collapsedLayout->setSpacing (0);
+
+  collapsedLayout->addStretch ();
+
+  QPushButton* expandBtn= new QPushButton ("<", collapsedBar);
+  expandBtn->setObjectName ("chat-tab-collapsed-expand-btn");
+  expandBtn->setFocusPolicy (Qt::NoFocus);
+  expandBtn->setCursor (Qt::PointingHandCursor);
+  DpiUtils::applyScaledFont (expandBtn, kCollapseFontPx);
+  expandBtn->setStyleSheet (
+      QString ("QPushButton { border: none; border-radius: %1px; "
+               "padding: %2px 0px; background-color: transparent; } "
+               "QPushButton:hover { background-color: #e0e0e0; }")
+          .arg (DpiUtils::scaled (kCollapseBorderRadius))
+          .arg (DpiUtils::scaled (kCollapsePadY)));
+  connect (expandBtn, &QPushButton::clicked, this,
+           [this] () { toggle_sidebar (); });
+  collapsedLayout->addWidget (expandBtn);
+
+  collapsedBar->hide ();
+  sidebarCollapsedBar_= collapsedBar;
+  sidebarLayout->addWidget (collapsedBar);
 }
 
 /**
@@ -515,6 +557,31 @@ QTChatTabWidget::refresh_sidebar () {
   }
 }
 
+/**
+ * @brief 切换侧边栏的收起/展开状态。
+ *
+ * 收起时 sidebar 缩为窄条（仅含展开按钮），展开时恢复完整内容。
+ */
+void
+QTChatTabWidget::toggle_sidebar () {
+  if (!sidebarWidget_) return;
+
+  if (sidebarCollapsed_) {
+    // 展开：显示正常内容，隐藏窄条，恢复宽度
+    if (sidebarNormalContent_) sidebarNormalContent_->show ();
+    if (sidebarCollapsedBar_) sidebarCollapsedBar_->hide ();
+    sidebarWidget_->setFixedWidth (sidebarExpandedWidth_);
+    sidebarCollapsed_= false;
+  }
+  else {
+    // 收起：隐藏正常内容，显示窄条，缩为窄条
+    if (sidebarNormalContent_) sidebarNormalContent_->hide ();
+    if (sidebarCollapsedBar_) sidebarCollapsedBar_->show ();
+    sidebarWidget_->setFixedWidth (DpiUtils::scaled (kSidebarCollapsedWidth));
+    sidebarCollapsed_= true;
+  }
+}
+
 /**
  * @brief 将指定面板从欢迎态切换到会话态。
  *

src/Plugins/Qt/qt_chat_tab_widget.hpp

@@ -134,6 +134,11 @@ class QTChatTabWidget : public QWidget {
    */
   void focus_input_editor (ChatConversationPanel* panel);
 
+  /**
+   * @brief 切换侧边栏的收起/展开状态。
+   */
+  void toggle_sidebar ();
+
 public:
   /**
    * @brief 为 Chat Tab 安装主菜单栏内容。
@@ -154,16 +159,21 @@ class QTChatTabWidget : public QWidget {
   void set_chat_focus_icons (widget focusWidget);
 
 private:
-  QWidget*        sidebarWidget_;                    ///< 左侧边栏容器。
-  QWidget*        contentWidget_;                    ///< 右侧内容区容器。
-  QLabel*         conversationCountLabel_;           ///< 显示会话数量的标签。
-  QWidget*        conversationListWidget_;           ///< 承载会话列表的控件。
-  QVBoxLayout*    conversationListLayout_;           ///< 会话按钮的布局。
-  QPushButton*    newChatButton_;                    ///< 新建会话按钮。
-  QStackedWidget* conversationStack_;                ///< 会话页面的堆叠控件。
-  QList<ChatConversationPanel*> conversations_;      ///< 所有会话面板的列表。
+  QWidget*        sidebarWidget_;               ///< 左侧边栏容器。
+  QWidget*        contentWidget_;               ///< 右侧内容区容器。
+  QLabel*         conversationCountLabel_;      ///< 显示会话数量的标签。
+  QWidget*        conversationListWidget_;      ///< 承载会话列表的控件。
+  QVBoxLayout*    conversationListLayout_;      ///< 会话按钮的布局。
+  QPushButton*    collapseButton_;              ///< 侧边栏内的收缩按钮。
+  QPushButton*    newChatButton_;               ///< 新建会话按钮。
+  QWidget*        sidebarNormalContent_;        ///< 侧边栏展开时的内容容器。
+  QWidget*        sidebarCollapsedBar_;         ///< 侧边栏收起时的窄条容器。
+  QStackedWidget* conversationStack_;           ///< 会话页面的堆叠控件。
+  QList<ChatConversationPanel*> conversations_; ///< 所有会话面板的列表。
   ChatConversationPanel*        activeConversation_; ///< 当前激活的会话。
   int       nextConversationTitleId_; ///< 自动生成会话标题的 ID 计数器。
+  bool      sidebarCollapsed_;        ///< 侧边栏当前是否处于收起状态。
+  int       sidebarExpandedWidth_;    ///< 侧边栏展开时的宽度（像素）。
   QToolBar* chatMenuToolBar_;         ///< Chat Tab 的菜单工具栏。
   QToolBar* chatModeToolBar_;         ///< Chat Tab 的模式工具栏。
   QToolBar* chatFocusToolBar_;        ///< Chat Tab 的焦点工具栏。