更新记录

0.1.0（2026-11-12） 下载此版本

• 文字备注：节点名后跟一段说明
• 覆盖显示名称：用自定义名字替换文件名，留空恢复
• 悬浮提示：自定义 tooltip
• 文字色 / 背景色：自绘调色盘拖拽取色（HSV 色块 + 色相条），另附常用色块与 HEX 输入；
• 图标：17 个内置图标（另有一个「不设置」选项），由独立的「选择图标」命令设置
• 删除线：标记废弃文件或目录
• 按扩展名批量设置：一条规则命中一批同类文件，范围可限定当前目录（含子目录）或整个项目
• 备注清单：列出全部规则，标出「路径已失效」与「重复、永不生效」，支持一键清理与单条删除
• 双击视图里的文件节点即打开文档；右键节点可编辑备注或回到项目管理器，
• 从视图定位到原生项目树：右键文件节点 →「在项目管理器中打开」，打开文件并让左侧项目管理器展开定位到它
• 主题自适应：跟随 HBuilderX 的 editor.colorScheme 与 editor.fontSize 切换明暗配色与字号

平台兼容性

# H-FileTreeTip · HBuilderX 目录树备注

给项目目录树加备注：文字说明、覆盖显示名、悬浮提示、文字色 / 背景色、图标、删除线，以及按扩展名批量设置。所有配置存放在项目根目录的 H-DirectoryV1.xml，不写进 HBuilderX 的全局设置，提交它就能同步给同事，删掉它就全部重置。

配置采用简单的 <trees>/<tree> XML 结构，规则随项目一起提交即可。

开发分支：develop。

一、必须说明的平台差异

理想情况下，备注、颜色、图标应直接显示在原生项目管理器的节点上。

但 HBuilderX 没有提供节点装饰扩展点：官方 API 里没有文件装饰器，TreeItem 也只有 label / tooltip / contextValue / command / collapsibleState，不支持文字色、背景色、图标。因此本插件采用如下载体：

换句话说：写配置在原生树，看效果在插件视图。这是 HBuilderX 现有扩展能力下能做到的最接近目标效果的方案，不是功能缺失。

二、功能

• 文字备注：节点名后跟一段说明
• 覆盖显示名称：用自定义名字替换文件名，留空恢复
• 悬浮提示：自定义 tooltip
• 文字色 / 背景色：自绘调色盘拖拽取色（HSV 色块 + 色相条），另附常用色块与 HEX 输入； 「编辑全部属性」里两个颜色输入框各带一个「打开调色盘」按钮（分别标注文字颜色 / 背景颜色）， 选好颜色自动填回对应输入框；配置里 r,g,b、#RRGGBB、rgb() / rgba() 与常见颜色名均可解析
• 图标：17 个内置图标（另有一个「不设置」选项），由独立的「选择图标」命令设置； 「设置颜色」命令只管颜色，不再重复询问图标
• 删除线：标记废弃文件或目录
• 按扩展名批量设置：一条规则命中一批同类文件，范围可限定当前目录（含子目录）或整个项目
• 备注清单：列出全部规则，标出「路径已失效」与「重复、永不生效」，支持一键清理与单条删除
• 双击视图里的文件节点即打开文档；右键节点可编辑备注或回到项目管理器， 菜单里不再单独提供「打开该文件」
• 从视图定位到原生项目树：右键文件节点 →「在项目管理器中打开」，打开文件并让左侧 项目管理器展开定位到它（目录节点没有对应能力，需手动展开）
• 手改 H-DirectoryV1.xml 保存后即时生效（fs.watch 文件监听 + 文档保存事件双通道）
• 主题自适应：跟随 HBuilderX 的 editor.colorScheme 与 editor.fontSize 切换明暗配色与字号

三、安装与调试

1. 需要 HBuilderX 3.0.0 及以上，且安装 node-debug 插件（HBuilderX 3.2.11+ 调试体验最佳）。
2. 用 HBuilderX 打开本目录（插件目录名 H-FileTreeTip 即插件 ID），点工具栏「运行插件」或按 Ctrl+R，会启动一个加载了本插件的新窗体。
3. 修改代码后需要停止并重新「运行插件」，不支持热更新。
4. 离线安装：把整个插件目录拷到 HBuilderX 安装目录/plugins 下，重启 HBuilderX。

自检（不需要 HBuilderX，纯 Node）：

node tests/selftest.js

四、使用

1. 菜单「视图 → 显示扩展视图」打开 目录备注 视图；或在「工具」菜单点「目录备注：打开视图」。
2. 在左侧项目管理器里右键任意文件或目录 → 「目录备注」子菜单，选择要设置的项。
   • 也可以直接在「目录备注」视图里右键节点操作，路径信息更明确。
3. 配置会写到项目根目录的 H-DirectoryV1.xml，视图立即刷新。
4. 想从视图回到原生项目树：右键文件节点 →「在项目管理器中打开」； 直接双击节点则只在编辑器里打开文档，不会切换左侧视图。

HBuilderX 官方文档没有承诺 explorer/context 命令回调的参数结构。插件会宽松解析多种形态；若解析不出选中路径，会弹出一个可搜索的选择框让你明确指定目标，不会静默把备注写到当前打开的文件上。

五、H-DirectoryV1.xml 格式

<?xml version="1.0" encoding="UTF-8"?>
<trees>
    <tree path="/src/api" title="所有接口定义" icon="api" textColor="85,150,235"/>
    <tree path="/src/legacy/old.js" title="待下线" strikethrough="true"/>
    <tree path="/src/components" extension="vue" title="业务组件" icon="ui"/>
    <tree extension="md" title="项目文档"/>
</trees>

命中优先级：

1. 路径规则（无 extension）：path 全等，优先级最高；
2. 目录级扩展名规则（path + extension）：path 更长的赢；
3. 全项目扩展名规则（只有 extension）：兜底；
4. 同优先级时写在前面的那条生效，所以「备注清单」里能标出永不生效的重复规则。

扩展名规则不匹配目录节点。写回文件时只替换 <tree> 元素，注释、声明、缩进、换行风格与 BOM 全部保留，不会背着用户重排配置文件。

六、目录结构

extension.js              插件入口：注册命令、视图、事件与销毁钩子
package.json              清单：视图 / 命令 / 菜单 / 激活事件
lib/
  constants.js            常量、图标集、颜色预设
  xml.js                  H-DirectoryV1.xml 解析与无损写回（纯逻辑）
  matcher.js              路径归一化、颜色解析、规则匹配、样式合成（纯逻辑）
  project.js              项目根目录换算与目录树扫描（Node fs）
  store.js                配置文件读写、按项目缓存、外部变更监听
  targets.js              右键菜单参数解析与兜底目标选择
  form.js                 输入 / 选择 / 综合编辑表单（含内嵌调色盘按钮与旧版本降级）
  colorpicker.js          调色盘对话框：HSV 换算、双向通信、失败降级
  view.js                 WebView 视图的数据装配、消息处理与打开文件
  commands.js             命令注册与业务编排
webview/index.html        「目录备注」视图页面
webview/colorpicker.html HSV 调色盘页面
tests/selftest.js         离线自检（89 项，含 mock HBuilderX 的集成场景）

lib/ 下所有模块都不 require('hbuilderx')，hx 由 extension.js 统一注入， 所以纯逻辑层可以直接用 Node 跑测试；真正调用 IDE API 的是 targets / form / colorpicker / view / commands 五处，外加入口 extension.js。

七、已知限制

• 原生项目管理器不会被染色或换图标（HBuilderX 未开放该能力），视觉效果在插件视图里查看。
• 目录树扫描默认忽略 node_modules、.git、unpackage 等目录，深度上限 8 层、节点上限 6000；需要调整可改 lib/constants.js。
• 旧版本 HBuilderX 若无 showFormDialog（或明确报控件不兼容），综合编辑表单会先去掉 widgetGroup 按钮、用纯输入框表单重试一次，仍失败才降级为逐项输入框。 在综合表单里点「取消」或关闭窗口一律静默退出：不写配置、不弹第二个输入框。HBuilderX 部分版本 用 reject 表示取消，插件已单独识别，不会把它误判成 API 不可用。
• 「清除全部设置」会二次确认。消息框按钮按官方顺序 [确定清除, 取消] 传；若当前版本的返回值 无法识别（例如返回索引），会改用选择列表再确认一次——既不静默跳过，也不会误删。
• 调色盘依赖 HBuilderX 内置浏览器插件（createWebViewDialog）。若当前环境没有该插件、 内置浏览器不可用，或页面脚本始终没加载，会自动退回「常用色 + 自定义输入」列表，功能不中断； 「不设置」可清除已设的颜色。
• 「编辑全部属性」里的调色盘按钮依赖 widgetGroup / button 控件与 onChanged 回调。 若当前版本不认识这些控件，会去掉按钮、用纯输入框表单重试一次；若连 showFormDialog 也不可用，则退回逐项输入。个别版本若不支持 updateForm 界面回写，选中的颜色仍会在 保存时合并进配置，不会丢失。
• 「在项目管理器中打开」没有按路径选中节点的官方 API，只能先打开文件、再执行内置命令 （这些命令都作用于当前活动编辑器，不接受路径参数）。单项目窗体默认「与编辑器同步」， 打开文件后左侧会自动展开；多项目或关闭同步时，插件会尝试 editor.action.revealInProjectExplorer，再用官方的 workbench.view.explorer 置焦。 前一个命令未列入官方 Command 列表，个别版本可能把它实现成「同步开关」—— 若发现同步状态被意外切换，删掉 lib/commands.js 里 EXPLORER_COMMANDS 的第一行即可， 其余链路不受影响。目录节点无法成为活动编辑器，只能手动在项目管理器里展开。
• 通知策略：保存、清除、按扩展名批量设置、清理失效 / 重复规则等操作成功后一律不弹 右下角通知，视图刷新后效果本身可见。只在「操作未生效 / 目标异常 / 空结果」时提示 （例如目录不能作为文档打开、没有失效路径）；「清除全部设置」的二次确认保留。