尧图网页设计 
简介图片热区是网页交互中的常见技术通过在一张图上划分自定义区域并绑定链接或事件可以创造出丰富的互动体验。这份“图片热区js插件”正是面向前端开发者和网页设计师的轻量级jQuery工具解决了手工编写坐标映射代码耗时且难以维护的问题适用于在线地图、产品展示、交互式教学等场景。资源压缩包共8个文件以两个js文件为核心包含插件主体与jQuery依赖另配有css样式、html演示页、png图像素材、xml工程配置以及md说明文档整体仅约209KB结构精简便于直接引入或扩展。目前已有2271人学习下载。功能上插件支持自由绘制矩形、圆形等热区可精确调整位置与尺寸每个热区均可绑定独立URL同时与IntelliJ IDEA等IDE良好集成便于在编码环境中实时预览。源码注释丰富目录组织清晰包含了可直接运行的demo能帮助开发者快速掌握图片热区的实现思路并在此基础上定制个性化交互逻辑有效提升页面开发效率。1. 图片热区 js 插件把图片划分成可交互区域到底解决了什么图片热区image hotspot / image map是前端交互里出现频率很高的老需求户型图按房间选房、电商主图标注每个卖点位置、室内全景划分家具区域、医学影像标记病灶。登录过任何选房平台或在线工具几乎都会碰到它。原生 HTML 的map/area能画矩形、圆和多边形但交互能力非常弱——没有默认高亮、没有缩放适配、多图切换要手动刷新。图片热区 js 插件要做的就是把坐标数据、渲染层、事件回调、响应式缩放统一封装起来让同一套热区配置同时跑在桌面端和移动端。我在这里把选型、数据格式、最小可运行实现和踩坑记录完整讲一遍适合正在做图片标注类功能的前端开发以及被areacoords 维护折腾过的产品前端。2. 三种图片热区实现路径与选型逻辑为什么插件值得引入图片热区不是单一技术而是“数据 渲染 交互”的组合体。给自己做方案前先把原生 map、Canvas、SVG 三条路走一遍看清各自边界才能判断插件值不值得写或引入。2.1 原生/结构简单但交互回天乏术原生方式就是把映射关系直接写进 HTMLimg srcfloor.png usemap#floorMap alt户型图 / map namefloorMap area shaperect coords10,10,120,80 href#room-main alt主卧 / area shapecircle coords200,160,30 href#room-kitchen alt厨房 / /maparea 的 coords 是相对原图自然像素的坐标浏览器在图片显示尺寸变化时不会自动换算必须在脚本里手动改。shape 只有 rect、circle、poly 三种高亮、悬浮样式都没有缺省行为tooltip 要自己再套一层 DOM。如果业务只有一张静态图、几个链接跳转原生方案够用但只要涉及响应式、动态增删热区、点击反馈调试成本立刻上升。实际开发里我在响应式布局下做过一次原生 area 的缩放换算代码是这样的img.addEventListener(load, () { const rect img.getBoundingClientRect(); const ratio rect.width / img.naturalWidth; const realCoords area.getAttribute(coords) .split(,) .map(v Math.round(parseFloat(v) * ratio)); area.setAttribute(coords, realCoords.join(,)); });这段逻辑每次 window resize 都要重跑一遍多张图、多块 area 时就会陷入重复劳动而且 polygon 的每个顶点都要乘比例漏一个点热区就错一位。很多老项目就是用这种方式撑下来的代码又长又脆。2.2 Canvas 命中检测热区多时性能最稳Canvas 方案的做法是用 isPointInPath 做屏幕坐标命中检测热区本身不是 DOM 节点// 判断点是否落在某个矩形热区内 const hitRect (ctx, x, y, r) { ctx.beginPath(); ctx.rect(r.x, r.y, r.width, r.height); return ctx.isPointInPath(x, y); };每次鼠标移动都遍历所有热区几何体做命中测试热区数量到几百个时性能仍然稳定因为不涉及 DOM 创建。痛点也很明确热区没有实体节点hover 反馈只能自己重绘tooltip 定位要手算屏幕坐标文字标签绘制成本高。适合热区密集、形状复杂的编辑器类产品用它做底层命中上层再套 Vue/React 组件。离屏 canvas 在这里还有一个用处就是做像素级透明度检测这点在后面的避坑章节会再展开。2.3 SVG 热区形状与样式都好控制SVG 用 polygon 或 path 描述热区天然复用 CSSsvg viewBox0 0 800 600 styleposition:absolute;left:0;top:0 !-- polygon 的 points 是 x1,y1 x2,y2 ... 格式 -- polygon points10,10 120,10 120,80 10,80 fillrgba(255,0,0,0.2) / text x20 y50主卧/text /svgviewBox 让 SVG 随容器缩放坐标逻辑最简单。事件监听直接绑在 polygon 上mouseenter、click 都是标准 DOM 行为。缺点是热区数量一多SVG 节点数跟着上去大范围地理图的几千个区片会让首屏渲染明显变慢。SVG 还有个隐含坑polygon 的 points 数据必须是闭合坐标转换接口生成时经常漏掉最后一个重复点位导致热区缺一条边。2.4 插件化封装的核心思路数据与渲染分离三种路径我都用过最后落地选插件方案判断标准很简单业务要维护的热区是否超过 20 个、是否要响应式、是否需要多次更新数据。任何一个条件成立就应该把热区抽象成“数据数组 渲染层 事件委托”的插件模型。坐标统一用原图自然像素引用渲染时乘以一个比例系数事件用委托绑定新增热区不改内部代码。市面上早期的图片热区插件大多绑定 jQuery在 React/Vue 项目里引入旧库很别扭。新项目更现实的做法是拆成数据层和渲染层自己维护一个几十行的轻量类这就是第 3 章要给出一套不依赖框架的最小实现的原因。选型要少掺玄学核心看热区数量和更新频率两条路走下来“图片热区 js 插件 数据驱动”是我最常用的组合。方案缩放适配hover 反馈Tooltip 成本热区节点量推荐场景原生 map/area手动计算几乎没有需自行封装低静态链接图Canvas重绘画布需自行重绘中很稳编辑器/密集热区SVGviewBox 自动天然支持低中偏高中量热区、标注JS 插件封装统一缩放函数事件委托实现低低业务中的功能模块3. 用插件跑通最小用例热区数据格式、初始化与事件回调选定插件化路线之后第一个落地步骤是确定数据格式。这块不往后想清楚后面加需求一定会翻车。3.1 热区数据协议坐标、形状、属性我一般会把热区定义成一个纯 JSON 数组独立于 DOM 结构存在[ { id: room-main, type: rect, coords: [10, 10, 120, 80], name: 主卧, extra: { price: 2800 } }, { id: room-kitchen, type: circle, coords: [200, 160, 30], name: 厨房 }, { id: room-balcony, type: polygon, coords: [400, 100, 480, 100, 480, 200, 400, 220], name: 阳台 } ]coords 的含义按 type 区分rect 是 [x1, y1, x2, y2]circle 是 [cx, cy, r]polygon 是依次排列的顶点坐标 [x1, y1, x2, y2, ...]。所有坐标都以图片的自然像素为基准显示尺寸变化不修改数据只改渲染层的比例系数。name 用来展示extra 可以放任何业务字段比如价格、跳转链接、状态标记。这个协议的好处在于后端可以直接下发热区数据前端只负责渲染不需要为每一张图维护一套页面逻辑。3.2 插件初始化流程等待图片加载再算比例核心流程分三步创建相对定位容器、插入图片、等图片加载后按显示尺寸计算缩放比例并绘制热区层。下面给出一个不依赖框架的最小实现类存成 image-hotspot.js 后通过普通 script 引入即可。class ImageHotspot { constructor(container, imageUrl, spots, options {}) { this.container typeof container string ? document.querySelector(container) : container; this.imageUrl imageUrl; this.spots spots; this.options Object.assign({ highlightColor: rgba(255, 200, 0, 0.25), onClick: null, onEnter: null, onLeave: null }, options); this.ratioX 1; this.ratioY 1; this._init(); } _init() { this.container.style.position relative; this.container.innerHTML ; this.img new Image(); this.img.src this.imageUrl; this.img.style.display block; this.img.style.width 100%; this.container.appendChild(this.img); this.layer document.createElement(div); this.layer.style.cssText position:absolute;inset:0;pointer-events:none;; this.container.appendChild(this.layer); // 图片可能已缓存complete 为 true 时直接渲染 if (this.img.complete) { this._render(); } else { this.img.addEventListener(load, () this._render()); } } _render() { this._calcRatio(); this.layer.innerHTML ; this.spots.forEach(spot { const target this._createTarget(spot); if (target) this.layer.appendChild(target); }); } _calcRatio() { const rect this.img.getBoundingClientRect(); this.ratioX rect.width / this.img.naturalWidth; this.ratioY rect.height / this.img.naturalHeight; } _createTarget(spot) { // rect 和 circle 的实现polygon 见第 4 章 if (spot.type ! rect spot.type ! circle) return null; const el document.createElement(div); el.className hotspot-target; el.dataset.id spot.id; let style position:absolute;pointer-events:auto;cursor:pointer;; if (spot.type rect) { const x spot.coords[0] * this.ratioX; const y spot.coords[1] * this.ratioY; const w (spot.coords[2] - spot.coords[0]) * this.ratioX; const h (spot.coords[3] - spot.coords[1]) * this.ratioY; style left:${x}px;top:${y}px;width:${w}px;height:${h}px;; } else if (spot.type circle) { const cx spot.coords[0] * this.ratioX; const cy spot.coords[1] * this.ratioY; // 半径用两个比例中较小值避免椭圆 const r spot.coords[2] * Math.min(this.ratioX, this.ratioY); style left:${cx - r}px;top:${cy - r}px;width:${r * 2}px;height:${r * 2}px;border-radius:50%;; } style background:${this.options.highlightColor};; el.style.cssText style; el.addEventListener(click, e { if (typeof this.options.onClick function) { this.options.onClick.call(this, spot, e); } }); el.addEventListener(mouseenter, () { if (typeof this.options.onEnter function) { this.options.onEnter(spot); } }); el.addEventListener(mouseleave, () { if (typeof this.options.onLeave function) { this.options.onLeave(spot); } }); return el; } setData(spots) { this.spots spots; this._render(); } destroy() { this.container.innerHTML ; } }逻辑顺序是这样的_init先构造容器结构图片插在底层热区层用 absolute 覆盖上去pointer-events:none让热区层默认不拦截图片事件具体热区节点再设回pointer-events:auto。_calcRatio根据图片的自然像素和实际渲染尺寸算出两个方向的缩放比例_createTarget再把 coords 换算成屏幕像素并生成一个可点击的覆盖层。关键的是img.complete判断图片已经命中缓存时load 事件不会再触发只等load会造成热区一直不渲染。参数说明container 支持选择器字符串或 DOM 对象imageUrl 是图片地址spots 是上文定义的热区数组options 里的 onClick、onEnter、onLeave 分别对应点击、移入、移出三个生命周期回调回调第一个参数是完整的热区数据对象第二个参数才是原始 event 对象。highlightColor 控制默认填充色实际业务里可以再加 strokeColor、opacity 等配置。3.3 一个能跑的调用示例点房间名显示详情把类落地到页面里逻辑很短div idmapBox stylewidth:600px;max-width:100%/div div idtip styleheight:2em/div// 初始化热区插件并绑定展示回调 const spots [ { id: r1, type: rect, coords: [10, 10, 120, 80], name: 主卧, extra: { price: 2800 } }, { id: r2, type: circle, coords: [200, 160, 30], name: 厨房 } ]; const hotspot new ImageHotspot(#mapBox, ./floor.png, spots, { highlightColor: rgba(0, 150, 255, 0.2), onClick(spot) { document.querySelector(#tip).textContent ${spot.name}月租 ${spot.extra.price ?? -} 元; }, onEnter(spot) { document.querySelector(#tip).textContent 当前指向${spot.name}; } });这段代码演示了最典型的落地场景用户鼠标移到房间上页面顶部文字实时更新房间名点下去之后再把价格等业务信息渲染出来。coords 数据直接写在数组里因此从接口拿热区配置变成很自然的事比如改成 fetch 拉取数据后调用setData渲染即可。4. 五个必调参数与响应式适配让热区在移动端不偏移上线时最容易被吐槽的就是手机端热区全歪。这章把参数和缩放细节一次讲清楚照着调基本能避开绝大多数问题。4.1 窗口缩放时热区跟随resize 与比例重算前面最小实现里比例只在图片加载时算一次。浏览器窗口变化导致图片显示宽度变化后热区还停在旧位置这种“桌面正常、手机串位”的现象是热区插件最常见的翻车现场。解决办法是监听 resize 并重算// 容器尺寸变化后强制重绘热区 window.addEventListener(resize, () { hotspot._render(); });如果插件内部管理生命周期更合适的做法是把 resize 逻辑收进插件让每个实例自己监听和销毁避免页面里有多个热图时重复触发。重算的代价只是重新生成几个 div性能几乎没有压力。但 resize 事件触发非常频繁拖拽浏览器边框时会连续触发几十次需要加防抖let timer; window.addEventListener(resize, () { clearTimeout(timer); timer setTimeout(() hotspot._render(), 150); });这里 150ms 是经验值太短没起到截流作用太长会明显感觉热区更新慢半拍。4.2 形状类型与坐标细节rect/circle/polygon 的边界rect 的 coords 是左上角和右下角正着写没问题反着写x1 x2会让宽度为负热区直接消失建议进入渲染前做一次排序// 对矩形坐标排序避免宽度或高度为负 const [x1, y1, x2, y2] spot.coords; const left Math.min(x1, x2); const top Math.min(y1, y2); const width Math.abs(x2 - x1); const height Math.abs(y2 - y1);polygon 的坐标换算我单独处理因为最小实现类里没有覆盖。常见的渲染方式是补一个全尺寸 SVG 层把polygon元素放进去事件直接绑在 polygon 上_createPolygonTarget(spot) { const svg document.createElementNS(http://www.w3.org/2000/svg, svg); svg.style.cssText position:absolute;left:0;top:0;width:100%;height:100%;; const poly document.createElementNS(http://www.w3.org/2000/svg, polygon); const scaled []; for (let i 0; i spot.coords.length; i 2) { scaled.push(${spot.coords[i] * this.ratioX},${spot.coords[i 1] * this.ratioY}); } poly.setAttribute(points, scaled.join( )); poly.setAttribute(fill, this.options.highlightColor); svg.appendChild(poly); svg.addEventListener(click, e { if (this.options.onClick) this.options.onClick(spot, e); }); return svg; }polygon 数据常见坑是坐标没闭合。有的后端生成数据时只会给出不重复顶点渲染出的多边形边界少一条边命中区域变小。数据清洗时补上闭合const points spot.coords.slice(); if (points[0] ! points[points.length - 2] || points[1] ! points[points.length - 1]) { points.push(points[0], points[1]); }circle 半径换算要单独注意图片宽高比不是 1:1 时直接用 displayWidth / naturalWidth 去乘半径圆会变成椭圆。用Math.min(ratioX, ratioY)是保形做法牺牲一点位置精度保证图形不变形。4.3 高亮样式与 tooltip 气泡用 CSS 类替代内联样式前面代码用内联样式直接写背景到了项目里会很难维护。更合理的做法是让热区层挂一个固定 class样式全交给 CSS.hotspot-target { border: 2px solid rgba(255, 255, 255, 0.8); box-sizing: border-box; border-radius: 4px; transition: background-color 0.2s; } .hotspot-target:hover { background-color: rgba(255, 200, 0, 0.3) !important; }CSS 类的意义在于热区的视觉表达和业务渲染彻底分离后续调整描边、圆角、透明过渡都不需要重新发布插件代码。tooltip 同样用容器加绝对定位实现回调里已经能通过getBoundingClientRect拿到热区屏幕坐标onEnter(spot) { const rect this.layer.querySelector([data-id${spot.id}]).getBoundingClientRect(); tooltip.style.left ${rect.left rect.width / 2}px; tooltip.style.top ${rect.top - 8}px; tooltip.textContent spot.name; tooltip.classList.add(visible); }这里定位用的是视口坐标如果容器外层有滚动或 transform需要在页面根节点上做一次坐标换算否则 tooltip 会偏移。带 transform 的容器会改变 getBoundingClientRect 的参考系这类问题在弹窗内嵌图片热区时最容易出现。4.4 事件回调里的 event 对象stopPropagation 与冒泡控制热区层覆盖在图片上方点击事件会冒泡到容器如果容器上挂的是整图点击统计就会重复计数。回调里第二个参数是原始 event 对象可以用它做事件控制onClick(spot, e) { // 阻止事件继续冒泡到容器和页面 e.stopPropagation(); e.preventDefault(); // 后续业务逻辑如打开详情弹窗 showDetail(spot); }stopPropagation 阻止冒泡到父级preventDefault 处理带a链接的默认跳转。这个细节在最开始写插件时容易漏等产品反馈“每次点热区还激活了底图按钮”再回去补就要改一批历史页面。事件委托模式下原生的e.target会被矫正成当前命中的热区节点回调里的 spot 参数才是真正的目标数据源。4.5 数据更新与重绘setData 的两种增量策略接口重新拉取热区数据后setData 需要支持两种重绘策略。简单场景直接用innerHTML 全量重建热区几十个时性能没有差异但如果热区上千全量重建会导致交互卡顿改成只对变化的 id 做局部更新setData(spots) { const newIds new Set(spots.map(s s.id)); // 移除已经不存在的热区节点 this.layer.querySelectorAll(.hotspot-target, svg).forEach(el { if (!newIds.has(el.dataset.id)) el.remove(); }); // 只新增当前缺失的节点 spots.forEach(spot { if (!this.layer.querySelector([data-id${spot.id}])) { this.layer.appendChild(this._createTarget(spot)); } }); this.spots spots; }局部更新的前提是热区必须有稳定 id且坐标渲染不依赖其他热区的计算结果。我遇到过一个需求是热区之间有联动比如选中 A 后 B 要变色那种场景不能只增量画节点还得配合状态管理一起重绘否则联动状态会错乱。5. 图片热区 js 插件常见问题与避坑记录5 条实战踩坑以下问题都是我在项目里真实遇到过的按照“现象 → 原因 → 解决”记录每一条都能对照排查。5.1 坑点 1图片还没加载完就初始化热区全部堆在左上角现象页面刷新第一次打开时热区全部叠在图片左上角刷新第二次又正常。 原因页面脚本在图片加载完成前执行了插件初始化_calcRatio拿到的 naturalWidth 是 0比例算出异常坐标全部错乱。 解决让初始化链路挂到图片 load 之后。如果插件没有内部等待逻辑用脚本侧判断图片 complete 再初始化// 先加载图片加载完成后再初始化插件 const img new Image(); img.src ./floor.png; if (img.complete) { initHotspot(); } else { img.addEventListener(load, initHotspot); }提示图片容器的 CSS 里务必保持width:100%;height:auto图片一旦被拉伸所有基于 naturalWidth 的比例计算都会偏离。5.2 坑点 2src 换了但热区层还在渲染旧图数据现象一个容器先加载户型 A再切换成户型 B热区显示的还是 A 的坐标。 原因容器内旧图片和旧热区层没有被清空新增的图片 append 到后面覆盖关系错乱。 解决每次切换前调用destroy把container.innerHTML清掉再重新走初始化流程。另外确认 destroy 里把 window resize 监听也解绑否则上一个实例的 resize 回调还在持续重绘会报空引用错误。function switchFloor(url, spots) { // 切换前先销毁旧实例避免热区层残留 hotspot.destroy(); hotspot new ImageHotspot(#mapBox, url, spots, options); }5.3 坑点 3移动端热区偏移几个像素多边形变形明显现象桌面端正常手机上热区整体偏右下圆角区域尤其明显。 原因只用一个 ratio 去缩放宽度和高度。移动端容器宽高比和桌面端不一致宽和高的缩放比例必须分开计算另外 resize 防抖没做横竖屏切换时热区没有及时重算。 解决用 ratioX、ratioY 分别参与坐标换算并在 resize 事件里重绘。#mapBox img { display: block; width: 100%; height: auto; }5.4 坑点 4动态追加热区后点击事件全部失效现象调 setData 追加新热区新热区点击没反应旧热区正常。 原因事件绑定是在_createTarget里逐个 addEventListener 的局部更新时如果直接复用缓存 DOM 节点事件函数引用会丢失全量 innerHTML 重建后新节点也没有重新绑定事件。 解决不要手工缓存 DOM 节点做局部追加利用事件委托把点击监听挂到 layer 上统一分发// 事件委托热区节点的事件统一由 layer 层处理 this.layer.addEventListener(click, e { const target e.target.closest(.hotspot-target, polygon); if (!target) return; const id target.dataset.id; const spot this.spots.find(s s.id id); if (spot this.options.onClick) this.options.onClick(spot, e); });事件委托之后无论热区节点是新建还是复用事件都统一走委托省去反复绑定。这也是插件化方案相比手写 addEventListener 的核心优势之一。5.5 坑点 5透明 PNG 的空白区域也会命中热区现象图片是透明背景的商品图用户点击空白处居然触发了热区。 原因热区本质是几何多边形不感知像素透明度。只要坐标范围内落点就会触发事件。 解决方案分两层。轻量做法是让 shape 尽量贴合实际商品轮廓缩小 rect 与视觉偏差重度做法是在点击命中后再做一次像素级 alpha 检测用离屏 canvas 把图片画上去取点击坐标的 alpha 值判断// 判断点击位置是否透明scaleX/scaleY 为屏幕坐标到自然像素的换算系数 function isTransparent(img, x, y, scaleX, scaleY) { const canvas document.createElement(canvas); canvas.width img.naturalWidth; canvas.height img.naturalHeight; const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); const px Math.round(x * scaleX); const py Math.round(y * scaleY); return ctx.getImageData(px, py, 1, 1).data[3] 8; }这个损耗只在点击瞬间发生热区数量不大时可以接受。不过它依赖图片同源策略跨域图片getImageData会抛安全异常需要提前给图片设置 crossOrigin 且服务端返回对应响应头。6. 进阶技巧用 Canvas 辅助生成热区坐标与无障碍键盘支持前面几章讲的是消费热区数据这章补充两个生产端常用的技巧怎么快速得到一份可用坐标数据以及怎么让热区对键盘用户也可访问。6.1 用点击记录生成坐标从设计稿到数据数组没有后端下发数据时我习惯用一段临时页面直接点出来的坐标作为初始数据。核心思路是用 canvas 覆盖图片监听 click把鼠标坐标换算成原图自然像素并输出 JSON// 点击画布将屏幕坐标换算为原图自然像素坐标 canvas.addEventListener(click, e { const rect canvas.getBoundingClientRect(); const x (e.clientX - rect.left) * (img.naturalWidth / rect.width); const y (e.clientY - rect.top) * (img.naturalHeight / rect.height); points.push(Math.round(x), Math.round(y)); console.log(JSON.stringify(points)); });矩形按两个点记录多边形按多个点记录点击完复制控制台输出即可生成数据。这个小页面我保留在项目工具目录里每来新图都能用比手动去 PS 里量像素坐标快出一个数量级。6.2 无障碍支持tabindex、aria-label 与回车触发热区如果是可交互的必须考虑键盘用户。div 默认不可聚焦给热区节点加tabindex0和aria-label再监听 keydown 里的 Enter 执行同样的点击逻辑// 让热区节点可被键盘聚焦并支持回车触发点击 el.setAttribute(tabindex, 0); el.setAttribute(role, button); el.setAttribute(aria-label, spot.name || 图片热区); el.addEventListener(keydown, e { if (e.key Enter) el.click(); });这里有一个易忽略点热区节点如果互相挨得很近tab 顺序可能混乱需要在数据协议里加 order 字段按 order 给 DOM 排序保证 Tab 顺序与视觉顺序一致。6.3 一套工程化习惯坐标数据独立成 JSON最后一个建议是把热区数据从页面代码里拆出来独立成 JSON 文件或单独模块。这样设计稿变更只改数据不动插件和样式。我在项目里维护过一个包含 300 多个户型热区的数据文件配合局部更新策略热区在移动端和桌面端的体验保持一致靠的就是把数据与渲染彻底分离。这些做法谈不上多复杂但确实让后来接手的人少走了很多弯路希望帮到你。本文还有配套的精品资源点击获取 图片热区js插件实战：实现坐标数据、响应式交互与事件委托
简介图片热区是网页交互中的常见技术通过在一张图上划分自定义区域并绑定链接或事件可以创造出丰富的互动体验。这份“图片热区js插件”正是面向前端开发者和网页设计师的轻量级jQuery工具解决了手工编写坐标映射代码耗时且难以维护的问题适用于在线地图、产品展示、交互式教学等场景。资源压缩包共8个文件以两个js文件为核心包含插件主体与jQuery依赖另配有css样式、html演示页、png图像素材、xml工程配置以及md说明文档整体仅约209KB结构精简便于直接引入或扩展。目前已有2271人学习下载。功能上插件支持自由绘制矩形、圆形等热区可精确调整位置与尺寸每个热区均可绑定独立URL同时与IntelliJ IDEA等IDE良好集成便于在编码环境中实时预览。源码注释丰富目录组织清晰包含了可直接运行的demo能帮助开发者快速掌握图片热区的实现思路并在此基础上定制个性化交互逻辑有效提升页面开发效率。1. 图片热区 js 插件把图片划分成可交互区域到底解决了什么图片热区image hotspot / image map是前端交互里出现频率很高的老需求户型图按房间选房、电商主图标注每个卖点位置、室内全景划分家具区域、医学影像标记病灶。登录过任何选房平台或在线工具几乎都会碰到它。原生 HTML 的map/area能画矩形、圆和多边形但交互能力非常弱——没有默认高亮、没有缩放适配、多图切换要手动刷新。图片热区 js 插件要做的就是把坐标数据、渲染层、事件回调、响应式缩放统一封装起来让同一套热区配置同时跑在桌面端和移动端。我在这里把选型、数据格式、最小可运行实现和踩坑记录完整讲一遍适合正在做图片标注类功能的前端开发以及被areacoords 维护折腾过的产品前端。2. 三种图片热区实现路径与选型逻辑为什么插件值得引入图片热区不是单一技术而是“数据 渲染 交互”的组合体。给自己做方案前先把原生 map、Canvas、SVG 三条路走一遍看清各自边界才能判断插件值不值得写或引入。2.1 原生/结构简单但交互回天乏术原生方式就是把映射关系直接写进 HTMLimg srcfloor.png usemap#floorMap alt户型图 / map namefloorMap area shaperect coords10,10,120,80 href#room-main alt主卧 / area shapecircle coords200,160,30 href#room-kitchen alt厨房 / /maparea 的 coords 是相对原图自然像素的坐标浏览器在图片显示尺寸变化时不会自动换算必须在脚本里手动改。shape 只有 rect、circle、poly 三种高亮、悬浮样式都没有缺省行为tooltip 要自己再套一层 DOM。如果业务只有一张静态图、几个链接跳转原生方案够用但只要涉及响应式、动态增删热区、点击反馈调试成本立刻上升。实际开发里我在响应式布局下做过一次原生 area 的缩放换算代码是这样的img.addEventListener(load, () { const rect img.getBoundingClientRect(); const ratio rect.width / img.naturalWidth; const realCoords area.getAttribute(coords) .split(,) .map(v Math.round(parseFloat(v) * ratio)); area.setAttribute(coords, realCoords.join(,)); });这段逻辑每次 window resize 都要重跑一遍多张图、多块 area 时就会陷入重复劳动而且 polygon 的每个顶点都要乘比例漏一个点热区就错一位。很多老项目就是用这种方式撑下来的代码又长又脆。2.2 Canvas 命中检测热区多时性能最稳Canvas 方案的做法是用 isPointInPath 做屏幕坐标命中检测热区本身不是 DOM 节点// 判断点是否落在某个矩形热区内 const hitRect (ctx, x, y, r) { ctx.beginPath(); ctx.rect(r.x, r.y, r.width, r.height); return ctx.isPointInPath(x, y); };每次鼠标移动都遍历所有热区几何体做命中测试热区数量到几百个时性能仍然稳定因为不涉及 DOM 创建。痛点也很明确热区没有实体节点hover 反馈只能自己重绘tooltip 定位要手算屏幕坐标文字标签绘制成本高。适合热区密集、形状复杂的编辑器类产品用它做底层命中上层再套 Vue/React 组件。离屏 canvas 在这里还有一个用处就是做像素级透明度检测这点在后面的避坑章节会再展开。2.3 SVG 热区形状与样式都好控制SVG 用 polygon 或 path 描述热区天然复用 CSSsvg viewBox0 0 800 600 styleposition:absolute;left:0;top:0 !-- polygon 的 points 是 x1,y1 x2,y2 ... 格式 -- polygon points10,10 120,10 120,80 10,80 fillrgba(255,0,0,0.2) / text x20 y50主卧/text /svgviewBox 让 SVG 随容器缩放坐标逻辑最简单。事件监听直接绑在 polygon 上mouseenter、click 都是标准 DOM 行为。缺点是热区数量一多SVG 节点数跟着上去大范围地理图的几千个区片会让首屏渲染明显变慢。SVG 还有个隐含坑polygon 的 points 数据必须是闭合坐标转换接口生成时经常漏掉最后一个重复点位导致热区缺一条边。2.4 插件化封装的核心思路数据与渲染分离三种路径我都用过最后落地选插件方案判断标准很简单业务要维护的热区是否超过 20 个、是否要响应式、是否需要多次更新数据。任何一个条件成立就应该把热区抽象成“数据数组 渲染层 事件委托”的插件模型。坐标统一用原图自然像素引用渲染时乘以一个比例系数事件用委托绑定新增热区不改内部代码。市面上早期的图片热区插件大多绑定 jQuery在 React/Vue 项目里引入旧库很别扭。新项目更现实的做法是拆成数据层和渲染层自己维护一个几十行的轻量类这就是第 3 章要给出一套不依赖框架的最小实现的原因。选型要少掺玄学核心看热区数量和更新频率两条路走下来“图片热区 js 插件 数据驱动”是我最常用的组合。方案缩放适配hover 反馈Tooltip 成本热区节点量推荐场景原生 map/area手动计算几乎没有需自行封装低静态链接图Canvas重绘画布需自行重绘中很稳编辑器/密集热区SVGviewBox 自动天然支持低中偏高中量热区、标注JS 插件封装统一缩放函数事件委托实现低低业务中的功能模块3. 用插件跑通最小用例热区数据格式、初始化与事件回调选定插件化路线之后第一个落地步骤是确定数据格式。这块不往后想清楚后面加需求一定会翻车。3.1 热区数据协议坐标、形状、属性我一般会把热区定义成一个纯 JSON 数组独立于 DOM 结构存在[ { id: room-main, type: rect, coords: [10, 10, 120, 80], name: 主卧, extra: { price: 2800 } }, { id: room-kitchen, type: circle, coords: [200, 160, 30], name: 厨房 }, { id: room-balcony, type: polygon, coords: [400, 100, 480, 100, 480, 200, 400, 220], name: 阳台 } ]coords 的含义按 type 区分rect 是 [x1, y1, x2, y2]circle 是 [cx, cy, r]polygon 是依次排列的顶点坐标 [x1, y1, x2, y2, ...]。所有坐标都以图片的自然像素为基准显示尺寸变化不修改数据只改渲染层的比例系数。name 用来展示extra 可以放任何业务字段比如价格、跳转链接、状态标记。这个协议的好处在于后端可以直接下发热区数据前端只负责渲染不需要为每一张图维护一套页面逻辑。3.2 插件初始化流程等待图片加载再算比例核心流程分三步创建相对定位容器、插入图片、等图片加载后按显示尺寸计算缩放比例并绘制热区层。下面给出一个不依赖框架的最小实现类存成 image-hotspot.js 后通过普通 script 引入即可。class ImageHotspot { constructor(container, imageUrl, spots, options {}) { this.container typeof container string ? document.querySelector(container) : container; this.imageUrl imageUrl; this.spots spots; this.options Object.assign({ highlightColor: rgba(255, 200, 0, 0.25), onClick: null, onEnter: null, onLeave: null }, options); this.ratioX 1; this.ratioY 1; this._init(); } _init() { this.container.style.position relative; this.container.innerHTML ; this.img new Image(); this.img.src this.imageUrl; this.img.style.display block; this.img.style.width 100%; this.container.appendChild(this.img); this.layer document.createElement(div); this.layer.style.cssText position:absolute;inset:0;pointer-events:none;; this.container.appendChild(this.layer); // 图片可能已缓存complete 为 true 时直接渲染 if (this.img.complete) { this._render(); } else { this.img.addEventListener(load, () this._render()); } } _render() { this._calcRatio(); this.layer.innerHTML ; this.spots.forEach(spot { const target this._createTarget(spot); if (target) this.layer.appendChild(target); }); } _calcRatio() { const rect this.img.getBoundingClientRect(); this.ratioX rect.width / this.img.naturalWidth; this.ratioY rect.height / this.img.naturalHeight; } _createTarget(spot) { // rect 和 circle 的实现polygon 见第 4 章 if (spot.type ! rect spot.type ! circle) return null; const el document.createElement(div); el.className hotspot-target; el.dataset.id spot.id; let style position:absolute;pointer-events:auto;cursor:pointer;; if (spot.type rect) { const x spot.coords[0] * this.ratioX; const y spot.coords[1] * this.ratioY; const w (spot.coords[2] - spot.coords[0]) * this.ratioX; const h (spot.coords[3] - spot.coords[1]) * this.ratioY; style left:${x}px;top:${y}px;width:${w}px;height:${h}px;; } else if (spot.type circle) { const cx spot.coords[0] * this.ratioX; const cy spot.coords[1] * this.ratioY; // 半径用两个比例中较小值避免椭圆 const r spot.coords[2] * Math.min(this.ratioX, this.ratioY); style left:${cx - r}px;top:${cy - r}px;width:${r * 2}px;height:${r * 2}px;border-radius:50%;; } style background:${this.options.highlightColor};; el.style.cssText style; el.addEventListener(click, e { if (typeof this.options.onClick function) { this.options.onClick.call(this, spot, e); } }); el.addEventListener(mouseenter, () { if (typeof this.options.onEnter function) { this.options.onEnter(spot); } }); el.addEventListener(mouseleave, () { if (typeof this.options.onLeave function) { this.options.onLeave(spot); } }); return el; } setData(spots) { this.spots spots; this._render(); } destroy() { this.container.innerHTML ; } }逻辑顺序是这样的_init先构造容器结构图片插在底层热区层用 absolute 覆盖上去pointer-events:none让热区层默认不拦截图片事件具体热区节点再设回pointer-events:auto。_calcRatio根据图片的自然像素和实际渲染尺寸算出两个方向的缩放比例_createTarget再把 coords 换算成屏幕像素并生成一个可点击的覆盖层。关键的是img.complete判断图片已经命中缓存时load 事件不会再触发只等load会造成热区一直不渲染。参数说明container 支持选择器字符串或 DOM 对象imageUrl 是图片地址spots 是上文定义的热区数组options 里的 onClick、onEnter、onLeave 分别对应点击、移入、移出三个生命周期回调回调第一个参数是完整的热区数据对象第二个参数才是原始 event 对象。highlightColor 控制默认填充色实际业务里可以再加 strokeColor、opacity 等配置。3.3 一个能跑的调用示例点房间名显示详情把类落地到页面里逻辑很短div idmapBox stylewidth:600px;max-width:100%/div div idtip styleheight:2em/div// 初始化热区插件并绑定展示回调 const spots [ { id: r1, type: rect, coords: [10, 10, 120, 80], name: 主卧, extra: { price: 2800 } }, { id: r2, type: circle, coords: [200, 160, 30], name: 厨房 } ]; const hotspot new ImageHotspot(#mapBox, ./floor.png, spots, { highlightColor: rgba(0, 150, 255, 0.2), onClick(spot) { document.querySelector(#tip).textContent ${spot.name}月租 ${spot.extra.price ?? -} 元; }, onEnter(spot) { document.querySelector(#tip).textContent 当前指向${spot.name}; } });这段代码演示了最典型的落地场景用户鼠标移到房间上页面顶部文字实时更新房间名点下去之后再把价格等业务信息渲染出来。coords 数据直接写在数组里因此从接口拿热区配置变成很自然的事比如改成 fetch 拉取数据后调用setData渲染即可。4. 五个必调参数与响应式适配让热区在移动端不偏移上线时最容易被吐槽的就是手机端热区全歪。这章把参数和缩放细节一次讲清楚照着调基本能避开绝大多数问题。4.1 窗口缩放时热区跟随resize 与比例重算前面最小实现里比例只在图片加载时算一次。浏览器窗口变化导致图片显示宽度变化后热区还停在旧位置这种“桌面正常、手机串位”的现象是热区插件最常见的翻车现场。解决办法是监听 resize 并重算// 容器尺寸变化后强制重绘热区 window.addEventListener(resize, () { hotspot._render(); });如果插件内部管理生命周期更合适的做法是把 resize 逻辑收进插件让每个实例自己监听和销毁避免页面里有多个热图时重复触发。重算的代价只是重新生成几个 div性能几乎没有压力。但 resize 事件触发非常频繁拖拽浏览器边框时会连续触发几十次需要加防抖let timer; window.addEventListener(resize, () { clearTimeout(timer); timer setTimeout(() hotspot._render(), 150); });这里 150ms 是经验值太短没起到截流作用太长会明显感觉热区更新慢半拍。4.2 形状类型与坐标细节rect/circle/polygon 的边界rect 的 coords 是左上角和右下角正着写没问题反着写x1 x2会让宽度为负热区直接消失建议进入渲染前做一次排序// 对矩形坐标排序避免宽度或高度为负 const [x1, y1, x2, y2] spot.coords; const left Math.min(x1, x2); const top Math.min(y1, y2); const width Math.abs(x2 - x1); const height Math.abs(y2 - y1);polygon 的坐标换算我单独处理因为最小实现类里没有覆盖。常见的渲染方式是补一个全尺寸 SVG 层把polygon元素放进去事件直接绑在 polygon 上_createPolygonTarget(spot) { const svg document.createElementNS(http://www.w3.org/2000/svg, svg); svg.style.cssText position:absolute;left:0;top:0;width:100%;height:100%;; const poly document.createElementNS(http://www.w3.org/2000/svg, polygon); const scaled []; for (let i 0; i spot.coords.length; i 2) { scaled.push(${spot.coords[i] * this.ratioX},${spot.coords[i 1] * this.ratioY}); } poly.setAttribute(points, scaled.join( )); poly.setAttribute(fill, this.options.highlightColor); svg.appendChild(poly); svg.addEventListener(click, e { if (this.options.onClick) this.options.onClick(spot, e); }); return svg; }polygon 数据常见坑是坐标没闭合。有的后端生成数据时只会给出不重复顶点渲染出的多边形边界少一条边命中区域变小。数据清洗时补上闭合const points spot.coords.slice(); if (points[0] ! points[points.length - 2] || points[1] ! points[points.length - 1]) { points.push(points[0], points[1]); }circle 半径换算要单独注意图片宽高比不是 1:1 时直接用 displayWidth / naturalWidth 去乘半径圆会变成椭圆。用Math.min(ratioX, ratioY)是保形做法牺牲一点位置精度保证图形不变形。4.3 高亮样式与 tooltip 气泡用 CSS 类替代内联样式前面代码用内联样式直接写背景到了项目里会很难维护。更合理的做法是让热区层挂一个固定 class样式全交给 CSS.hotspot-target { border: 2px solid rgba(255, 255, 255, 0.8); box-sizing: border-box; border-radius: 4px; transition: background-color 0.2s; } .hotspot-target:hover { background-color: rgba(255, 200, 0, 0.3) !important; }CSS 类的意义在于热区的视觉表达和业务渲染彻底分离后续调整描边、圆角、透明过渡都不需要重新发布插件代码。tooltip 同样用容器加绝对定位实现回调里已经能通过getBoundingClientRect拿到热区屏幕坐标onEnter(spot) { const rect this.layer.querySelector([data-id${spot.id}]).getBoundingClientRect(); tooltip.style.left ${rect.left rect.width / 2}px; tooltip.style.top ${rect.top - 8}px; tooltip.textContent spot.name; tooltip.classList.add(visible); }这里定位用的是视口坐标如果容器外层有滚动或 transform需要在页面根节点上做一次坐标换算否则 tooltip 会偏移。带 transform 的容器会改变 getBoundingClientRect 的参考系这类问题在弹窗内嵌图片热区时最容易出现。4.4 事件回调里的 event 对象stopPropagation 与冒泡控制热区层覆盖在图片上方点击事件会冒泡到容器如果容器上挂的是整图点击统计就会重复计数。回调里第二个参数是原始 event 对象可以用它做事件控制onClick(spot, e) { // 阻止事件继续冒泡到容器和页面 e.stopPropagation(); e.preventDefault(); // 后续业务逻辑如打开详情弹窗 showDetail(spot); }stopPropagation 阻止冒泡到父级preventDefault 处理带a链接的默认跳转。这个细节在最开始写插件时容易漏等产品反馈“每次点热区还激活了底图按钮”再回去补就要改一批历史页面。事件委托模式下原生的e.target会被矫正成当前命中的热区节点回调里的 spot 参数才是真正的目标数据源。4.5 数据更新与重绘setData 的两种增量策略接口重新拉取热区数据后setData 需要支持两种重绘策略。简单场景直接用innerHTML 全量重建热区几十个时性能没有差异但如果热区上千全量重建会导致交互卡顿改成只对变化的 id 做局部更新setData(spots) { const newIds new Set(spots.map(s s.id)); // 移除已经不存在的热区节点 this.layer.querySelectorAll(.hotspot-target, svg).forEach(el { if (!newIds.has(el.dataset.id)) el.remove(); }); // 只新增当前缺失的节点 spots.forEach(spot { if (!this.layer.querySelector([data-id${spot.id}])) { this.layer.appendChild(this._createTarget(spot)); } }); this.spots spots; }局部更新的前提是热区必须有稳定 id且坐标渲染不依赖其他热区的计算结果。我遇到过一个需求是热区之间有联动比如选中 A 后 B 要变色那种场景不能只增量画节点还得配合状态管理一起重绘否则联动状态会错乱。5. 图片热区 js 插件常见问题与避坑记录5 条实战踩坑以下问题都是我在项目里真实遇到过的按照“现象 → 原因 → 解决”记录每一条都能对照排查。5.1 坑点 1图片还没加载完就初始化热区全部堆在左上角现象页面刷新第一次打开时热区全部叠在图片左上角刷新第二次又正常。 原因页面脚本在图片加载完成前执行了插件初始化_calcRatio拿到的 naturalWidth 是 0比例算出异常坐标全部错乱。 解决让初始化链路挂到图片 load 之后。如果插件没有内部等待逻辑用脚本侧判断图片 complete 再初始化// 先加载图片加载完成后再初始化插件 const img new Image(); img.src ./floor.png; if (img.complete) { initHotspot(); } else { img.addEventListener(load, initHotspot); }提示图片容器的 CSS 里务必保持width:100%;height:auto图片一旦被拉伸所有基于 naturalWidth 的比例计算都会偏离。5.2 坑点 2src 换了但热区层还在渲染旧图数据现象一个容器先加载户型 A再切换成户型 B热区显示的还是 A 的坐标。 原因容器内旧图片和旧热区层没有被清空新增的图片 append 到后面覆盖关系错乱。 解决每次切换前调用destroy把container.innerHTML清掉再重新走初始化流程。另外确认 destroy 里把 window resize 监听也解绑否则上一个实例的 resize 回调还在持续重绘会报空引用错误。function switchFloor(url, spots) { // 切换前先销毁旧实例避免热区层残留 hotspot.destroy(); hotspot new ImageHotspot(#mapBox, url, spots, options); }5.3 坑点 3移动端热区偏移几个像素多边形变形明显现象桌面端正常手机上热区整体偏右下圆角区域尤其明显。 原因只用一个 ratio 去缩放宽度和高度。移动端容器宽高比和桌面端不一致宽和高的缩放比例必须分开计算另外 resize 防抖没做横竖屏切换时热区没有及时重算。 解决用 ratioX、ratioY 分别参与坐标换算并在 resize 事件里重绘。#mapBox img { display: block; width: 100%; height: auto; }5.4 坑点 4动态追加热区后点击事件全部失效现象调 setData 追加新热区新热区点击没反应旧热区正常。 原因事件绑定是在_createTarget里逐个 addEventListener 的局部更新时如果直接复用缓存 DOM 节点事件函数引用会丢失全量 innerHTML 重建后新节点也没有重新绑定事件。 解决不要手工缓存 DOM 节点做局部追加利用事件委托把点击监听挂到 layer 上统一分发// 事件委托热区节点的事件统一由 layer 层处理 this.layer.addEventListener(click, e { const target e.target.closest(.hotspot-target, polygon); if (!target) return; const id target.dataset.id; const spot this.spots.find(s s.id id); if (spot this.options.onClick) this.options.onClick(spot, e); });事件委托之后无论热区节点是新建还是复用事件都统一走委托省去反复绑定。这也是插件化方案相比手写 addEventListener 的核心优势之一。5.5 坑点 5透明 PNG 的空白区域也会命中热区现象图片是透明背景的商品图用户点击空白处居然触发了热区。 原因热区本质是几何多边形不感知像素透明度。只要坐标范围内落点就会触发事件。 解决方案分两层。轻量做法是让 shape 尽量贴合实际商品轮廓缩小 rect 与视觉偏差重度做法是在点击命中后再做一次像素级 alpha 检测用离屏 canvas 把图片画上去取点击坐标的 alpha 值判断// 判断点击位置是否透明scaleX/scaleY 为屏幕坐标到自然像素的换算系数 function isTransparent(img, x, y, scaleX, scaleY) { const canvas document.createElement(canvas); canvas.width img.naturalWidth; canvas.height img.naturalHeight; const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); const px Math.round(x * scaleX); const py Math.round(y * scaleY); return ctx.getImageData(px, py, 1, 1).data[3] 8; }这个损耗只在点击瞬间发生热区数量不大时可以接受。不过它依赖图片同源策略跨域图片getImageData会抛安全异常需要提前给图片设置 crossOrigin 且服务端返回对应响应头。6. 进阶技巧用 Canvas 辅助生成热区坐标与无障碍键盘支持前面几章讲的是消费热区数据这章补充两个生产端常用的技巧怎么快速得到一份可用坐标数据以及怎么让热区对键盘用户也可访问。6.1 用点击记录生成坐标从设计稿到数据数组没有后端下发数据时我习惯用一段临时页面直接点出来的坐标作为初始数据。核心思路是用 canvas 覆盖图片监听 click把鼠标坐标换算成原图自然像素并输出 JSON// 点击画布将屏幕坐标换算为原图自然像素坐标 canvas.addEventListener(click, e { const rect canvas.getBoundingClientRect(); const x (e.clientX - rect.left) * (img.naturalWidth / rect.width); const y (e.clientY - rect.top) * (img.naturalHeight / rect.height); points.push(Math.round(x), Math.round(y)); console.log(JSON.stringify(points)); });矩形按两个点记录多边形按多个点记录点击完复制控制台输出即可生成数据。这个小页面我保留在项目工具目录里每来新图都能用比手动去 PS 里量像素坐标快出一个数量级。6.2 无障碍支持tabindex、aria-label 与回车触发热区如果是可交互的必须考虑键盘用户。div 默认不可聚焦给热区节点加tabindex0和aria-label再监听 keydown 里的 Enter 执行同样的点击逻辑// 让热区节点可被键盘聚焦并支持回车触发点击 el.setAttribute(tabindex, 0); el.setAttribute(role, button); el.setAttribute(aria-label, spot.name || 图片热区); el.addEventListener(keydown, e { if (e.key Enter) el.click(); });这里有一个易忽略点热区节点如果互相挨得很近tab 顺序可能混乱需要在数据协议里加 order 字段按 order 给 DOM 排序保证 Tab 顺序与视觉顺序一致。6.3 一套工程化习惯坐标数据独立成 JSON最后一个建议是把热区数据从页面代码里拆出来独立成 JSON 文件或单独模块。这样设计稿变更只改数据不动插件和样式。我在项目里维护过一个包含 300 多个户型热区的数据文件配合局部更新策略热区在移动端和桌面端的体验保持一致靠的就是把数据与渲染彻底分离。这些做法谈不上多复杂但确实让后来接手的人少走了很多弯路希望帮到你。本文还有配套的精品资源点击获取