3.8 KiB

Raw Permalink Blame History

Changelog: 面包屑导航后端集成

日期: 2026-01-21
类型: Feature
影响范围: 前端 - 项目页面面包屑导航

功能说明

实现了文件夹面包屑导航功能，后端直接返回完整的面包屑路径，前端进行适配处理。

实现细节

后端返回格式

后端 /folders/{id} 接口返回的面包屑格式：

{
  "id": "018e1234-5678-7abc-8def-000000000003",
  "name": "西游记之大圣归来",
  "breadcrumbs": [
    { "id": "018e1234-5678-7abc-8def-000000000001", "name": "我的项目" },
    { "id": "018e1234-5678-7abc-8def-000000000003", "name": "西游记之大圣归来" }
  ]
}

前端处理逻辑

由于前端使用虚拟根节点（virtual-mine / virtual-collab）而后端返回真实根文件夹 ID，需要进行转换：

const breadcrumbs = useMemo(() => {
  const crumbs = [];

  // 1. 添加虚拟根节点
  const virtualRoot = activeRootId === VIRTUAL_ROOTS.mine.id 
    ? VIRTUAL_ROOTS.mine 
    : VIRTUAL_ROOTS.collab;
  crumbs.push({ id: virtualRoot.id, name: virtualRoot.name });

  // 2. 跳过后端返回的第一个面包屑（真实根文件夹）
  if (!isVirtualRoot(currentFolderId) && currentFolderData?.breadcrumbs) {
    const pathWithoutRoot = currentFolderData.breadcrumbs.slice(1);
    pathWithoutRoot.forEach((folder) => {
      crumbs.push({ id: folder.id, name: folder.name });
    });
  }

  return crumbs;
}, [activeRootId, currentFolderId, currentFolderData]);

数据流转

后端返回:
[真实根文件夹, 一级文件夹, 二级文件夹, ..., 当前文件夹]

前端处理:
1. 添加虚拟根节点
2. 跳过后端的第一个元素（真实根文件夹）
3. 添加剩余路径

最终显示:
[虚拟根节点, 一级文件夹, 二级文件夹, ..., 当前文件夹]

修改文件

✅ client/src/services/api/folders.ts - 移除 Mock 代码，使用真实 API
✅ client/src/pages/ProjectsPage.tsx - 实现面包屑构建逻辑，添加调试日志
✅ client/.env.development.local - 设置 VITE_USE_MOCK=false

调试功能

添加了详细的调试日志，在浏览器控制台中可以看到：

🍞 面包屑构建: {
  currentFolderId: "...",
  isVirtualRoot: false,
  currentFolderData: {...},
  breadcrumbsFromData: [...]
}

🍞 处理后的面包屑: {
  original: [...],
  afterSlice: [...]
}

🍞 最终面包屑: [...]

预期效果

根目录：我的项目
一级文件夹：我的项目 > 西游记之大圣归来
二级文件夹：我的项目 > 西游记之大圣归来 > 子文件夹

测试步骤

确保后端服务器正在运行
刷新前端页面
点击一级文件夹
检查面包屑是否正确显示
查看浏览器控制台的调试日志

故障排查

如果面包屑显示不正确，请检查：

后端是否返回 breadcrumbs 字段
- 打开浏览器开发者工具 → Network 标签
- 查找 /folders/{id} 请求
- 检查响应中是否包含 breadcrumbs 数组
前端是否正确获取数据
- 查看控制台中的 🍞 面包屑构建 日志
- 检查 currentFolderData 是否有值
- 检查 breadcrumbsFromData 是否是数组
数据转换是否正确
- 查看 🍞 处理后的面包屑 日志
- 检查 afterSlice 是否正确跳过了第一个元素

总结

成功实现了文件夹面包屑导航功能，后端直接返回完整路径，前端进行虚拟根节点转换。添加了详细的调试日志便于问题排查。

3.8 KiB Raw Permalink Blame History