简介这个基于jQuery的图片热区插件面向网页前端开发与设计人员用于在图片中绘制矩形、圆形、多边形等自定义形状区域并为每个区域单独绑定跳转链接或交互事件适合制作在线地图、商品热点标注、互动式教学示意图等页面。压缩包内含八个文件脚本文件负责核心逻辑样式文件控制热区外观图片文件提供界面素材另有可直接运行的示例页面、项目配置与说明文档整体体积约两百KB便于下载与集成。插件支持通过拖拽调整热区位置和尺寸也允许自定义配色和触发方式源代码注释丰富附带清晰的工程结构开发者可基于演示工程快速修改复用也可结合其他脚本扩展更多事件处理。目前已有两千余人学习特别适合需要快速为图片增加交互效果、但又不希望从零编写复杂逻辑的前端初学者。1. 图片热区不是area这么简单生产环境要的是绘制编辑与坐标校准一张商品详情图、一张户型图、一张系统架构图业务方经常提一句图上点某个位置要能弹信息窗、跳链接、或者联动展示说明。这类需求就是图片热区。很多团队的初版实现是糊一个 HTMLarea上去等编辑需求一多、图片在不同设备宽度来回切才发现这套方案根本撑不住。完整可落地的热区插件核心要解决三件事可视化绘制任意形状、坐标数据能持久化并回显、图片尺寸变化后热区自动校准。下文要拆的就是一套图片热区 js 插件从坐标系、数据结构、事件链路讲起再到上线后最容易踩的五个坑最后落到一个可以自动回归的坐标校验用例。适合要给商品图做标注、给架构图做交互、给户型图做热区的开发者参考。2. 方案选型为什么原生 area 只适合演示不适合生产用2.1 原生map的边界在于可视化和坐标维护原生方式需要先写好一个img usemap#xxx和一对maparea标签示例如下img srcproduct.png usemap#prod-map width800 height600 alt商品图 / map nameprod-map area shaperect coords100,80,240,260 href/item/a alt帽子 / area shapecircle coords500,220,45 href/item/b alt围巾 / /maparea的coords全部以图片原始像素为基准浏览器负责点击命中。问题在于三点第一rect、circle、polygon的坐标全靠手工量编辑一个区域等于重新算一遍像素第二area本身没有事件回调鼠标悬停和点击后的交互要再包一层 JS 去判断“落点是否落在某个 coords 范围内”等于把命中检测又做了一遍第三坐标是写死的绝对值图片一旦响应式缩放热区和图片的相对位置就错乱了每个断点要写一套 coords维护成本立刻失控。所以原生area在静态演示页能跑在需要人持续标注、数据要入库的系统里基本不可用。我一般会把热区插件的能力拆成三块透明叠加层负责承载图形绘制数据层负责把坐标归一化存储渲染层负责按当前图片显示尺寸把坐标换算回去。这样上层业务可以只关心“这张图上有哪些热区”不关心“这张图现在显示得多宽”。2.2 SVG 与 Canvas叠加层的两种主流做法实现透明叠加层有两条主流路线。SVG 叠加层的优势是热区是真实 DOM 节点click、mouseenter、mouseleave天然可绑定CSS 控制 hover 样式也方便甚至可以给某个热区直接加title提示劣势是热区数量到几百个时 DOM 节点会明显拖慢重绘而且每个节点的x/y/width仍然是像素绝对值同样要做归一化换算。在标注点只有二三十个、重点在语义化呈现的项目里SVG 是很好的选择。Canvas 叠加层则相反所有热区画在一张画布上绘制性能主要取决于图形数量而不是 DOM 层级几百个矩形、圆形重绘压力不大缺点是热区不进入 DOM点击命中要自己处理hover 样式也要在重绘时手动判断当前光标位于哪个热区。这套插件默认走 Canvas 叠加层选它的理由是热区数据在真实业务里常常几百条起步SVG 方案在这种量级下会让页面变得笨重。另外 Canvas 还有一个好处绘制中的草稿可以用更高透明度的样式展示视觉上更容易区分“编辑中”和“已保存”。2.3 先定坐标系再写插件初始化最容易翻车的点是把 Canvas 里的显示坐标和图片原始坐标当成同一个东西。实际上只需要区分两个坐标空间坐标空间 A图片自然尺寸也就是naturalWidth / naturalHeight。热区数据持久化时永远存这个空间的坐标图片文件不变坐标就不会变。坐标空间 B图片在页面里实际渲染出来的尺寸比如 400px 宽。绘制、鼠标命中、重绘都发生在该空间里因为鼠标事件拿到的只能是显示坐标。两个空间的换算公式为scaleX displayWidth / naturalWidth scaleY displayHeight / naturalHeight displayX originX * scaleX图片如果被object-fit: cover拉伸裁剪还要把裁剪后的显示偏移量算进去如果保持原始比例缩放取Math.min(scaleX, scaleY)并居中即可否则画出来的圆会变椭圆。插件的最小初始化配置如下div idhotspot-app styleposition: relative; width: 100%; max-width: 800px; img idtarget-img srcdemo.jpg alt标注图 styledisplay: block; width: 100%; / canvas idhotspot-canvas styleposition: absolute; inset: 0;/canvas /divconst app new HotspotPlugin({ canvas: #hotspot-canvas, image: #target-img, mode: rect, // rect | circle | polygon strokeColor: #ff4d4f, strokeWidth: 2, fillColor: rgba(255, 77, 79, 0.15), onSave: (hotspots) { localStorage.setItem(hotspots, JSON.stringify(hotspots)); } });canvas和image分别指向叠加层与底图mode决定新建热区的形状strokeColor与fillColor控制编辑态视觉fillColor里的透明度建议留一点否则会完全遮住图片onSave是每次编辑动作结束后的回调这里只演示了写入 localStorage落地时一般会 POST 到后端。注意缩放系数必须以图片显示区域的实际尺寸为基准容器的padding和border都不算数。很多项目热区偏移就是因为初始化时拿容器尺寸当图片尺寸用导致整组坐标被固定偏移。3. 把坐标玩成数据热区 JSON 结构、事件链路与后端回显3.1 可持久化的热区数据结构热区数据要同时满足前端绘制、后端存储、审核端展示三个场景字段建议统一成下面这套字段类型说明idstring热区唯一标识编辑删除时需要typestringrect/circle/polygonpointsarray坐标点数组按类型规则解析labelstring业务标签如“帽子区”“入口A”dataobject业务附加数据如跳转链接displayIndexnumber层级顺序值越大越在上层rect的points存左上角和右下角两个点[{x,y}, {x,y}]circle存圆心加半径[{x, y, r}]polygon存完整顶点数组。所有坐标都放在图片自然尺寸空间。这样设计的好处是业务侧不关心屏幕宽度不管前端放到 iPhone 还是 4K 屏只要图片的naturalWidth不变换算就正确。导出给其他系统时有时需要相对坐标也就是以图片宽高为 1 的百分比。不少同事喜欢直接把相对坐标入库但我的建议是接口层存自然尺寸绝对坐标渲染层动态算相对值因为相对坐标虽然能响应式但导出去给别的工具用时还得再乘一遍图片尺寸多一道转换反而容易出错。如果确实需要比值写一个转换函数即可function normalisePoints(points, { width, height }) { if (points.length r in points[0]) { return [{ x: points[0].x / width, y: points[0].y / height, r: points[0].r / width }]; } return points.map(p ({ x: p.x / width, y: p.y / height })); }circle的半径这里除以width而不是height是因为圆形热区在视觉上应当保持正圆等比例缩放时r / width和r / height结果一样但取width作为基准更符合“宽度决定缩放”的直觉。如果图片本身被非等比拉伸用r / width至少能保证水平方向不超出图片边界。3.2 mousedown 到 onSave绘制与编辑的完整事件链路热区操作需要区分绘制态和查看态绘制态下鼠标拖拽生成新热区查看态下点击热区触发业务回调。事件链路的核心代码如下canvas.addEventListener(mousedown, (e) { if (app.mode view) return; const { offsetX, offsetY } toCanvasPoint(e); app.drawing true; app.currentHotspot app.createDraft(offsetX, offsetY); canvas.addEventListener(mousemove, onDrawingMove); }); function onDrawingMove(e) { if (!app.drawing) return; const { offsetX, offsetY } toCanvasPoint(e); app.updateDraft(app.currentHotspot, offsetX, offsetY); renderCanvas(); } canvas.addEventListener(mouseup, (e) { if (!app.drawing) return; app.drawing false; canvas.removeEventListener(mousemove, onDrawingMove); app.finishDraft(app.currentHotspot); app.onSave(app.getSerializedHotspots()); });这里最关键的是toCanvasPointfunction toCanvasPoint(e) { const rect canvas.getBoundingClientRect(); return { offsetX: e.clientX - rect.left, offsetY: e.clientY - rect.top }; }不建议用浏览器原生的e.offsetX / e.offsetY因为 Canvas 被 CSS 缩放、页面发生滚动、或者外层容器有边框时这个相对值不可靠。用clientX减getBoundingClientRect().left是最稳的基准任何布局下都不会差。createDraft创建草稿对象updateDraft根据鼠标移动位置更新矩形对角线或圆半径finishDraft负责补齐id和时间戳最后onSave输出可持久化的序列化结果。每次绘制完成后要立即解绑mousemove否则下次 mousedown 会重复绑定出现一次移动触发多次更新的问题。3.3 回显与多端一致性保存阶段就是把app.getSerializedHotspots()的结果提交到后端。回显阶段后端返回同样结构的 JSON前端逐个还原坐标并重绘function denormalisePoints(points, { width, height }) { if (points.length r in points[0]) { return [{ x: points[0].x * width, y: points[0].y * height, r: points[0].r * width }]; } return points.map(p ({ x: p.x * width, y: p.y * height })); } async function loadHotspots(imgId) { const res await fetch(/api/image/${imgId}/hotspots); const hotspots await res.json(); app.setHotspots(hotspots.map(hs ({ ...hs, points: denormalisePoints(hs.points, app.imageSize) }))); app.setMode(view); // 回显时不进入绘制态防止误操作 renderCanvas(); }注意回显基准里app.imageSize必须取自当前页面里图片元素的naturalWidth / naturalHeight而不是数据库里存的旧尺寸。图片一旦被运营替换过旧坐标整体失效用旧尺寸回显会让热区全部错位。setMode(view)这一步也值得保留否则回显完还是绘制态用户一点图片就会误画一个热区。注意回显时后端返回的图片尺寸要以当前页面img元素的naturalWidth为准。换过图就重新拉一次数据不要让旧数据继续渲染。4. 图片热区避坑实录定位漂移、事件穿透与高清屏模糊4.1 浏览器缩放后热区整体错位现象页面刚加载时热区位置正确浏览器窗口缩放或开发者工具切换设备模式后热区整体偏移越靠近图片右下角偏差越大。原因热区数据里保存的是显示坐标没有做归一化。窗口一变显示尺寸跟着变旧坐标还是按变之前的显示尺寸算的自然对不上。解决存储时统一使用自然尺寸绝对坐标渲染时通过变换函数换算function buildDisplayTransform(naturalSize, displaySize) { const scaleX displaySize.width / naturalSize.width; const scaleY displaySize.height / naturalSize.height; const scale Math.min(scaleX, scaleY); const offsetX (displaySize.width - naturalSize.width * scale) / 2; const offsetY (displaySize.height - naturalSize.height * scale) / 2; return { scale, offsetX, offsetY }; }这段逻辑同时兼容object-fit: contain的图片居中的偏移量通过offsetX / offsetY补上。如果图片是拉满容器且不做等比缩放scaleX等于scaleY偏移量就是 0但保留这两个字段能让函数适用更多场景。4.2 绘制起点偏移直接用了 offsetX 对不准现象鼠标点击后画出的矩形起点和光标位置差了二三十像素且所有热区都朝同一个方向偏。原因代码里用了e.offsetX但 Canvas 被 CSS 拉伸、外层容器有边框或圆角时offsetX与 Canvas 的像素坐标并不对齐。这个偏差在普通笔记本上不明显换到大屏显示器或高分屏后尤其突出。解决统一用e.clientX - canvas.getBoundingClientRect().left作为绘制坐标。拿到坐标后先不要直接画到 Canvas 上而是先换算到图片自然尺寸空间渲染时再转回来形成闭环。4.3 查看态时 Canvas 挡住图片下层链接现象热区功能做完后图片上方的按钮点击无反应连 hover 样式都不触发。原因透明 Canvas 始终悬浮在图片上方默认会捕获所有鼠标事件。即使没进入绘制模式事件也被 Canvas 拦截图片下方的链接自然点不到。解决把事件捕获开关和交互模式绑定function setInteractMode(mode) { if (mode drawing || mode editing) { canvas.style.pointerEvents auto; canvas.style.cursor crosshair; } else { canvas.style.pointerEvents none; canvas.style.cursor default; } }查看态设置pointer-events: none鼠标事件直接穿透 Canvas 到图片或链接进入绘制或编辑态再恢复auto。注意切换时要把mode和 CSS 同步更新否则会出现“界面显示在编辑中但 Canvas 不响应鼠标”的怪现象。4.4 高分屏上线后线条发虚现象普通 PC 上正常换到高分屏后发现热区描边特别虚文字和辅助线模糊。原因Canvas 的实际像素没有跟上devicePixelRatio。浏览器把 CSS 像素映射到物理像素时做了放大1 CSS 像素在 2 倍屏上需要 4 个物理像素去近似线条边缘自然发虚。解决创建 Canvas 时把画布实际尺寸乘以devicePixelRatio再用setTransform把绘制坐标系压回来const dpr window.devicePixelRatio || 1; canvas.width displayWidth * dpr; canvas.height displayHeight * dpr; canvas.style.width displayWidth px; canvas.style.height displayHeight px; ctx.setTransform(dpr, 0, 0, dpr, 0, 0);注意这里不要用ctx.scale(dpr, dpr)多次调用会叠加setTransform是重置变换后再设置更安全。设置完成后鼠标坐标仍然按 CSS 像素计算绘制落点却已经对齐到物理像素线条就清晰了。Canvas 的 CSS 尺寸和绘制尺寸一旦不一致鼠标坐标与绘制位置也会错位这两个问题经常一起出现。4.5 图片还没加载完就初始化现象初始化代码执行时无报错但页面出现后 Canvas 尺寸为 0或者画着画着热区消失。原因new HotspotPlugin()执行时图片的naturalWidth还不是真实值插件用 0 作为基准尺寸创建了画布图片加载完成后画布没有跟着更新热区全部绘制到了可当前位置。解决初始化前先等图片解码完成img.decode()是现在比较稳的方式const img document.querySelector(#target-img); if (img.complete) { initHotspot(); } else { img.addEventListener(load, initHotspot, { once: true }); }用fetch动态加载图片时还要额外处理 404否则插件会一直等待。老项目里如果没有decode就退回到load事件监听两者选一个即可不要两个混用。5. 进阶响应式校准、批量工作流与热区渲染性能5.1 图片尺寸变化时如何自动校准商品图在不同设备下宽度会动态变化热区不能只做一次换算就完事。常见做法是监听容器尺寸变化重新计算变换系数并重绘function refreshHotspotOverlay() { const displaySize imageEl.getBoundingClientRect(); const transform buildDisplayTransform(imageSize, { width: displaySize.width, height: displaySize.height }); renderHotspots(transform); } const resizeObserver new ResizeObserver(refreshHotspotOverlay); resizeObserver.observe(containerEl);注意ResizeObserver在初始化阶段会立即触发一次如果此时图片还没加载完成会拿到错误尺寸最后又能被下一轮回调修正但中间会出现一次闪动。保险做法是先检查imageEl.naturalWidth 0再执行重绘。老浏览器不支持ResizeObserver时退化成window.resize监听即可效果基本一致只是无法感知容器单独变化。5.2 批量标注从手画到状态流转如果运营要在一张图上标几十个商品入口单纯能画还不够还需要解决中途保存、多人协作、审核发布这串问题。我的做法是给每条热区数据加状态字段pending表示草稿、published表示已发布、disabled表示隐藏。绘制时只处理pending其他状态只渲染不编辑const stateMap { pending: { color: #faad14, editable: true, visible: true }, published: { color: #52c41a, editable: false, visible: true }, disabled: { color: #d9d9d9, editable: false, visible: false } };这样设计后编辑端可以直接把新画的临时状态pending提交审核端只展示新增和修改的热区通过后再统一发布为published。导出 JSON 时带上状态字段后端也能按状态过滤不需要额外维护一套“临时表”和“正式表”。5.3 热区数量大了分层渲染与命中检测当热区数量到两三百个时全量重绘会开始卡顿。常见手段是分层底层 Canvas 渲染所有已保存热区顶层 Canvas 只画绘制中的临时热区。编辑过程中只重绘顶层保存成功后再把顶层内容合并到底层。命中检测也要避免“全量遍历所有顶点再解析几何”矩形和圆形先做包围盒预筛再用公式精确命中多边形先用getBoundingRect粗筛再走射线法判断点是否在多边形内部。这里的关键是区分瓶颈绘制卡住就分层命中卡住就加包围盒缓存保存回显卡住就把序列化放进requestIdleCallback里。大多数项目用不到 Web Worker硬件性能和浏览器兼容性都不划算。6. 坐标校准回归用例交付前跑完这三步再发版坐标换算逻辑是热区插件最容易改出隐形 bug 的地方。我的习惯是每次改完先跑一个纯函数回归用例再进浏览器做三步验证。回归用例的核心思路给定一组图片自然尺寸和显示尺寸任取四个边角坐标正向换算后再反向换算误差必须控制在 0.001px 以内function calibrationTest() { const natural { width: 1200, height: 800 }; const display { width: 600, height: 400 }; const transform buildDisplayTransform(natural, display); const testPoints [ { x: 10, y: 10 }, { x: 800, y: 600 }, { x: 1200, y: 1 }, { x: 1, y: 800 } ]; for (const pt of testPoints) { const displayPt { x: pt.x * transform.scale transform.offsetX, y: pt.y * transform.scale transform.offsetY }; const backPt { x: (displayPt.x - transform.offsetX) / transform.scale, y: (displayPt.y - transform.offsetY) / transform.scale }; const err Math.abs(backPt.x - pt.x) Math.abs(backPt.y - pt.y); if (err 0.001) { throw new Error(坐标回归失败: ${pt.x},${pt.y} 误差 ${err}); } } }四个测试点分别落在左上角、图片中下部、右上角边界、左下角边界覆盖了偏移量参与计算的极端情况。跑完这个用例后我还会在浏览器里手动走一遍进入绘制模式在图片四个角各画一个热区确认位置贴合鼠标把浏览器窗口缩到一半再放大看热区是否跟着图片一起缩放最后开启高分屏模拟确认线条不发虚。三步走完后再做一次“保存、刷新、回显”的完整闭环基本没有漏过问题的可能。如果你准备把这套热区插件接进自己的项目源码包和示例工程在资源下载处可以拿到里面包含 rect、circle、polygon 三种绘制模式、坐标序列化与回显、设备像素比适配以及一个可运行的坐标校准用例改一下图片路径就能直接看效果。从那以后我每次改坐标相关代码都会强制自己先跑一遍校准用例再提测这个习惯已经拦下好几次“看着没问题、上线就歪”的事故希望帮到你。本文还有配套的精品资源点击获取