FileAnnotation

为 VSCode 文件和文件夹添加备注，帮助你在大型项目中快速标识文件用途。

目录

• 功能特性
• 安装
• 快速开始
• 侧边栏备注树
• Smart 菜单导入
• 配置选项
• 数据存储
• 命令列表
• 项目结构
• 开发

功能特性

安装

方式一：VSIX 安装

1. 下载最新的 .vsix 文件
2. Ctrl+Shift+P → Extensions: Install from VSIX...
3. 选择 .vsix 文件，重新加载窗口

快速开始

添加备注

1. 在文件资源管理器中右键点击文件或文件夹
2. 选择「✏️添加备注」
3. 输入备注内容，回车确认

添加后，文件名旁会显示彩色 badge，鼠标悬停显示完整备注。

编辑 / 删除备注

• 右键 → 「✍️编辑备注」修改内容
• 右键 → 「🗑️ 删除备注」移除备注
• 编辑时清空输入框并回车也可删除

侧边栏备注树

点击活动栏中的备注图标打开「文件备注」侧边栏。

显示模式

点击标题栏 🔄 按钮切换：

搜索备注

点击标题栏 🔍 按钮：

• 实时搜索：输入关键词即时过滤（支持文件名和备注内容）
• 防抖优化：300ms 延迟，避免频繁刷新
• 自动展开：匹配节点及其所有父级目录自动展开
• 持久搜索框：失去焦点不关闭，方便随时微调
• ESC 关闭：按 ESC 关闭搜索框，结果保留在侧边栏
• 搜索状态下出现 ❌ 按钮，点击恢复原视图

侧边栏内联操作

• 有备注的节点：显示 ✏️ 编辑 和 🗑️ 删除 按钮
• 无备注的节点（全量模式）：显示 ➕ 添加 按钮
• 点击文件节点直接打开文件，点击文件夹节点定位到资源管理器

自动过滤

以下目录/文件不会出现在侧边栏中：

node_modules、.git、dist、out、.vscode 及所有以 . 开头的隐藏文件

🚁 Smart 菜单导入

适用于使用 Smart 框架的前端项目，可将后端返回的菜单 JSON 批量导入为文件备注。

使用步骤

1. 点击侧边栏标题栏的 🚁 按钮（或命令面板搜索 smart菜单导入）
2. 在弹出的输入框中粘贴菜单 JSON 数组
3. 确认后插件自动处理：
   • 递归提取所有含有效 component 路径的菜单项
   • 将 component 拼接为 src/views/<component> 的完整文件路径
   • 以菜单项的 name 作为备注内容
   • 新数据插入到存储文件最前面，已有备注不会被覆盖

输入格式示例

[
  {
    "name": "主控面板",
    "component": "BLANK_LAYOUT",
    "children": [
      {
        "name": "分析页",
        "component": "dashboard/analysis/index"
      },
      {
        "name": "工作台",
        "component": "dashboard/workbench/index"
      }
    ]
  }
]

💡 component 为 BLANK_LAYOUT、LAYOUT 等特殊标识符的项自动跳过，只处理包含 /xxx 的有效路径。

文件路径解析规则

插件会按以下顺序尝试匹配文件扩展名：.vue → .tsx → .ts → .jsx → .js。若均不存在，默认使用 .vue 后缀。

配置选项

Ctrl+, 搜索 FileAnnotation：

数据存储

备注数据保存在工作区根目录：

your-project/
├── .vscode/
│   └── file-annotation.json    ← 备注数据
└── src/
    └── ...

file-annotation.json 格式：

[
  {
    "filePath": "/absolute/path/to/src/views/dashboard/analysis/index.vue",
    "note": "分析页",
    "isDirectory": false
  },
  {
    "filePath": "/absolute/path/to/src/utils",
    "note": "工具函数目录",
    "isDirectory": true
  }
]

建议将 .vscode/file-annotation.json 纳入版本控制，方便团队共享备注信息。

命令列表

项目结构

src/
├── extension.ts              # 插件入口：activate / deactivate
├── types.ts                  # 共享类型定义
├── constants.ts              # 共享常量（配置键、忽略规则等）
├── fileUtils.ts              # 文件系统工具函数
├── FileNotesManager.ts       # 备注数据管理（CRUD + 持久化）
├── NoteTreeItem.ts           # 侧边栏树节点模型
├── FileNotesTreeProvider.ts  # 侧边栏树数据提供者
├── FileDecorationProvider.ts # 文件资源管理器装饰器
├── routeParser.ts            # 路由文件解析器
├── smartMenu.ts              # Smart 菜单数据示例
└── commands.ts               # 命令注册与处理

开发

# 安装依赖
npm install

# 编译
npm run compile

# 监听模式（自动重编译）
npm run watch

# 打包为 .vsix
npm run package

# 发布到市场
npm run publish

按 F5 启动 Extension Development Host 进行调试。