简介一份基于 jQuery 的图片热区交互插件源码面向前端开发者与交互设计人员用于在图片上自由绘制矩形、圆形或不规则区域并为每个热区绑定独立链接或事件适合在线地图、产品展示和交互式教程等场景。压缩包共8个文件包含JS核心库与依赖库、CSS样式、HTML演示页、PNG背景素材、README说明及工程配置整体仅209KB结构紧凑便于下载后直接预览与部署。已有2271人学习下载适合初学者快速上手。通过演示页与项目文件可学习热区绘制、链接绑定、样式定制等关键写法插件基于jQuery构建源码注释详细支持在IntelliJ IDEA等IDE中预览编辑有助于二次开发与团队协作。1. 图片热区插件到底是什么不只是一张图上画几个透明方块电商场景里最常见的交互不是按钮而是商品图上那些可点击的局部区域鞋子、背带、配饰鼠标悬停过去就弹提示、跳链接或者高亮。很多人第一反应是给img套maparea真做起来才知道这套老方案在响应式布局和动态数据面前有多别扭。这个图片热区 js 插件要解决的就是「把一张普通图片变成可配置的交互地图」这整件事。它适合两类人一类是电商、营销页开发需要快速在图片上圈定可点击区域并绑定跳转另一类是二次开发的学习者能从一个完整的热区编辑器和运行时渲染方案里学会坐标系统、命中检测和事件交互这些前端基本功。它的核心思路很简单——把热区数据抽象成一份 JSON编辑器和渲染层各管一头图片随意缩放热区自己跟着走。2. 设计思路与技术选型为什么不用现成 map 标签而是自研热区引擎2.1 原生 map/area 标签的痛点要理解这个插件为什么存在得先看清楚map标签的死穴。area的coords是写死像素的图片一旦不是 1:1 原尺寸展示点击区域就全部偏移。响应式页面里object-fit: cover一上场原图被裁剪coords直接作废。更麻烦的是运营要自己改热区——你不大可能让运营去手改标签属性必须提供一个可视化编辑界面。而一个独立插件可以做得更彻底热区数据从图片解耦出来存成 JSON渲染时实时换算坐标。图片怎么缩放、怎么裁剪只要把换算规则定死热区永远贴着图走。这个思路也是整个项目的架构基石。2.2 插件架构总览编辑器与运行时两层拆分整个项目拆成两个互相独立的部分hotspot-plugin/ ├── src/ │ ├── core/ # 运行时核心不依赖 DOM 状态 │ │ ├── Hotspot.js # 主控制器 │ │ ├── types.js # 热区类型定义rect/circle/polygon │ │ └── hitTest.js # 命中检测算法 │ ├── editor/ # 编辑器模块负责可视化绘制 │ │ ├── Editor.js # 编辑器主逻辑 │ │ ├── drawTool.js # 绘制工具矩形/圆/多边形 │ │ └── overlay.js # 编辑器覆盖层渲染 │ ├── renderer/ │ │ ├── overlayLayer.js # 展示层热区渲染 │ │ └── tooltip.js # 悬停提示气泡 │ └── utils/ │ ├── coordinates.js # 坐标换算工具 │ └── dom.js # DOM 操作辅助编辑器的职责是「把用户手指或鼠标画的图形转成结构化数据」运行时的职责是「把结构化数据渲染成可交互的热区」。两者之间唯一的约定是数据格式。这个拆分带来的好处是线上展示根本不需要引入编辑器代码生产包体积小一半如果运营需要临时改热区再单独加载编辑器模块。2.3 技术选型方案项目不依赖任何框架原生 JavaScript 实现。用原生有几层考虑。首先热区交互本身就是 DOM 事件和坐标计算框架在这里帮不上太多忙反而徒增依赖体积。其次这个插件要被不同技术栈的项目引用——有人插进 Vue有人插进 React有人直接在 SSR 页面里用原生模块可以以零依赖的形式发布任何环境都能直接引入。渲染层采用的是「绝对定位覆盖层方案」。在图片外层包一个相对定位容器热区用绝对定位的 DOM 或 SVG 元素铺在图片上方。相比 canvas 方案DOM 方案的好处是热区天然支持 CSS hover 效果、事件绑定和自定义 tooltip不需要自己额外做事件拾取。绘制和展示统一用 SVG 而不是 Div 切法是为了一次性支持矩形、圆和不规则多边形三种形状SVG 图形属性直接用数据坐标设置少一层换算。3. 目录结构与核心模块拆解一张图上的热区是怎么被算出来的3.1 坐标系统的确立所有热区逻辑的第一步是确定坐标存什么格式。插件选择「百分比 像素」双轨制JSON 数据里存相对于原图的百分比坐标渲染时换算成当前显示尺寸的像素坐标。原图设计稿宽度是 1600px一个热区 x 坐标是 800px那存的就是 50%页面把这个图渲染成 800px 宽热区实际渲染 x 就是 400px。这个设计的原因很简单百分比坐标天然抗缩放图片不管长宽比变化多少热区相对位置不会跑。像素坐标只存在于渲染层和编辑器层用于实际 DOM 操作和命中检测。3.2 核心模块一坐标换算工具坐标换算是整个插件的最小核心单元所有模块都依赖它// utils/coordinates.js const coordinates { /** * 将真实像素坐标转换为相对于原始图片尺寸的百分比坐标 */ toPercent(point, originWidth, originHeight) { return { x: (point.x / originWidth) * 100, y: (point.y / originHeight) * 100, }; }, /** * 将百分比坐标转换为当前容器尺寸下的像素坐标 */ toPixel(percentPoint, containerWidth, containerHeight) { return { x: (percentPoint.x / 100) * containerWidth, y: (percentPoint.y / 100) * containerHeight, }; }, /** * 将百分比热区数据转换成渲染层的绝对定位样式 */ hotspotToStyle(hotspot, containerWidth, containerHeight) { const base { left: ${hotspot.x}%, top: ${hotspot.y}% }; if (hotspot.type rect) { return { ...base, width: ${hotspot.width}%, height: ${hotspot.height}%, }; } if (hotspot.type circle) { return { ...base, width: ${hotspot.radius * 2}%, height: ${hotspot.radius * 2}%, }; } return base; }, };上面这段代码里的关键点是toPercent和toPixel。运行时渲染阶段插件拿到原始图片尺寸和容器当前尺寸用toPixel把热区数据转成像素用于命中检测DOM 样式阶段却可以直接用百分比设置因为left/top/width/height天然支持百分比单位浏览器会替我们做换算。这两个方法多存储 double 计算但性能完全不是问题——一个页面上的热区通常不会超过 50 个。使用注意originWidth/originHeight必须取自图片naturalWidth/naturalHeight而不是offsetWidth。offsetWidth是图片实际渲染宽度可能是被 CSS 缩放过的用它当基准会导致热区在明暗两套渲染尺寸之间来回漂移。这是跑这个项目时最容易踩的第一个坑。3.3 核心模块二命中检测算法热区渲染成 DOM 之后浏览器自己会处理点击事件看起来好像不需要命中检测模块。但在编辑器场景里绘制过程中还没有生成 DOM鼠标移动时需要实时判断光标在哪个热区附近、要不要吸附端点运行时场景里你也许需要做「热区重叠检测」或者「键盘导航」。命中检测是数据层面的兜底能力。// core/hitTest.js const hitTest { /** * 统一入口按热区类型分发到具体检测函数 */ isPointInHotspot(point, hotspot, containerWidth, containerHeight) { const target coordinates.toPixel(hotspot, containerWidth, containerHeight); switch (hotspot.type) { case rect: return this._inRect(point, target); case circle: return this._inCircle(point, target); case polygon: return this._inPolygon(point, target.points); default: return false; } }, _inRect(point, rect) { return point.x rect.x point.x rect.x rect.width point.y rect.y point.y rect.y rect.height; }, _inCircle(point, circle) { const dx point.x - circle.x; const dy point.y - circle.y; return Math.sqrt(dx * dx dy * dy) circle.radius; }, _inPolygon(point, polygonPoints) { // 射线法实现从 point 向右发一条水平射线 let inside false; for (let i 0, j polygonPoints.length - 1; i polygonPoints.length; j i) { const pi polygonPoints[i]; const pj polygonPoints[j]; const intersects ((pi.y point.y) ! (pj.y point.y)) (point.x (pj.x - pi.x) * (point.y - pi.y) / (pj.y - pi.y) pi.x); if (intersects) inside !inside; } return inside; }, };射线法Ray Casting是多边形命中检测的经典实现从目标点水平向右发一条射线统计它与多边形边界的交点个数奇数则在内部偶数则在外部。代码里的intersects表达式同时处理了判断和边界条件核心机制是利用了两个顶点y坐标与目标点y坐标的差值符号不同来确定射线是否穿过了这条边。这个模块在编辑器里用处特别大。绘制多边形时每加一个顶点就用命中检测判断当前鼠标位置是否落在已绘制的区域内从而决定要不要闭合图形或者高亮提示——不用等渲染完成再做区域判断。4. 编辑器模块实战从鼠标绘制到 JSON 导出的完整链路4.1 热区数据结构的统一约定编辑器画出来的东西最终要落到一份可以被渲染层直接消费的 JSON 上。三种类型的通用字段是id/type/x/y矩形多width/height圆形多radius多边形多points。// 一份标准的热区数据示例 [ { id: hotspot-001, type: rect, x: 42.5, // 左上角 x 的百分比坐标 y: 31.2, // 左上角 y 的百分比坐标 width: 18.3, // 矩形宽百分比 height: 12.6, // 矩形高百分比 action: { type: link, value: /products/shoes/2024-001 }, label: 春季限量款跑鞋 }, { id: hotspot-002, type: circle, x: 70.8, y: 44.1, radius: 5.2, // 半径百分比 action: { type: tooltip, value: 隐藏参数鞋底缓震层 } }, { id: hotspot-003, type: polygon, points: [ { x: 20.1, y: 55.3 }, { x: 35.6, y: 49.8 }, { x: 40.2, y: 62.7 }, { x: 25.9, y: 68.4 } ], action: { type: lightbox, value: /gallery/sneakers-detail } } ]action字段是整个热区的「行为载荷」渲染层拿到它只做一件事按类型触发对应回调。这种设计把数据与行为解耦运营配置热区时完全不关心跳转怎么实现只填action.type和action.value。后续要加新行为类型比如埋点上报、打开视频弹窗扩展action的联合类型即可。4.2 绘制交互的事件流设计编辑器交互是典型的「按下 — 拖动 — 抬起」三段式。矩形和圆形的绘制逻辑几乎一样按下时固定起点拖动过程中实时预览抬起时确定终点。// editor/drawTool.js 片段矩形绘制逻辑 class DrawTool { constructor(overlaySvg, options) { this.overlaySvg overlaySvg; this.drawing false; this.startPoint null; this.previewElements { rect: null }; this.onComplete options.onComplete || (() {}); } bindEvents() { this.overlaySvg.addEventListener(mousedown, (e) { // 只响应左键避免和右键菜单冲突 if (e.button ! 0) return; this.drawing true; this.startPoint this._toRelativePoint(e); this._createPreviewRect(this.startPoint); e.preventDefault(); }); this.overlaySvg.addEventListener(mousemove, (e) { if (!this.drawing) return; const currentPoint this._toRelativePoint(e); this._updatePreviewRect(this.startPoint, currentPoint); }); document.addEventListener(mouseup, (e) { if (!this.drawing) return; this.drawing false; const endPoint this._toRelativePoint(e); const rectData this._computeRectData(this.startPoint, endPoint); this._removePreview(); this.onComplete(rectData); }); } _toRelativePoint(e) { const svgRect this.overlaySvg.getBoundingClientRect(); return { x: e.clientX - svgRect.left, y: e.clientY - svgRect.top, }; } }_toRelativePoint是把鼠标在屏幕上的绝对位置换算成相对 SVG 容器的本地坐标。这里用的是getBoundingClientRect()做一次减法比createSVGPoint()那套换算逻辑更直接。mousedown和mousemove监听在 SVG 上而mouseup必须挂到document——这保证鼠标拖出容器外再松开也能正确结束绘制是一个资深的交互经验点。最终回调出去的rectData是百分比坐标不是像素坐标。换算发生在_computeRectData内部_computeRectData(start, end) { const imgW this.baseWidth; // 图片 naturalWidth const imgH this.baseHeight; // 图片 naturalHeight return { type: rect, x: (Math.min(start.x, end.x) / imgW) * 100, y: (Math.min(start.y, end.y) / imgH) * 100, width: (Math.abs(end.x - start.x) / imgW) * 100, height: (Math.abs(end.y - start.y) / imgH) * 100, }; }用Math.min处理反向拖动从右下往左上画用Math.abs保证宽高恒为正数。这两个细节不做的话用户向左或向上拖动时热区坐标会变成负数渲染层拿到负宽高的矩形直接显示不出来——这是编辑器类工具最常见的翻车点。4.3 多边形绘制的特殊处理多边形绘制和矩形圆形的交互完全不同不是一次拖动成型而是逐点点击连线双击或点击起点闭合。代码里需要维护一个顶点数组// editor/drawTool.js 片段多边形顶点收集 _polygonToolState { points: [], tempPolygonElement: null, }; addPoint(point) { this._polygonToolState.points.push(point); this._renderPolygonPreview(this._polygonToolState.points); // 如果点击位置接近起点阈值 10px自动闭合 const first this._polygonToolState.points[0]; const dx point.x - first.x; const dy point.y - first.y; if (Math.sqrt(dx * dx dy * dy) 10) { this._closePolygon(); } } _closePolygon() { const points this._polygonToolState.points.slice(0, -1); // 去掉多余的终点 if (points.length 3) { this._resetPolygonTool(); return; } const polygonData { type: polygon, points: points.map((p) ({ x: (p.x / this.baseWidth) * 100, y: (p.y / this.baseHeight) * 100, })), }; this.onComplete(polygonData); this._resetPolygonTool(); }闭合阈值的判断放在addPoint里用户体验上是「最后一个点点到差不多位置就自动闭合」的效果。注意_closePolygon把最后一个点slice掉了——因为那个点是闭合时误触的重复点。命中检测在这里也派上用场编辑器实时用射线法判断当前悬停的位置是否在已绘制的多边形内部如果在就给用户一个「可以闭合」的光标反馈进一步降低误操作概率。5. 避坑记录图片热区插件落地最容易踩的 4 个坑5.1 坑一图片尺寸变化后热区全部偏移现象插件在富文本编辑器里调试一切正常图片原尺寸 1600px热区精确贴合。发布到移动端图片变成宽度 375px所有热区都偏了。原因坐标换算用了offsetWidth/offsetHeight作为基准。offsetWidth是元素的实际渲染宽度它会受 CSS 影响——比如设置了max-width: 100%图片在桌面端渲染成 1600px移动端渲染成 375px同一份代码在两端用不同的基准算热区结果自然不一致。解决换算统一改用naturalWidth/naturalHeight。这两个属性返回的是图片源文件的真实尺寸没有任何 CSS 干扰。渲染层再做一次「以原始尺寸为基准的百分比 → 当前容器像素」的转换。记住一句话你把什么尺寸当基准存的就永远用那个尺寸当基准算。5.2 坑二z-index 设置的坑——热区盖住了图片本身现象热区渲染出来了但图片上的所有操作全部失效图片本身绑定的点击事件永远触发不了。原因热区元素position: absolute放进一个容器容器的z-index很高热区元素默认层级高于图片图片上原本有点击缩放等交互被透明的热区 DOM 遮住了。透明元素依然占据层级空间事件会命中它而不是图片本身。解决在热区容器上设置pointer-events: none热区元素显式设置为pointer-events: auto。这样「事件穿透」只在没有热区的地方生效有热区的地方正常捕获点击。这是热区叠加层的标准做法不做的话一个页面有热区的地方图片永远点不到。5.3 坑三热区编辑器和页面滚动事件打架现象在移动端用手指绘制多边形时手指一动页面就跟着滚热区画得歪歪扭扭。原因绘制操作本质是手指在触摸屏上滑动而touchmove是passive事件浏览器认为默认行为滚动必须执行不可能被preventDefault()取消。解决绘制进行时在容器上动态设置touch-action: none绘制结束恢复原值。这个 CSS 属性告诉浏览器「这个元素上触摸操作由 JS 处理不需要滚动」绕开 passive 限制。同理鼠标拖拽在桌面端不会和滚动冲突但触摸端必须处理。如果项目把编辑器做成覆盖层最佳实践是编辑模式下给根容器加overflow: hidden配合touch-action: none双保险。5.4 坑四图片懒加载导致热区初始化位置错乱现象页面加载完成后热区要等两三秒才出现出现时位置比图片偏了一截图片加载完成后热区又跳回正确位置。原因热区初始化时图片还没加载完成naturalWidth/naturalHeight是 0。这时候做百分比换算得到一堆 NaN 或 0渲染出来的热区位置全部错误。等图片真正加载完成naturalWidth有了真实值重新计算后热区位置又修正了。解决初始化顺序强行依赖图片load事件而不是 DOMContentLoaded。代码必须先await图片的 load 完成再拿到自然尺寸去初始化热区。另一个备选是轮询检查img.complete属性但complete在缓存命中时会直接为 true 导致跳过等待不如事件监听可靠。注意load事件在图片已缓存时可能不触发的边界情况所以要在complete为 true 时直接继续初始化逻辑。6. 二次开发把插件接进任意框架的四个改造点先说一个改造理念这个项目的两个核心模块——坐标系统和命中检测——是纯函数集合完全不依赖 DOM API这是刻意设计的结果。二次开发时优先保持核心模块的纯净性把 DOM 交互全部隔离在渲染层和编辑器层这样不管外面包什么框架核心逻辑一行不改只替换渲染和事件绑定。第一个改造点是「数据驱动的框架接入」。在 React 里用这个插件正确的姿势是把热区数据作为 React state 持有渲染层用一个useEffect监听数据变化如果变化就调用hotspotInstance.setData(newData)。不要把热区数据存在插件实例内部不然 React 的状态管理就会和数据源脱节你没法在组件里直接根据热区数据联动其他 UI。同理在 Vue 里把setData封装成watch的响应式入口。第二个改造点是「事件钩子扩展」。原插件的 action 是内置的link/tooltip/lightbox三类实际接入时业务方可能有自定义行为比如点击热区上报埋点、触发弹窗组件、联动播放视频。我的改法是在Hotspot构造函数里加一个actionHandler注册表// 二次开发示例自定义 action 处理器 const hotspot new Hotspot({ container: #image-wrapper, onAction: (hotspotData) { const handlerMap { link: () window.open(hotspotData.action.value, _blank), track: () trackEvent(hotspot_click, { id: hotspotData.id }), videoModal: () openVideoModal(hotspotData.action.value), }; const handler handlerMap[hotspotData.action.type]; handler handler(); }, });这样业务方只扩展handlerMap就能接入任意行为不需要改动插件内部代码。这个模式比覆写onClick回调干净得多能支持一个页面多种热区行为混合存在。第三个改造点是「多边形精细编辑」。原插件多边形只能逐点绘制运营想调整一个顶点的位置只能删除重画。这个功能不复杂面向顶点做拖拽监听拖拽中的命中检测交给_inPolygon判断哪个顶点离光标最近阈值 8px然后更新对应点的百分比坐标并触发重绘。这是二次开发里性价比最高的一块。第四个改造点是「响应式断点适配」。如果同一张图在不同断位下需要不同的热区——比如桌面端鼠标悬停有 tooltip移动端没有——那就在Hotspot.setData之前做一层数据预处理根据视口宽度过滤掉不需要的热区。注意不要去改坐标数据只过滤id列表这样数据源保持干净后续切换断点恢复也容易。这个项目我从拆开读到改完一共花了两天。最值得记的一笔是把命中检测从渲染层抽出来的那次重构——在那之前我把点击判断写在 SVG 的click事件里编辑器一用就崩因为绘制过程中根本没有 DOM 可点。从那以后我每次做这类图形交互插件都强制走一遍「纯函数核心 单层 DOM 渲染 事件隔离」的三层分离再也没为类似问题返工。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/18 20:00:25 · 阅读 1.2k 图片热区插件开发全解：坐标换算、命中检测与避坑指南
简介一份基于 jQuery 的图片热区交互插件源码面向前端开发者与交互设计人员用于在图片上自由绘制矩形、圆形或不规则区域并为每个热区绑定独立链接或事件适合在线地图、产品展示和交互式教程等场景。压缩包共8个文件包含JS核心库与依赖库、CSS样式、HTML演示页、PNG背景素材、README说明及工程配置整体仅209KB结构紧凑便于下载后直接预览与部署。已有2271人学习下载适合初学者快速上手。通过演示页与项目文件可学习热区绘制、链接绑定、样式定制等关键写法插件基于jQuery构建源码注释详细支持在IntelliJ IDEA等IDE中预览编辑有助于二次开发与团队协作。1. 图片热区插件到底是什么不只是一张图上画几个透明方块电商场景里最常见的交互不是按钮而是商品图上那些可点击的局部区域鞋子、背带、配饰鼠标悬停过去就弹提示、跳链接或者高亮。很多人第一反应是给img套maparea真做起来才知道这套老方案在响应式布局和动态数据面前有多别扭。这个图片热区 js 插件要解决的就是「把一张普通图片变成可配置的交互地图」这整件事。它适合两类人一类是电商、营销页开发需要快速在图片上圈定可点击区域并绑定跳转另一类是二次开发的学习者能从一个完整的热区编辑器和运行时渲染方案里学会坐标系统、命中检测和事件交互这些前端基本功。它的核心思路很简单——把热区数据抽象成一份 JSON编辑器和渲染层各管一头图片随意缩放热区自己跟着走。2. 设计思路与技术选型为什么不用现成 map 标签而是自研热区引擎2.1 原生 map/area 标签的痛点要理解这个插件为什么存在得先看清楚map标签的死穴。area的coords是写死像素的图片一旦不是 1:1 原尺寸展示点击区域就全部偏移。响应式页面里object-fit: cover一上场原图被裁剪coords直接作废。更麻烦的是运营要自己改热区——你不大可能让运营去手改标签属性必须提供一个可视化编辑界面。而一个独立插件可以做得更彻底热区数据从图片解耦出来存成 JSON渲染时实时换算坐标。图片怎么缩放、怎么裁剪只要把换算规则定死热区永远贴着图走。这个思路也是整个项目的架构基石。2.2 插件架构总览编辑器与运行时两层拆分整个项目拆成两个互相独立的部分hotspot-plugin/ ├── src/ │ ├── core/ # 运行时核心不依赖 DOM 状态 │ │ ├── Hotspot.js # 主控制器 │ │ ├── types.js # 热区类型定义rect/circle/polygon │ │ └── hitTest.js # 命中检测算法 │ ├── editor/ # 编辑器模块负责可视化绘制 │ │ ├── Editor.js # 编辑器主逻辑 │ │ ├── drawTool.js # 绘制工具矩形/圆/多边形 │ │ └── overlay.js # 编辑器覆盖层渲染 │ ├── renderer/ │ │ ├── overlayLayer.js # 展示层热区渲染 │ │ └── tooltip.js # 悬停提示气泡 │ └── utils/ │ ├── coordinates.js # 坐标换算工具 │ └── dom.js # DOM 操作辅助编辑器的职责是「把用户手指或鼠标画的图形转成结构化数据」运行时的职责是「把结构化数据渲染成可交互的热区」。两者之间唯一的约定是数据格式。这个拆分带来的好处是线上展示根本不需要引入编辑器代码生产包体积小一半如果运营需要临时改热区再单独加载编辑器模块。2.3 技术选型方案项目不依赖任何框架原生 JavaScript 实现。用原生有几层考虑。首先热区交互本身就是 DOM 事件和坐标计算框架在这里帮不上太多忙反而徒增依赖体积。其次这个插件要被不同技术栈的项目引用——有人插进 Vue有人插进 React有人直接在 SSR 页面里用原生模块可以以零依赖的形式发布任何环境都能直接引入。渲染层采用的是「绝对定位覆盖层方案」。在图片外层包一个相对定位容器热区用绝对定位的 DOM 或 SVG 元素铺在图片上方。相比 canvas 方案DOM 方案的好处是热区天然支持 CSS hover 效果、事件绑定和自定义 tooltip不需要自己额外做事件拾取。绘制和展示统一用 SVG 而不是 Div 切法是为了一次性支持矩形、圆和不规则多边形三种形状SVG 图形属性直接用数据坐标设置少一层换算。3. 目录结构与核心模块拆解一张图上的热区是怎么被算出来的3.1 坐标系统的确立所有热区逻辑的第一步是确定坐标存什么格式。插件选择「百分比 像素」双轨制JSON 数据里存相对于原图的百分比坐标渲染时换算成当前显示尺寸的像素坐标。原图设计稿宽度是 1600px一个热区 x 坐标是 800px那存的就是 50%页面把这个图渲染成 800px 宽热区实际渲染 x 就是 400px。这个设计的原因很简单百分比坐标天然抗缩放图片不管长宽比变化多少热区相对位置不会跑。像素坐标只存在于渲染层和编辑器层用于实际 DOM 操作和命中检测。3.2 核心模块一坐标换算工具坐标换算是整个插件的最小核心单元所有模块都依赖它// utils/coordinates.js const coordinates { /** * 将真实像素坐标转换为相对于原始图片尺寸的百分比坐标 */ toPercent(point, originWidth, originHeight) { return { x: (point.x / originWidth) * 100, y: (point.y / originHeight) * 100, }; }, /** * 将百分比坐标转换为当前容器尺寸下的像素坐标 */ toPixel(percentPoint, containerWidth, containerHeight) { return { x: (percentPoint.x / 100) * containerWidth, y: (percentPoint.y / 100) * containerHeight, }; }, /** * 将百分比热区数据转换成渲染层的绝对定位样式 */ hotspotToStyle(hotspot, containerWidth, containerHeight) { const base { left: ${hotspot.x}%, top: ${hotspot.y}% }; if (hotspot.type rect) { return { ...base, width: ${hotspot.width}%, height: ${hotspot.height}%, }; } if (hotspot.type circle) { return { ...base, width: ${hotspot.radius * 2}%, height: ${hotspot.radius * 2}%, }; } return base; }, };上面这段代码里的关键点是toPercent和toPixel。运行时渲染阶段插件拿到原始图片尺寸和容器当前尺寸用toPixel把热区数据转成像素用于命中检测DOM 样式阶段却可以直接用百分比设置因为left/top/width/height天然支持百分比单位浏览器会替我们做换算。这两个方法多存储 double 计算但性能完全不是问题——一个页面上的热区通常不会超过 50 个。使用注意originWidth/originHeight必须取自图片naturalWidth/naturalHeight而不是offsetWidth。offsetWidth是图片实际渲染宽度可能是被 CSS 缩放过的用它当基准会导致热区在明暗两套渲染尺寸之间来回漂移。这是跑这个项目时最容易踩的第一个坑。3.3 核心模块二命中检测算法热区渲染成 DOM 之后浏览器自己会处理点击事件看起来好像不需要命中检测模块。但在编辑器场景里绘制过程中还没有生成 DOM鼠标移动时需要实时判断光标在哪个热区附近、要不要吸附端点运行时场景里你也许需要做「热区重叠检测」或者「键盘导航」。命中检测是数据层面的兜底能力。// core/hitTest.js const hitTest { /** * 统一入口按热区类型分发到具体检测函数 */ isPointInHotspot(point, hotspot, containerWidth, containerHeight) { const target coordinates.toPixel(hotspot, containerWidth, containerHeight); switch (hotspot.type) { case rect: return this._inRect(point, target); case circle: return this._inCircle(point, target); case polygon: return this._inPolygon(point, target.points); default: return false; } }, _inRect(point, rect) { return point.x rect.x point.x rect.x rect.width point.y rect.y point.y rect.y rect.height; }, _inCircle(point, circle) { const dx point.x - circle.x; const dy point.y - circle.y; return Math.sqrt(dx * dx dy * dy) circle.radius; }, _inPolygon(point, polygonPoints) { // 射线法实现从 point 向右发一条水平射线 let inside false; for (let i 0, j polygonPoints.length - 1; i polygonPoints.length; j i) { const pi polygonPoints[i]; const pj polygonPoints[j]; const intersects ((pi.y point.y) ! (pj.y point.y)) (point.x (pj.x - pi.x) * (point.y - pi.y) / (pj.y - pi.y) pi.x); if (intersects) inside !inside; } return inside; }, };射线法Ray Casting是多边形命中检测的经典实现从目标点水平向右发一条射线统计它与多边形边界的交点个数奇数则在内部偶数则在外部。代码里的intersects表达式同时处理了判断和边界条件核心机制是利用了两个顶点y坐标与目标点y坐标的差值符号不同来确定射线是否穿过了这条边。这个模块在编辑器里用处特别大。绘制多边形时每加一个顶点就用命中检测判断当前鼠标位置是否落在已绘制的区域内从而决定要不要闭合图形或者高亮提示——不用等渲染完成再做区域判断。4. 编辑器模块实战从鼠标绘制到 JSON 导出的完整链路4.1 热区数据结构的统一约定编辑器画出来的东西最终要落到一份可以被渲染层直接消费的 JSON 上。三种类型的通用字段是id/type/x/y矩形多width/height圆形多radius多边形多points。// 一份标准的热区数据示例 [ { id: hotspot-001, type: rect, x: 42.5, // 左上角 x 的百分比坐标 y: 31.2, // 左上角 y 的百分比坐标 width: 18.3, // 矩形宽百分比 height: 12.6, // 矩形高百分比 action: { type: link, value: /products/shoes/2024-001 }, label: 春季限量款跑鞋 }, { id: hotspot-002, type: circle, x: 70.8, y: 44.1, radius: 5.2, // 半径百分比 action: { type: tooltip, value: 隐藏参数鞋底缓震层 } }, { id: hotspot-003, type: polygon, points: [ { x: 20.1, y: 55.3 }, { x: 35.6, y: 49.8 }, { x: 40.2, y: 62.7 }, { x: 25.9, y: 68.4 } ], action: { type: lightbox, value: /gallery/sneakers-detail } } ]action字段是整个热区的「行为载荷」渲染层拿到它只做一件事按类型触发对应回调。这种设计把数据与行为解耦运营配置热区时完全不关心跳转怎么实现只填action.type和action.value。后续要加新行为类型比如埋点上报、打开视频弹窗扩展action的联合类型即可。4.2 绘制交互的事件流设计编辑器交互是典型的「按下 — 拖动 — 抬起」三段式。矩形和圆形的绘制逻辑几乎一样按下时固定起点拖动过程中实时预览抬起时确定终点。// editor/drawTool.js 片段矩形绘制逻辑 class DrawTool { constructor(overlaySvg, options) { this.overlaySvg overlaySvg; this.drawing false; this.startPoint null; this.previewElements { rect: null }; this.onComplete options.onComplete || (() {}); } bindEvents() { this.overlaySvg.addEventListener(mousedown, (e) { // 只响应左键避免和右键菜单冲突 if (e.button ! 0) return; this.drawing true; this.startPoint this._toRelativePoint(e); this._createPreviewRect(this.startPoint); e.preventDefault(); }); this.overlaySvg.addEventListener(mousemove, (e) { if (!this.drawing) return; const currentPoint this._toRelativePoint(e); this._updatePreviewRect(this.startPoint, currentPoint); }); document.addEventListener(mouseup, (e) { if (!this.drawing) return; this.drawing false; const endPoint this._toRelativePoint(e); const rectData this._computeRectData(this.startPoint, endPoint); this._removePreview(); this.onComplete(rectData); }); } _toRelativePoint(e) { const svgRect this.overlaySvg.getBoundingClientRect(); return { x: e.clientX - svgRect.left, y: e.clientY - svgRect.top, }; } }_toRelativePoint是把鼠标在屏幕上的绝对位置换算成相对 SVG 容器的本地坐标。这里用的是getBoundingClientRect()做一次减法比createSVGPoint()那套换算逻辑更直接。mousedown和mousemove监听在 SVG 上而mouseup必须挂到document——这保证鼠标拖出容器外再松开也能正确结束绘制是一个资深的交互经验点。最终回调出去的rectData是百分比坐标不是像素坐标。换算发生在_computeRectData内部_computeRectData(start, end) { const imgW this.baseWidth; // 图片 naturalWidth const imgH this.baseHeight; // 图片 naturalHeight return { type: rect, x: (Math.min(start.x, end.x) / imgW) * 100, y: (Math.min(start.y, end.y) / imgH) * 100, width: (Math.abs(end.x - start.x) / imgW) * 100, height: (Math.abs(end.y - start.y) / imgH) * 100, }; }用Math.min处理反向拖动从右下往左上画用Math.abs保证宽高恒为正数。这两个细节不做的话用户向左或向上拖动时热区坐标会变成负数渲染层拿到负宽高的矩形直接显示不出来——这是编辑器类工具最常见的翻车点。4.3 多边形绘制的特殊处理多边形绘制和矩形圆形的交互完全不同不是一次拖动成型而是逐点点击连线双击或点击起点闭合。代码里需要维护一个顶点数组// editor/drawTool.js 片段多边形顶点收集 _polygonToolState { points: [], tempPolygonElement: null, }; addPoint(point) { this._polygonToolState.points.push(point); this._renderPolygonPreview(this._polygonToolState.points); // 如果点击位置接近起点阈值 10px自动闭合 const first this._polygonToolState.points[0]; const dx point.x - first.x; const dy point.y - first.y; if (Math.sqrt(dx * dx dy * dy) 10) { this._closePolygon(); } } _closePolygon() { const points this._polygonToolState.points.slice(0, -1); // 去掉多余的终点 if (points.length 3) { this._resetPolygonTool(); return; } const polygonData { type: polygon, points: points.map((p) ({ x: (p.x / this.baseWidth) * 100, y: (p.y / this.baseHeight) * 100, })), }; this.onComplete(polygonData); this._resetPolygonTool(); }闭合阈值的判断放在addPoint里用户体验上是「最后一个点点到差不多位置就自动闭合」的效果。注意_closePolygon把最后一个点slice掉了——因为那个点是闭合时误触的重复点。命中检测在这里也派上用场编辑器实时用射线法判断当前悬停的位置是否在已绘制的多边形内部如果在就给用户一个「可以闭合」的光标反馈进一步降低误操作概率。5. 避坑记录图片热区插件落地最容易踩的 4 个坑5.1 坑一图片尺寸变化后热区全部偏移现象插件在富文本编辑器里调试一切正常图片原尺寸 1600px热区精确贴合。发布到移动端图片变成宽度 375px所有热区都偏了。原因坐标换算用了offsetWidth/offsetHeight作为基准。offsetWidth是元素的实际渲染宽度它会受 CSS 影响——比如设置了max-width: 100%图片在桌面端渲染成 1600px移动端渲染成 375px同一份代码在两端用不同的基准算热区结果自然不一致。解决换算统一改用naturalWidth/naturalHeight。这两个属性返回的是图片源文件的真实尺寸没有任何 CSS 干扰。渲染层再做一次「以原始尺寸为基准的百分比 → 当前容器像素」的转换。记住一句话你把什么尺寸当基准存的就永远用那个尺寸当基准算。5.2 坑二z-index 设置的坑——热区盖住了图片本身现象热区渲染出来了但图片上的所有操作全部失效图片本身绑定的点击事件永远触发不了。原因热区元素position: absolute放进一个容器容器的z-index很高热区元素默认层级高于图片图片上原本有点击缩放等交互被透明的热区 DOM 遮住了。透明元素依然占据层级空间事件会命中它而不是图片本身。解决在热区容器上设置pointer-events: none热区元素显式设置为pointer-events: auto。这样「事件穿透」只在没有热区的地方生效有热区的地方正常捕获点击。这是热区叠加层的标准做法不做的话一个页面有热区的地方图片永远点不到。5.3 坑三热区编辑器和页面滚动事件打架现象在移动端用手指绘制多边形时手指一动页面就跟着滚热区画得歪歪扭扭。原因绘制操作本质是手指在触摸屏上滑动而touchmove是passive事件浏览器认为默认行为滚动必须执行不可能被preventDefault()取消。解决绘制进行时在容器上动态设置touch-action: none绘制结束恢复原值。这个 CSS 属性告诉浏览器「这个元素上触摸操作由 JS 处理不需要滚动」绕开 passive 限制。同理鼠标拖拽在桌面端不会和滚动冲突但触摸端必须处理。如果项目把编辑器做成覆盖层最佳实践是编辑模式下给根容器加overflow: hidden配合touch-action: none双保险。5.4 坑四图片懒加载导致热区初始化位置错乱现象页面加载完成后热区要等两三秒才出现出现时位置比图片偏了一截图片加载完成后热区又跳回正确位置。原因热区初始化时图片还没加载完成naturalWidth/naturalHeight是 0。这时候做百分比换算得到一堆 NaN 或 0渲染出来的热区位置全部错误。等图片真正加载完成naturalWidth有了真实值重新计算后热区位置又修正了。解决初始化顺序强行依赖图片load事件而不是 DOMContentLoaded。代码必须先await图片的 load 完成再拿到自然尺寸去初始化热区。另一个备选是轮询检查img.complete属性但complete在缓存命中时会直接为 true 导致跳过等待不如事件监听可靠。注意load事件在图片已缓存时可能不触发的边界情况所以要在complete为 true 时直接继续初始化逻辑。6. 二次开发把插件接进任意框架的四个改造点先说一个改造理念这个项目的两个核心模块——坐标系统和命中检测——是纯函数集合完全不依赖 DOM API这是刻意设计的结果。二次开发时优先保持核心模块的纯净性把 DOM 交互全部隔离在渲染层和编辑器层这样不管外面包什么框架核心逻辑一行不改只替换渲染和事件绑定。第一个改造点是「数据驱动的框架接入」。在 React 里用这个插件正确的姿势是把热区数据作为 React state 持有渲染层用一个useEffect监听数据变化如果变化就调用hotspotInstance.setData(newData)。不要把热区数据存在插件实例内部不然 React 的状态管理就会和数据源脱节你没法在组件里直接根据热区数据联动其他 UI。同理在 Vue 里把setData封装成watch的响应式入口。第二个改造点是「事件钩子扩展」。原插件的 action 是内置的link/tooltip/lightbox三类实际接入时业务方可能有自定义行为比如点击热区上报埋点、触发弹窗组件、联动播放视频。我的改法是在Hotspot构造函数里加一个actionHandler注册表// 二次开发示例自定义 action 处理器 const hotspot new Hotspot({ container: #image-wrapper, onAction: (hotspotData) { const handlerMap { link: () window.open(hotspotData.action.value, _blank), track: () trackEvent(hotspot_click, { id: hotspotData.id }), videoModal: () openVideoModal(hotspotData.action.value), }; const handler handlerMap[hotspotData.action.type]; handler handler(); }, });这样业务方只扩展handlerMap就能接入任意行为不需要改动插件内部代码。这个模式比覆写onClick回调干净得多能支持一个页面多种热区行为混合存在。第三个改造点是「多边形精细编辑」。原插件多边形只能逐点绘制运营想调整一个顶点的位置只能删除重画。这个功能不复杂面向顶点做拖拽监听拖拽中的命中检测交给_inPolygon判断哪个顶点离光标最近阈值 8px然后更新对应点的百分比坐标并触发重绘。这是二次开发里性价比最高的一块。第四个改造点是「响应式断点适配」。如果同一张图在不同断位下需要不同的热区——比如桌面端鼠标悬停有 tooltip移动端没有——那就在Hotspot.setData之前做一层数据预处理根据视口宽度过滤掉不需要的热区。注意不要去改坐标数据只过滤id列表这样数据源保持干净后续切换断点恢复也容易。这个项目我从拆开读到改完一共花了两天。最值得记的一笔是把命中检测从渲染层抽出来的那次重构——在那之前我把点击判断写在 SVG 的click事件里编辑器一用就崩因为绘制过程中根本没有 DOM 可点。从那以后我每次做这类图形交互插件都强制走一遍「纯函数核心 单层 DOM 渲染 事件隔离」的三层分离再也没为类似问题返工。希望帮到你。本文还有配套的精品资源点击获取