CSideMenu 组件规格说明

1. 概述与范围

本规格描述 CSideMenu 组件的技术契约：数据树、三级菜单、全局手风琴、响应式侧栏、antd Layout.Sider / Menu 的组合。

• 依赖：React、antd v6、@ant-design/icons
• 范围：侧栏容器、菜单渲染、遮罩
• 非目标：路由与子页实现、自定义滚动条

2. 数据模型

MenuTree（宿主传入）

interface MenuItem {
  key: string | number;      // 唯一标识
  label: string;              // 显示文本
  children?: MenuItem[];      // 子菜单
  path?: string;              // 页面路径
  pageName?: string;         // 页面名称
  type?: 'chart' | 'setting' | 'folder' | 'file';  // 图标类型
}

interface MenuTree extends MenuItem {}

组件 Props

interface CSideMenuProps {
  title: string;                           // 顶区标题
  tree?: MenuTree;                         // 合并后的菜单树
  collapsed: boolean;                      // 是否收起
  curActivePaneKey?: string | number;     // 当前选中键
  panesOnShelf?: Array<{ key: string }>; // 已打开页签列表
  onClickMenuItem: (item: MenuItem) => void;
  onSetMenuCollapse: (collapsed: boolean | void) => void;
}

3. 组件行为

Requirement: 三级菜单树渲染

组件 SHALL 从注入的 tree 数据结构渲染三级菜单树。结构为 key > label > children > key > label > children。每个节点 SHALL 包含 id、name、可选 type 字段。当节点包含非空 children 时，SHALL 渲染为 SubMenu；否则为叶子项。

Requirement: 全局手风琴展开

当用户展开一个节点时，组件 SHALL 关闭之前展开的节点。全局最多同时只有一个展开分支。

Requirement: 响应式固定模式

当视口宽度低于 lg 断点时（移动端），侧边栏 SHALL 进入固定模式，以 position: fixed 悬浮覆盖在内容之上。当菜单展开时 SHALL 显示背景遮罩，点击遮罩 SHALL 触发收起。PC 端不启用覆盖模式。

Requirement: 固定模式延迟导航

在固定模式下，当用户点击叶子项时，组件 SHALL 先触发收起（onSetMenuCollapse(true)），然后在约 300ms 延迟后调用 onClickMenuItem，以避免动画闪烁。

Requirement: 菜单项点击回调

当用户点击叶子菜单项时，组件 SHALL 调用 onClickMenuItem，传入完整的菜单项对象，至少包含 id、name、path、pageName 字段。

Requirement: 折叠状态回调

组件 SHALL 支持 onSetMenuCollapse 的两种调用模式：boolean 参数（设置精确折叠状态）和无参调用（切换）。宿主应用 SHALL 处理这两种模式。

Requirement: 空树处理

当注入的 tree 为空或 undefined 时，组件 SHALL 渲染标题区域和空菜单区域，且不抛出错误。

Requirement: 当前选中键高亮

当 curActivePaneKey 与菜单节点的 id 或 key 匹配时，该节点 SHALL 显示选中样式。当叶子项被选中时，其所属 SubMenu SHALL 显示子树选中样式。

Requirement: 已打开标签指示器

当 panesOnShelf 中的某个条目的 key 与叶子节点的 id 匹配时，该叶子 SHALL 显示"已打开"指示器样式。

4. 图标映射

5. 响应式断点

• PC 端：breakpoint="lg" (992px) 以上，使用 antd Layout.Sider
• 移动端：992px 及以下，使用固定定位覆盖层 + 遮罩