文件夹快捷轨（QuickRail）

一个贴在 Eagle 主窗口顶部的实时文件夹快捷入口。适合文件夹层级很多、经常在几个目录之间来回切换的资源库。

当前版本：v1.0.0 ｜ 建议 Eagle：4.0 Build 18+ ｜ 已验证：4.0 Build 23 ｜ 许可证：MIT

功能

• 勾选任意层级文件夹，立即显示在顶部快捷轨。
• “全部”作为独立入口，可与普通文件夹一起置顶、排序或移除。
• 文件夹选择器采用可展开/收起的树形结构，并支持鼠标滚轮；展开状态会按资源库保存，重新打开管理界面或重启 Eagle 后继续恢复。
• 文件夹新增、改名、换色或删除后，每 2 秒自动同步。
• 按资源库记录文件夹使用次数，可切换最近 24 小时 / 7 天 / 30 天。统计同时包含快捷轨点击，以及插件运行期间在 Eagle 中检测到的原生文件夹切换。
• 每个 Eagle 资源库独立保存一套快捷入口。
• 拖动快捷入口可排序；Alt + 1~9 可打开前 9 个入口（快捷轨获得焦点时）。
• 快捷轨中出现同名文件夹时，会自动显示能够区分它们的最短父级路径；若直属父级也同名，则继续向上补充路径，悬停仍可查看完整路径。
• 右键任意快捷入口可单独设置快捷轨显示色，也可进入长度调整：拖动目标卡片右边缘即可改变长度，轨道末端的 ✓ / × 用于保存或取消，还可一键恢复默认长度。自定义长度按资源库保存。
• 快捷入口多到超出轨道时，可直接用鼠标滚轮横向浏览，也可继续使用两侧箭头。
• 右键菜单可恢复文件夹原色，或经二次确认后从快捷轨移除；这些操作不会修改颜色或删除 Eagle 中的真实文件夹。
• 管理界面的“快捷顺序”支持继续手动拖拽；“使用统计”会按当前时间范围展示排行，单击文件夹即可加入或移出快捷轨。新项目按点击先后追加，也可按排行全选或取消全选。
• 按住快捷条空白区域即可自由移动，拖动使用 Eagle 窗口 API，空白区域保持普通箭头光标。
• 可选“联动吸附”：开启时会锁定快捷轨相对 Eagle 主窗口的位置；拖动 Eagle 会带着快捷轨移动，拖动快捷轨也会带着 Eagle 移动。关闭后两个窗口恢复独立移动；启用状态会自动记住。开机后若联动助手暂时尚未就绪，会保留开启偏好并自动重连，只有用户点击关闭才会真正关闭。
• 可选“系统置顶”，默认只作为 Eagle 的子窗口显示在主程序上方。
• 成功打开“全部”或普通文件夹时不弹出遮挡快捷栏的提示；只有失败信息仍会显示。
• 首次使用的紧凑状态为 760 × 58，之后会记住用户最后调整的宽度和紧凑栏高度。打开管理界面时保持当前宽度，只向下扩展到足够显示内容；关闭及下次启动后恢复保存的比例。
• 快捷轨会记住最后窗口位置，关闭 Eagle、重启电脑或重新打开 Eagle 后恢复；联动吸附带来的位置变化和位于副屏的负坐标也会保存。
• 紧凑状态和管理状态都允许从窗口边缘自由拉伸；紧凑栏会随高度填充，管理面板会随可用空间自适应，不留下黑色空框。

安装

Release 同时提供可直接安装的 .eagleplugin 文件和 GitHub 自动生成的源码压缩包。

直接安装（推荐）

1. 打开 Releases，进入 v1.0.0。
2. 下载 Eagle-QuickRail-v1.0.0.eagleplugin。
3. 双击安装包，按 Eagle 提示完成安装。

导入源码

1. 在 Release 中下载并解压 Source code (zip)，或使用下方 Git 命令克隆仓库。
2. 在 Eagle 中打开插件面板（默认快捷键 P）。
3. 右键插件面板，选择“开发者选项 → 导入本地项目”。
4. 选择包含 manifest.json 的仓库目录。

使用 Git 克隆

git clone https://github.com/zyc2pi/eagle-quickrail.git

使用

1. 点击快捷轨右侧的“管理”。
2. 搜索或滚动找到常用文件夹，点击勾选。
3. 点击“完成”，之后单击顶部入口即可跳转。
4. 点击文件夹左侧箭头可展开或收起；也可使用“全部展开 / 全部收起”。
5. “全部”默认已置顶，也可以在管理面板中取消。
6. 点击链条图标开启“联动吸附”；再次点击即可解除。
7. 在管理界面右侧切换到“使用统计”，选择时间范围查看次数。单击条目即可选择，再次单击可取消；数字表示它在快捷轨中的顺序。“全选”按当前排行加入全部文件夹，“取消全选”清空快捷轨选择。
8. 右键快捷轨中的项目可更换它在快捷轨里的颜色；点击“原”恢复原色。“从快捷轨移除”需要再次确认。
9. 右键项目后点击“调长度”，拖动卡片亮起的右边缘；点击轨道最右侧 ✓ 保存，点击 × 或按 Esc 取消。“默认长度”会清除该卡片的自定义长度。入口过多时，在轨道上滚动鼠标滚轮即可左右浏览。

常用操作速查

目标	操作
添加或移除快捷入口	打开“管理”，单击对应文件夹
调整快捷入口顺序	在快捷轨或管理界面的“快捷顺序”中拖动
区分同名文件夹	插件自动显示最短可区分的父级路径
修改颜色	右键快捷入口，选择快捷色；“原”恢复文件夹原色
修改卡片长度	右键 →“调长度”→ 拖动右边缘 → ✓ 保存
浏览溢出的快捷入口	在快捷轨上滚动鼠标滚轮，或点击左右箭头
快速打开前九项	快捷轨获得焦点后按 Alt + 1~9
隐藏快捷轨	点击最右侧 ×；之后可从 Eagle 插件面板再次打开

兼容性与实现说明

• 普通文件夹跳转使用 Eagle 官方 eagle.folder.open(folderId) API。
• 文件夹列表使用官方 eagle.folder.getAll() API，并监听资源库切换事件。
• Eagle 当前没有公开的文件夹点击事件，因此插件在运行期间每 650ms 读取一次 eagle.folder.getSelected()；只在选中文件夹发生变化时记录一次，不会因停留在同一文件夹而重复累计。
• Eagle 当前没有公开的“打开全部视图”插件 API，因此“全部”入口使用 Eagle 注入的主窗口 parentID，向主窗口已注册的 show-and-search IPC 导航事件发送消息并进入 openAll()；不依赖已禁用的 @electron/remote。
• “联动吸附”在 Windows 上通过 Eagle 的通用窗口 IPC 获取快捷轨原生句柄，并由插件内置的隐藏 PowerShell 助手同步两个窗口的位置；不会修改 Eagle 安装文件。
• 已在 Eagle 4.0 Build 23 的接口结构上开发；建议使用 Eagle 4.0 Build 18 或更高版本。

文件结构

quickrail/
├─ manifest.json
├─ index.html
├─ styles.css
├─ logo.png
├─ assets/logo.svg
├─ js/core.js
├─ js/plugin.js
├─ scripts/window-link.ps1
└─ tests/

隐私

插件只读取当前 Eagle 资源库的文件夹名称、层级、ID、颜色与当前选中状态。快捷入口的自定义显示色、卡片长度、使用记录及快捷轨窗口尺寸和位置保存在插件本地存储中；使用记录只保留最近 30 天且最多 20,000 条。插件不访问网络、不上传数据，也不直接修改资源库文件。

开发与验证

需要 Node.js 18 或更高版本。仓库不依赖第三方 npm 包：

npm test

测试覆盖文件夹树处理、快捷入口状态、窗口尺寸与位置记忆、生命周期时序、“全部”导航契约、使用统计、卡片长度及 Windows 联动助手。

如发现问题，请在 Issues 中提交，并附上 Eagle 版本、操作步骤和控制台报错。