From 73f6da477cbb11542401c6019149c94269482259 Mon Sep 17 00:00:00 2001 From: Tevin <tingquanren@163.com> Date: Mon, 13 Apr 2026 11:44:17 +0800 Subject: [PATCH] docs: 添加 CSideMenu V2 实现计划 --- openspec/docs/old-refactors/side-menu/task.md | 79 ++++++++++++++++++++------------------- 1 files changed, 40 insertions(+), 39 deletions(-) diff --git a/openspec/docs/old-refactors/side-menu/task.md b/openspec/docs/old-refactors/side-menu/task.md index 002ed7d..c9e5e96 100644 --- a/openspec/docs/old-refactors/side-menu/task.md +++ b/openspec/docs/old-refactors/side-menu/task.md @@ -1,55 +1,56 @@ -# 侧栏菜单（Side Menu）— 验收标准 +> **本文档集顺序**：① [prod.md](./prod.md) → ② [spec.md](./spec.md) → ③ **本页 task**。依据与条目应对齐 prod 与 spec。 -验收项应对照 [spec.md](./spec.md)；技术实现基于 **React + antd@6**，下列不重复验证 antd 默认组件能力（如 Menu 基础受控、`Sider` 常规折叠属性等），仅验证**本文档约定与叠加逻辑**。 +# 侧栏导航 — 验收标准 -**样本数据**：可使用与 SPEC §2.3、§2.4 一致的静态骨架 + 合并规则构造最小样例树；文档不绑定某仓库内具体文件路径。 +在 **antd@6** 目标栈下可执行（手工或 E2E）。参数与语义以 [spec.md](./spec.md) §5 为准；不要求与现网 class 名一致。 ---- +## 数据与结构 -## 数据与展示 +- [ ] 顶层 `tree` 非法组合不渲染错误结构；有 `items` 时一级分组标题与 `name` 一致。 +- [ ] 叶子标识与菜单 `key`/`selectedKeys` 一致；`curActivePaneKey` 命中叶子时该叶为 **selected**。 +- [ ] 分组下任意深度有选中时，该一级分组具 **子树选中** 可辨样式。 -- [ ] 空树不报错，侧栏可显示标题与空菜单区域。 -- [ ] 使用 SPEC 约定字段（`id`、`name`、`pageName`、`path`、可选 `type`）时，分组名与叶子文案展示正确。 -- [ ] `type` 为 `chart` / `setting` 等与 spec 约定映射一致；缺省或 `normal` 时走默认图标分支。 -- [ ] `id` 与 `key` 混用时，选中与展开比较均正确（字符串语义一致）；**数值型** `curActivePaneKey`（含负数 id 场景）与 Menu `selectedKeys` 类型转换正确。 -- [ ] 当前选中在深层叶子时，对应一级分组呈现「子树选中」样式（见 spec §4.1）。 -- [ ] 已打开页签对应的叶子显示「已打开」样式（`pane.key ===` 菜单项 `id`，见 spec §2.2）。 +## 响应式与壳层（根容器组合） -## 展开行为（超出 antd 默认的同级互斥） +- [ ] 跨越 `Sider` **breakpoint**（如 lg）时宿主收到 `onSetMenuCollapse(broken)`，且界面「**窄屏固定覆盖**」与 broken 一致。 +- [ ] **窄屏**且 `collapsed === false` 时呈现 **全宽抽屉** 语义；窄屏且 `collapsed === true` 时不呈现全宽展开。 +- [ ] 窄屏且展开时遮罩为 **可见半透明**（约 0.2 透明度量级，可肉眼对照 spec §5）；点遮罩收起。 +- [ ] 由窄回宽后无永久遮罩挡主内容操作。 -- [ ] 三级结构下，在 antd `Menu` 层展开二级某分支时，其**同级**其它已展开分支被关闭（spec §4.2 手风琴）。 -- [ ] 三级自定义子菜单层：展开某一 key 时**兄弟** key 从 `openKeys` 移除；关闭时仅移除当前 key（spec §4.2）。 -- [ ] 展开/关闭动画结束后，滚动区域「是否需要滚动」的判定会更新（允许短延迟）。 +## 展开与手风琴 -## 滚动与遮罩（逻辑） +- [ ] 同父级下连续展开两个一级 `SubMenu`，最终仅保留新展开项（同级其他被收起）。 +- [ ] **自研子菜单**路径：展开一节点时同级另一节点从 `openKeys` 中移除。 +- [ ] 展开/收起后，在约 0.35s～0.5s 内完成高度与滚动检测；内容足够高时无「永久无法滚动」或「滑块高度为 0」。 -- [ ] 内容超出阈值（约 10px）时出现自定义滚动条；滑块与 `scrollTop` 双向同步；触摸拖拽可用（spec §4.4）。 -- [ ] `resize` 后滚动条占位与是否需要滚动判断正确。 -- [ ] 固定模式且侧栏展开时显示遮罩；点遮罩触发收起；**滚动拖拽过程中**不因误点遮罩关闭（spec §4.5）。 +## 点击与宿主回调 -## 自定义样式与动效（须对照 spec §5） +- [ ] **非窄屏固定覆盖**：点叶子立即 `onClickMenuItem(item)`。 +- [ ] **窄屏固定覆盖**：先触发收起，约 300ms 后 `onClickMenuItem(item)`。 +- [ ] **点遮罩**（非拖拽滚动条、且为可见半透明遮罩）：触发收拢。 -- [ ] **无需滚动**时自绘轨道不可见且 `pointer-events` 不阻挡菜单操作；**需要滚动**时轨道在约定 **delay + duration** 后出现（spec §5.3）。 -- [ ] 出现滚动条时菜单区有约定 **padding-right**，一级 `SubMenu` 与自定义子菜单的箭头位置与 spec §5.3 一致（不与轨道重叠）。 -- [ ] 滑块默认细、hover **加宽与变色**有过渡（约 0.3s）；**滚动拖拽**态下滑块保持展开态且 **background 等关闭 transition（0s）**（spec §5.3）。 -- [ ] **滚动拖拽**时遮罩呈全透明、容器 **z-index** 与 §5.3 一致，与固定模式下半透明遮罩可区分。 -- [ ] 顶区标题条高度、主色底、ellipsis 符合 spec §5.1。 -- [ ] 固定模式全宽 class 与遮罩 rgba 层级符合 spec §5.2。 +## 自绘滚动条 — 出现与同步（spec §5） -## 宿主契约与窄屏 +- [ ] 仅当视口 ≥ 约 992px 且内容超高（含容差）时出现轨与滑块；否则轨不可见且不形成右侧可点死区。 +- [ ] 拖拽时 `scrollTop` 与滑块位移比例一致；松手后滚动与滑块仍同步。 +- [ ] **拖拽中**：遮罩 **近透明**；点遮罩/遮罩区域不收拢侧栏（与 spec §5 一致）。 +- [ ] **非拖拽**且窄屏展开：**半透明遮罩**可点收拢。 -- [ ] 低于约定断点时进入固定模式；断点变化时宿主收到折叠同步（spec §3.2）。 -- [ ] `onSetMenuCollapse`：传入 **boolean** 时宿主折叠态与之一致；**无参**调用时符合 spec §6.2 约定的切换语义。 -- [ ] 固定模式下点击叶子：先触发收起，再于约定延迟后调用「打开页」回调，顺序符合 spec §4.3。 -- [ ] 点击叶子时，回调参数为**完整菜单项对象**，至少包含宿主开页所需字段（如 `id`、`name`、`path`、`pageName`），与宿主标签/开页逻辑的消费方式一致（spec §2.5）。 +## 自绘滚动条 — 交互反馈阶梯（spec §5 表格） ---- +- [ ] 外围 → 邻近：先进入可滚菜单区，滑块条较默认态明显提亮（中间色），宽度可仍为窄条。 +- [ ] 邻近 → 主操作面：指针落在滑块热区，滑块加宽（如约 6px→12px）且更亮，过渡约 0.3s 量级。 +- [ ] 拖拽（激活）：滑块保持加宽高亮；`background-color` 等 `transition` 为 0，无跟手迟滞。 -## 修订记录 +## 自研子菜单 -| 日期 | 摘要 | -|------|------| -| 2026-04-07 | 自 spec §6 迁入；标注 antd@6 与基线不验范围 | -| 2026-04-07 | 对齐静态配置字段与壳回调验收 | -| 2026-04-07 | 去除具体文件路径 | -| 2026-04-07 | 宿主契约节号改为 §6.2；新增 §5 动效验收 | +- [ ] 展开时箭头旋转与 max-height 过渡可感知；收起与展开时长可不同，无闪断。 +- [ ] 选中在本节点与仅有子级选中时标题样式可区分。 + +## 已打开窗格 + +- [ ] `panesOnShelf` 中存在 `pane.key` 与叶子 `id` 一致的项时，该叶具 **已打开** 可辨样式，**Caret** 规则符合 spec §5。 + +## 回归（v6） + +- [ ] 窄视口/触摸下分组内多级仍可展开并点选叶子。 -- Gitblit v1.9.1