1. 放大镜效果实现从鼠标坐标映射到 canvas 局部重绘的完整链路放大镜效果实现说白了就是三件事鼠标在哪、遮罩跟到哪、大图从哪块开始画。听起来简单但真正动手写的时候坐标错位、倍率对不上、边界越界这三个坑几乎人人都会踩一遍。这篇面向的是正在做前端电商商品图或地图瓦片局部预览的开发者尤其是那种「小图 hover 出遮罩、右侧大图同步放大」的经典布局。我会把整条链路拆成可跟做的小目标同时把调试过程中用到的 TaoToken 统一 Key 接入方式一并交代清楚——因为我在本地反复调坐标映射时经常需要切换不同模型来帮我 review 代码逻辑统一 Key 能省掉一堆环境变量来回改的麻烦。先说清楚这篇交付什么一份可复制的 settings.json 配置骨架、TaoToken 统一 Key 的接入步骤、以及浏览器 DevTools 里验证放大倍率和偏移量的具体动作。右侧大图的完整渲染放到下一篇这篇先把「遮罩跟随 坐标映射 边界钳制」这条主链路跑通。2. TaoToken 前置统一 Key 解决调试期多模型切换2.1 为什么调试放大镜要接统一 Key调坐标映射的时候我习惯把鼠标事件的pageX/pageY、offsetLeft/offsetTop、遮罩的left/top全部打出来对照。但光看数字容易懵这时候让模型帮我分析「为什么 centerX 算出来是负数」会快很多。问题是不同模型走不同 endpoint、不同 Key环境变量改来改去很烦。TaoToken 的做法是给你一个统一入口模型对话、coding-plan、API 调用都走同一套 Key本地调试脚本里只维护一个变量就行。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在 console 里生成 Key。API 基址是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接填进配置里。2.2 拿 Key 与 settings.json 骨架进入 console 的 API Keys 页面创建 Key复制出来形如sk-xxxx。然后在你项目的.vscode/settings.json或者独立的调试配置里放这么一份骨架{ taotoken.apiBase: https://taotoken.net/api, taotoken.apiKey: sk-你的Key填这里, taotoken.defaultModel: claude-sonnet, magnifier.debug: { smallBoxSize: 398, maskSize: 300, zoomRatio: 4, logMouseEvent: true } }这里zoomRatio是放大倍率maskSize是遮罩边长smallBoxSize是小图容器边长。把这三个值抽出来后面算偏移量的时候直接引用改倍率不用满代码找数字。Key 不要硬编码进提交到仓库的文件本地用.env或者 settings 的本地覆盖层。3. 可复制配置鼠标坐标映射与遮罩跟随3.1 坐标映射的核心公式先明确坐标系。小图容器.small是position: relative遮罩.mask是position: absolute所以遮罩的left/top是相对于小图容器左上角的。鼠标事件里的e.pageX是相对整个文档的要减掉容器的offsetLeftconst centerX e.pageX - smallBox.offsetLeft; const centerY e.pageY - smallBox.offsetTop;这两个值就是鼠标在小图容器内的坐标。遮罩要让鼠标始终落在中心点所以遮罩的left centerX - maskSize / 2top centerY - maskSize / 2。代入 300 的遮罩就是减 150。3.2 边界钳制不能只写一半很多人边界处理只写了左上角if (left 0) left 0; if (top 0) top 0;结果鼠标移到右下角遮罩直接跑出容器。右下边界是smallBoxSize - maskSize代入 398 - 300 98const maxLeft smallBoxSize - maskSize; if (left maxLeft) left maxLeft; if (top maxLeft) top maxLeft;注意这里maxLeft和maxTop数值相同是因为容器是正方形如果小图是长方形得分别算smallBoxWidth - maskSize和smallBoxHeight - maskSize。3.3 完整可运行代码!DOCTYPE html html langzh-CN head meta charsetUTF-8 title放大镜效果实现/title style .small { position: relative; width: 398px; height: 398px; border: 1px solid #ccc; } .small img { width: 398px; height: 398px; display: block; } .mask { position: absolute; left: 0; top: 0; width: 300px; height: 300px; display: none; background: #FEDE4F; opacity: 0.5; cursor: move; } /style /head body div classsmall img src./upload/b3.png alt div classmask/div /div script window.onload function () { const smallBox document.querySelector(.small); const maskBox document.querySelector(.mask); const MASK_SIZE 300; const SMALL_SIZE 398; const MAX_OFFSET SMALL_SIZE - MASK_SIZE; smallBox.addEventListener(mouseenter, function () { maskBox.style.display block; }); smallBox.addEventListener(mouseleave, function () { maskBox.style.display none; }); smallBox.addEventListener(mousemove, function (e) { if (maskBox.style.display ! block) return; const centerX e.pageX - smallBox.offsetLeft; const centerY e.pageY - smallBox.offsetTop; let left centerX - MASK_SIZE / 2; let top centerY - MASK_SIZE / 2; if (left 0) left 0; if (top 0) top 0; if (left MAX_OFFSET) left MAX_OFFSET; if (top MAX_OFFSET) top MAX_OFFSET; maskBox.style.left left px; maskBox.style.top top px; }); }; /script /body /html这段代码跑起来遮罩会跟着鼠标走且不会越界。但注意这只是「遮罩跟随」这一环右侧大图的局部重绘还没接上。3.4 canvas 局部重绘的衔接点右侧大图如果用 canvas 画核心是把遮罩的left/top映射到大图的绘制起点。放大倍率zoomRatio决定映射关系const drawX left * zoomRatio; const drawY top * zoomRatio; const drawSize MASK_SIZE * zoomRatio; ctx.drawImage( sourceImage, drawX, drawY, drawSize, drawSize, 0, 0, canvasWidth, canvasHeight );这里sourceImage是原图drawX/drawY是原图上要截取的起点drawSize是截取区域边长。如果倍率是 4遮罩 300那截取区域就是 1200×1200画到 canvas 上。坐标错位最常见的原因就是这里drawX忘了乘倍率或者 canvas 的宽高和drawSize对不上。4. 验证请求DevTools 里确认倍率与偏移量4.1 用 console 打印对照在mousemove里加一行日志console.log({ centerX, centerY, left, top, drawX: left * 4, drawY: top * 4 });打开 DevTools 的 Console鼠标在小图上慢慢移动观察left/top是否在 0 到 98 之间drawX/drawY是否在 0 到 392 之间98×4。如果left出现负数或大于 98说明边界钳制没生效。4.2 用 Elements 面板看遮罩实际位置选中.mask元素在 Styles 面板里看left/top的实时值。鼠标移到小图左上角遮罩应该是left: 0; top: 0移到右下角应该是left: 98px; top: 98px。如果对不上回到 3.1 检查offsetLeft是不是被父级定位影响了。4.3 用 TaoToken 模型对话辅助排查如果打印出来的数字逻辑上说不通可以把日志贴到模型对话里问。入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 的模型对话页同一个 Key 直接可用。我试过把centerX为负的日志贴进去模型会提示检查smallBox.offsetLeft是否包含了页面滚动偏移——这种问题光看代码容易漏。5. 本篇常见错排查5.1 遮罩不跟随鼠标先确认mouseenter里display设成了block再确认mousemove里的if判断没写反。如果遮罩显示但不动检查maskBox.style.left赋值时有没有拼上px漏了单位浏览器会忽略。5.2 坐标整体偏移一个固定值大概率是offsetLeft取错了元素。smallBox.offsetLeft是相对其offsetParent的如果.small外面还有定位祖先这个值会变。稳妥做法是用getBoundingClientRect()const rect smallBox.getBoundingClientRect(); const centerX e.clientX - rect.left; const centerY e.clientY - rect.top;注意用clientX/clientY配getBoundingClientRect不要混用pageX。5.3 边界钳制后遮罩卡住不动检查MAX_OFFSET是不是算成了负数。如果maskSize大于smallBoxSizeSMALL_SIZE - MASK_SIZE就是负的钳制逻辑会把left锁死在负数上。确保遮罩尺寸小于容器尺寸。5.4 放大倍率对不上在 canvas 绘制那一步drawSize和 canvas 的实际宽高必须匹配。如果 canvas 是 400×400drawSize算出来 1200drawImage会把 1200 的区域压到 400 里看起来就是缩小而不是放大。要么把 canvas 设成drawSize要么在drawImage的目标参数里写对尺寸。6. 接入文档与后续链路这篇把遮罩跟随和坐标映射跑通了右侧大图的 canvas 局部重绘只开了个头。如果你在接入 TaoToken 统一 Key 的过程中遇到配置问题可以直接看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面把 API 基址、Key 放置位置、常见返回码都列清楚了。长期做前端编码和 Agent 调试的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有更细的额度说明。下一篇我会把右侧大图的完整渲染补上包括 canvas 尺寸计算、原图预加载、以及倍率切换时的重绘时机。你可以先把这篇的代码跑起来把console.log的数字对照一遍确认坐标映射没问题再往下接大图会顺很多。