docs/v1.0/client/changelogs/2026-01-21-breadcrumb-navigation.md

面包屑导航功能实现

日期: 2026-01-21
类型: Feature
影响范围: ProjectsPage, ProjectHeader

变更概述

实现了项目页面的文件夹面包屑导航功能，用户可以通过面包屑快速导航到父级文件夹。

技术实现

1. API 集成

• 使用 useFolderPath Hook 获取文件夹路径数据
• API 端点：GET /folders/{folder_id}/path
• 返回格式：{ path: [{ id, name }, ...] }

2. 面包屑构建逻辑

const breadcrumbs = useMemo(() => {
  const crumbs: Array<{ id: string; name: string }> = [];

  // 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) && folderPath) {
    folderPath.forEach((folder) => {
      crumbs.push({
        id: folder.id,
        name: folder.name,
      });
    });
  }

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

3. UI 展示

• 首页图标显示在第一个面包屑项
• 使用 ChevronRight 图标作为分隔符
• 当前文件夹高亮显示（粗体）
• 点击面包屑项可导航到对应文件夹

文件变更

修改的文件

1. client/src/pages/ProjectsPage.tsx

   • 导入 useFolderPath Hook
   • 实现面包屑数据构建逻辑
   • 清理未使用的变量和导入

2. client/src/stores/uiStore.ts

   • 扩展 createProjectInitialValues 类型，添加 folderId 字段
   • 支持在创建项目时预设所属文件夹

用户体验改进

• ✅ 清晰的层级导航路径
• ✅ 快速返回上级文件夹
• ✅ 视觉上突出当前位置
• ✅ 支持虚拟根节点（我的项目/协作项目）

后续优化

• 添加面包屑项的 hover 效果
• 支持面包屑项的右键菜单
• 长路径时的省略显示
• 面包屑项的拖拽移动功能

相关文档

• RFC 122: 文件夹 API 集成
• RFC 124: 文件夹分类前端实现