🌟 写在前面:为什么要做「小鱼工具箱」?
在日常开发和设计工作中,大家或多或少都有过这样的体验:
- 想下载站酷上的设计参考,发现网页右键被禁用,图片还被裁切成低清小图;
- 临时想转个 Unix 时间戳、格式化一段 JSON,打开在线工具网站,广告多得眼花缭乱;
- 下载了现成的很多工具箱软件,体积动辄几百兆,功能繁琐,还无法自己扩充定制。
“既然市面上的工具不够趁手,那为什么不自己动手做一个?”
于是,小鱼工具箱(Xiaoyu Toolbox) 诞生了!它是一个专为开发者和设计师打造的开源跨平台桌面客户端,基于 Electron + 原生 HTML5 / CSS3 / JavaScript 构建。
它的核心理念极其纯粹:
- 轻量纯粹:拒绝臃肿复杂的框架绑定,原生极简,秒级启动;
- 插卡式解耦:像小霸王游戏机插卡带一样,每个工具模块完全独立;
- 极低开发门槛:只要你会写基础的 HTML/JS,5 步就能快速扩展出你自己的专属实用小工具!
今天这篇博客,我们就带大家揭秘小鱼工具箱的架构设计,并手把手教你编写第一个属于自己的工具插件!
🖥️ 小鱼工具箱目前长啥样?有哪些酷炫功能?
在动手写代码前,先来看看工具箱目前的“当家花旦”功能:
1. 首发王牌:站酷设计参考高清批量提取器
平时做前端或 UI,少不了去站酷(Zcool)找灵感。但网页通常会压缩图片分辨率、限制右键,甚至有防盗链保护。
小鱼工具箱内置了强大的无感解析与下载引擎:
- 穿透反爬:利用 Electron 底层引擎无缝抓取作品详情,自动提取所有设计稿原图。
- 还原无损超清:智能识别并剔除网页裁剪参数(例如将预览图自动转回原始高清分辨率)。
- 瀑布流卡片交互:支持单选、反选、一键全选,直观清爽。
- 多线程并发下载:底层自动注入
Referer防盗链请求头,下载速度拉满,并配有实时动态进度条。
2. 全局通用设置中心
- 自由指定全平台存储目录(原生弹窗呼出访达 / 资源管理器);
- 智能按「作品名称 - 作者」自动规整归档文件夹;
- 一键直达保存目录,告别翻找路径的烦恼。
3. 双平台一键秒启与热重载
- macOS:执行
./run.sh即可自动检查环境并秒级拉起; - Windows:双击
run.bat即可开箱即用; - 极速热重载:内置防抖文件监听,改完 HTML/JS 代码,桌面窗口自动实时重载刷新,爽快程度堪比 Web 开发!
🏗️ 架构解析:什么是“插卡式模块化”?
许多初学者做桌面工具箱时,容易把所有业务逻辑写在同一个大文件里,工具多了之后代码变成“意大利面条”,牵一发而动全身。
小鱼工具箱采用了完全解耦的“插卡式设计”(类似微内核架构):
tools/
├── main.js # Electron 主进程(负责窗口管理、底层 Node 能力与系统 IPC)
├── preload.js # 安全桥接脚本(主进程能力安全暴露给前端)
├── src/
│ ├── index.html # 主窗口外壳(统一的侧边栏导航 + 各模块视图容器)
│ ├── renderer.js # 主界面路由总控(负责侧边栏切换、激活对应模块)
│ ├── styles/ # 统一的极简深色主题样式
│ └── modules/ # 独立子模块目录(核心!)
│ ├── zcool/ # 站酷工具
│ ├── settings/ # 设置中心
│ └── [your-tool]/ # ✨ 你要扩充的新工具!核心分工原则:
- 主壳只管调度,不管业务:
renderer.js只管识别用户点了侧边栏哪个按钮,然后展示对应的视图,并调用对应工具模块的init()方法。 - 子模块高度自治:每个工具在
src/modules/<tool-id>/下拥有独立的文件夹,使用自执行闭包函数(IIFE),内部变量绝不外泄,互不干扰。 - 渐进式能力:如果你的工具只是简单的纯前端逻辑(如文本统计、进制转换),完全不需要碰底层 Node 代码;如果需要读写本地文件或执行系统命令,通过
preload.js统一调度即可。
🚀 动手实战:5 步开发你的第一个插件「时间戳与日期转换器」
现在,假设我们经常需要把时间戳转换成可读的日期,或者把日常时间转成 10 位/13 位 Unix 时间戳。让我们一起为小鱼工具箱新增一个「时间戳转换 (timestamp-tool)」工具!
步骤 1:确定工具标识 (ID) 与基本信息
- 工具唯一 ID:
timestamp-tool(统一采用小写中划线命名) - 工具名称:时间戳转换
- 功能描述:Unix 时间戳与标准北京时间双向快捷转换
步骤 2:在 src/index.html 注册侧边栏导航与主视图
打开 src/index.html:
2.1 在侧边栏导航列表(<ul class="nav-list">)中追加导航项:
提示:一般放置在“工具设置”项之前。
<!-- 新增:时间戳转换工具导航 -->
<li class="nav-item" data-tool="timestamp-tool">
<span class="nav-icon">
<!-- 24x24 矢量时钟图标 -->
<svg class="icon-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<circle cx="12" cy="12" r="10"></circle>
<polyline points="12 6 12 12 16 14"></polyline>
</svg>
</span>
<span class="nav-text">时间戳转换</span>
</li>2.2 在主内容区(<main class="main-content">)中追加专属视图容器:
<!-- 新增:时间戳转换工具的主视图面板 -->
<section class="tool-view hidden" id="view-timestamp-tool">
<div class="card">
<div class="card-header">
<h2 class="card-title">时间戳与日期转换</h2>
<p class="card-subtitle">支持秒级 (10位) / 毫秒级 (13位) 时间戳与日常日期的快速双向互转</p>
</div>
<div class="card-body">
<!-- 当前时间实时显示 -->
<div style="margin-bottom: 20px; padding: 12px; background: rgba(255,255,255,0.04); border-radius: 8px;">
<span>当前系统时间戳:</span>
<strong id="ts-current-val" style="color: #60a5fa; font-family: monospace;">-</strong>
</div>
<!-- 转换表单 -->
<div style="display: flex; gap: 12px; align-items: center; margin-bottom: 16px;">
<input type="text" id="ts-input" class="input-text" placeholder="输入时间戳或日期字符串(如 2026-09-25 10:00:00)" style="flex: 1;" />
<button id="ts-btn-convert" class="btn btn-primary">一键转换</button>
</div>
<!-- 结果展示框 -->
<div id="ts-result" style="padding: 14px; background: rgba(0,0,0,0.3); border-radius: 8px; border: 1px solid rgba(255,255,255,0.08); font-family: monospace; min-height: 48px; color: #34d399;">
等待输入转换...
</div>
</div>
</div>
</section>2.3 在 src/index.html 底部引入对应的 JS 脚本:
<script src="modules/timestamp-tool/timestamp-tool.js"></script>步骤 3:创建独立的模块业务脚本
在 src/modules/ 目录下新建文件夹 timestamp-tool,并创建 timestamp-tool.js:
/**
* ====================================================================
* 小鱼工具箱 - 时间戳转换模块 (timestamp-tool.js)
* ====================================================================
*/
// 使用自执行函数闭包,防止变量泄漏到全局
window.TimestampToolModule = (function () {
// 私有变量:记录模块是否已初始化
let hasInited = false;
let timerId = null;
/**
* 模块主入口:当用户第一次在侧边栏点击本工具时,由主路由调用
*/
function init() {
if (hasInited) return; // 避免重复注册事件
hasInited = true;
// 启动当前时间戳实时刷新
startClock();
// 绑定转换按钮点击与回车事件
bindEvents();
console.log('[时间戳工具] 模块初始化完成');
}
/**
* 动态刷新当前系统时间戳
*/
function startClock() {
const currentEl = document.getElementById('ts-current-val');
if (!currentEl) return;
function update() {
const now = new Date();
currentEl.textContent = `${Math.floor(now.getTime() / 1000)} (秒) / ${now.getTime()} (毫秒)`;
}
update();
timerId = setInterval(update, 1000);
}
/**
* 绑定界面交互事件
*/
function bindEvents() {
const btn = document.getElementById('ts-btn-convert');
const input = document.getElementById('ts-input');
const resultBox = document.getElementById('ts-result');
if (!btn || !input || !resultBox) return;
btn.addEventListener('click', handleConvert);
input.addEventListener('keydown', (e) => {
if (e.key === 'Enter') handleConvert();
});
function handleConvert() {
const val = input.value.trim();
if (!val) {
// 调用小鱼工具箱全局统一的轻量 Toast 提示
if (window.Renderer && window.Renderer.showToast) {
window.Renderer.showToast('请输入要转换的内容', 'warning');
}
return;
}
// 判断输入是纯数字时间戳,还是日期文本
if (/^\d+$/.test(val)) {
// 时间戳转日期
let num = parseInt(val, 10);
// 如果是10位秒级时间戳,乘以1000转毫秒
if (val.length === 10) num *= 1000;
const date = new Date(num);
if (isNaN(date.getTime())) {
resultBox.textContent = '❌ 无效的时间戳数值!';
} else {
resultBox.textContent = `✅ 转换成功:${date.toLocaleString('zh-CN', { hour12: false })}`;
if (window.Renderer) window.Renderer.showToast('转换成功', 'success');
}
} else {
// 日期文本转时间戳
const date = new Date(val);
if (isNaN(date.getTime())) {
resultBox.textContent = '❌ 日期格式不正确,请参考:2026-09-25 10:00:00';
} else {
const sec = Math.floor(date.getTime() / 1000);
const ms = date.getTime();
resultBox.textContent = `✅ 秒级时间戳:${sec} | 毫秒级:${ms}`;
if (window.Renderer) window.Renderer.showToast('转换成功', 'success');
}
}
}
}
// 必须对外暴露统一的 init 方法
return {
init: init
};
})();步骤 4:在主路由总控 src/renderer.js 注册激活逻辑
打开 src/renderer.js,找到切换面板的函数 switchTool(toolId),在条件分支中加上两行代码:
// 切换视图逻辑中:
if (toolId === 'timestamp-tool' && window.TimestampToolModule) {
window.TimestampToolModule.init();
}步骤 5:启动查看你的杰作!
回到项目根目录:
- 如果你是在 macOS:打开终端运行
./run.sh; - 如果你是在 Windows:双击
run.bat。
由于内置了热重载机制,只要你保存了代码,小鱼工具箱桌面端就会立刻自动刷新!你可以在侧边栏看到刚刚添加的【时间戳转换】,点击即可直接使用。
整个过程仅仅修改了 3 处配置,编写了一个独立的 JS 文件,没有改动任何已有模块的代码,这就是插卡式架构的魅力!
💡 新手避坑指南(划重点 ⚠️)
如果你也是初次尝试开发 Electron 或原生多工具应用,一定要留意以下几个常见坑点:
1. 警惕全局作用域污染
- 踩坑现象:工具 A 里定义了
let config = {},工具 B 里也定义了let config = {},互相覆盖导致诡异的 Bug。 - 最佳解法:每个模块务必包裹在
(function() { ... })()闭包内,或者封装为 Class,只向window暴露唯一的模块对象(如window.TimestampToolModule)。
2. 避免 DOM ID 撞车
- 踩坑现象:大家都喜欢把按钮叫
id="btn-submit",把输入框叫id="input-val",导致获取到的 DOM 错乱。 - 最佳解法:为所有专属 DOM 元素加上工具 ID 前缀,例如
id="ts-input"、id="ts-btn-convert"。
3. 理解渲染进程 vs 主进程(IPC 边界)
- 纯前端能解决的,不要跨进程:像时间戳转换、文本去重、JSON 格式化、正则表达式测试等,纯前端 JS 就能搞定,完全不需要调主进程。
- 需要系统权限的,走安全 IPC:如果要保存文件到本地磁盘、读取系统剪贴板的大文件、执行 Shell 脚本,一定要在
main.js注册ipcMain.handle,并在preload.js暴露安全方法,千万不要在前端页面直接使用 Node 的require('fs')(开启nodeIntegration极易带来安全隐患)。
📦 如何打包成独立的桌面安装包?
开发完工具后,怎么发给没有 Node 环境的小伙伴使用?
小鱼工具箱已预先配置好 electron-builder,打包极为轻松:
🍎 打包 macOS 安装包(.dmg / .zip):
npm run build:mac打包产物将自动生成在 dist/ 目录下,双击即可将软件拖入 Applications 安装。
🪟 打包 Windows 安装包(.exe 安装版 / 免安装便携版):
npm run build:win支持一键安装包及单文件免安装绿色版(Portable)。
🤝 一起加入开源共建吧!
小鱼工具箱是一个拥抱社区、持续生长的个人工具集合。
不管是:
- 💡 一个实用的日常小工具(如:图片格式互转、Markdown 表格生成器、配色提取器等);
- 🐛 一份 Bug 反馈或界面优化建议;
- 📖 完善使用文档或扩展指南;
都非常欢迎大家 Fork 项目并提交 Pull Request!让我们一起打造出最好用、最轻巧的个人桌面万能工具箱。
欢迎在评论区留下你最想要的工具功能,我们下期实战教程见!
