先问个实际问题:你手头有没有一堆设计稿、截图或者产品原型图,需要快速在上面标出问题点、给协作方解释"细节这里不对、那里要改",结果发现要么开设计软件太重,要么在线平台要注册还限制素材数量?我为了对付这种场景写了个小工具——一个开源的HTML气泡图标注小工具,单文件搞定,浏览器双击打开就能用,不需要安装、不需要联网、不需要注册。这篇文章完整拆解它的实现思路和踩坑经历,包括核心的坐标换算、气泡拖拽、画布导出这几个关键模块的代码逻辑,适合想做轻量工具的前端新手,也适合产品、设计、测试这类经常要批量截图标注意的岗位。
1. 为什么偏要用HTML做气泡图标注工具
先说清楚我说的"气泡图标注"是什么。它和普通图片标注不太一样:目标不是框选区域或者画箭头,而是在图片的任意位置打上一个带数字序号的圆形气泡,数字从小到大排列,旁边可以附一句说明文字。最终产出的效果很像电商商品详情页上的"卖点标注图",也像设计评审时给交互稿打的批注点。这种形式特别适合"按点位去说明"的场景——你不需要精确画出某个区域,只需要让看图的人顺着数字1、2、3往下走就能理解你要表达的顺序。
这个需求本身不复杂,但市面上很少有工具是"刚刚好"针对这个场景的。截图工具只有箭头和方框,标注多了画面就显得乱;在线协作白板又太重,杀鸡用牛刀;正经的设计工具学习成本又高。我做这个小工具之前反复想过:用户真正需要的是什么?其实就三条:能传图、能在图上打带数字的圆点、能导出带标注的完整图片。仅此而已。
1.1 气泡标注工具的核心使用场景
我盘点了一下自己实际使用中的场景,大概分这么几类:
- 设计评审:把UI稿截图拖进工具,在第1个气泡写"按钮间距失衡",第2个写"这里颜色对比度不够",一次评审的反馈就能通过一张图传递干净。
- 课程讲义/操作指引:在系统截图里把操作入口用气泡标出顺序,1、2、3排好,学生照着点就不会迷路。
- 数据分析图表说明:在折线图、柱状图上标注异常点,附带说明文字,比单独在底下写注释直观得多。
- 电商详情页策划:在竞品详情页截图上标注借鉴点,方便给设计团队布置任务。
这些场景的共同特点是什么?轻量、临时、高频。你不可能为了一次性标注去专门下载安装一个完整的设计软件,但你又确实需要一个"比画图好用、比设计软件轻便"的中间态工具。这也是我坚持要做成"浏览器打开即用"形态的根本原因。
1.2 为什么"单文件、零依赖"是方案的核心
确定要做一个轻量工具之后,我给自己定了几条硬性约束:
- 单个HTML文件就能运行,不要打包、不要构建、不要npm install。
- 不依赖任何外部库和CDN,保证离线可用、内网可用。
- 开源,别人拿到源码能看懂、能改,而不是一个黑盒。
- 数据能导出,标注成果不能只活在这个工具里。
这个"单文件"约束看起来简单,其实会在技术选型上产生一系列连锁反应。既然不能用React/Vue,那就老老实实操作原生DOM;既然不能用Canvas绘图库,那就直接用Canvas 2D原生API或者纯DOM来画气泡;既然不能引入设计系统,那UI就自己写内联CSS。但正是这些限制,让工具保持了一种"原始但有效"的可靠感。
从分发角度讲,单HTML文件有一个不可替代的优势:传播即使用。你把这个文件通过聊天窗口发给同事,对方下载后双击就在浏览器打开了,整个过程没有环境变量、没有路径依赖、没有版本冲突。如果按传统思路做一个前后端分离的项目,那部署、维护、权限这些环节会瞬间淹没"标注"这个核心需求。
1.3 开源协议与代码可读性的取舍
这个工具我按MIT协议开源,也就是说别人拿去做商业用途也不会有法律障碍。我在代码结构上刻意保持了极简风格——全部逻辑只分三个区块:状态管理(标注数据)、渲染函数(气泡绘制)、事件处理(添加/拖拽/删除)。
我没有把所有代码堆在一个 <script> 标签里完事,而是模拟了模块化的写法,用注释分隔出"数据层""渲染层""交互层"。理由很简单:开源项目最大的价值不是代码能跑,而是别人能跑起来之后快速知道怎么改。哪怕只是加一个"气泡变红"的小功能,如果看代码的人要花半小时才能定位到相关逻辑,那这个开源工具的教育意义就打折了。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 工具的主流程:从打开页面到导出标注图
我写代码时首先定义的是用户操作路径,反过来驱动界面设计。最终的操作流程被我收敛成五步:打开页面 → 上传图片 → 点击添加气泡 → 输入说明文字 → 导出结果。核心界面其实就一个文件选择按钮、一张画布、一排操作控件。
有两个小细节我做了特别处理。一是页面默认展示一张示意图片,用户完全不懂怎么操作时打开就能看到"原来气泡长这样",降低上手门槛;二是"添加气泡"采用开关模式,点一下按钮进入连续添加状态,可以在图片上快速打多个点,不用每加一个就点一次按钮。
2.1 上传图片与画布的初始化逻辑
用户选定本地图片后,我读取文件对象,通过 URL.createObjectURL(file) 生成临时访问地址,然后加载到一个隐藏的Image对象里。为什么不是直接塞给Canvas?因为Canvas绘制图片前必须先知道图片的真实尺寸(自然宽高),只有等Image触发 `onl
