Skip to content

fix(knowledge-graph): 修复 5 种图谱引擎切换与右栏缩放的布局溢出 - #528

Merged
ThreeFish-AI merged 1 commit into
feature/1.x.xfrom
ThreeFish-AI/fix-graph-canvas-layout
May 12, 2026
Merged

fix(knowledge-graph): 修复 5 种图谱引擎切换与右栏缩放的布局溢出#528
ThreeFish-AI merged 1 commit into
feature/1.x.xfrom
ThreeFish-AI/fix-graph-canvas-layout

Conversation

@ThreeFish-AI

Copy link
Copy Markdown
Owner

背景

  • 本次变更要解决的问题:Knowledge Graph 页面(/knowledge/graph)切换 5 种渲染引擎(Cytoscape / d3-force / 3D WebGL / Sigma / Force Graph)并收起/展开右侧抽屉时,3D 引擎的画布会撑爆 Flex 容器,把右栏推到浏览器视口之外;同时给其他引擎留下了潜在的初始尺寸闪烁隐患。
  • 关联上下文/Issue/文档:apps/negentropy-ui/app/knowledge/graph/page.tsx 五引擎布局;GraphCanvasFrame.tsx 共享外框单一事实源。

核心变更

  • GraphCanvas3D.tsx(关键修复):复用 ForceGraphCanvas 已验证的 containerRef + ResizeObserver 模式,新增 dimensions state 并向 ForceGraph3D 显式传入 width/height;容器改为绝对定位(position:absolute; inset:0)打破「Canvas 反向撑大父容器」的循环;dimensions=0 时不渲染避免初始化闪烁。
  • GraphCanvasFrame.tsx(安全网):base class 追加 overflow-hidden,所有 5 个引擎共享溢出兜底;同步精简 className prop 的 JSDoc。
  • ForceGraphCanvas.tsx(一致性 + 防闪烁)dimensions 初值从硬编码 700×500 改为 0×0 并添加渲染守卫,与 3D 引擎保持同一范式。

风险与回滚

  • 主要风险:ForceGraph3Dwidth=0height=0 时被跳过渲染,依赖 ResizeObserver 在 mount 后同步回填真实尺寸;如果未来更换为不支持 ResizeObserver 的容器需重新校准。
  • 回滚方式:git revert <commit> 即可恢复原状;变更面仅 3 个组件文件,无 schema/数据迁移。

验证证据

  • 单元测试:无(纯布局/DOM 测量变更)。
  • 集成测试:无新增。
  • E2E/Workflow:在 Conductor workspace 启动 pnpm dev (port 3193),使用 Chrome DevTools 量化测量 5 引擎 × sidebar 展开/收起 的完整矩阵:
    • sidebar 展开:5 引擎 frame=1482px、canvas=1480px、aside.right=1838 < viewport=1862 ✓
    • sidebar 收起:5 引擎 frame=1770px、canvas=1768px、无溢出 ✓
    • 3D 引擎下 sidebar toggle 循环:1482 ↔ 1770 平滑切换,ResizeObserver 工作正常 ✓
  • 覆盖率/关键截图:测量数据见 commit message。

影响范围

  • 前端:apps/negentropy-ui/app/knowledge/graph/_components/{GraphCanvas3D,GraphCanvasFrame,ForceGraphCanvas}.tsx
  • 后端:无。
  • GitHub Actions / 文档:无。

Next Best Action

  • 在 PR 合并到 feature/1.x.x 后,回归验证生产构建(pnpm build && pnpm start)下 3D 引擎在 standalone server 模式的 ResizeObserver 表现,确保无 SSR/CSR 差异。

根因:GraphCanvas3D 未向 ForceGraph3D 传递 width/height,react-force-graph-3d
默认使用 window.innerWidth/Height,导致 Canvas 撑爆 Flex 容器并将右栏推出视口。

修复:
1. GraphCanvas3D:复用 ForceGraphCanvas 的 containerRef + ResizeObserver
   模式,通过绝对定位容器测量真实尺寸并以显式 width/height props 约束
   ForceGraph3D;dimensions=0 时不渲染避免初始化闪烁。
2. GraphCanvasFrame:base class 追加 overflow-hidden 作为所有引擎的溢出
   安全网,保留 className 扩展点供调用方追加样式。
3. ForceGraphCanvas:dimensions 初值从 700×500 改为 0×0 + 渲染守卫,
   消除初始尺寸与容器不匹配的潜在闪烁。

验证矩阵(视口 1862×900,sidebar 288px):
- 5 引擎 × sidebar 展开:frame=1482px, canvas=1480px, aside 在视口内 ✓
- 5 引擎 × sidebar 收起:frame=1770px, canvas=1768px, 无溢出 ✓
- 3D 引擎下 sidebar toggle:1482 ↔ 1770 平滑切换,ResizeObserver 工作正常 ✓

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
ThreeFish-AI merged commit 6b4fd30 into feature/1.x.x May 12, 2026
11 checks passed
@ThreeFish-AI
ThreeFish-AI deleted the ThreeFish-AI/fix-graph-canvas-layout branch May 12, 2026 07:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant