1. 先把需求拆开看提示框要解决什么问题“js实现鼠标放上按钮出现提示”这句话本身信息很少但它背后要处理的事情比想象中多。一个按钮上放一段说明文字鼠标移上去显示、移开消失——听起来十几行 JS 就能收工可真放到项目里用户会立刻抛出更多要求提示不能挡住鼠标否则会一闪一闪按钮在页面底部时提示不能跑出屏幕按钮放在一个overflow: hidden的卡片里提示不能被裁掉一半页面滚动时提示要跟着按钮走不能停在原地列表里动态生成的几百个按钮也得能用还有键盘用户按 Tab 键聚焦到按钮时同样应该看到提示。所以这篇文章讲的不是“怎么把一段文字显示出来”而是鼠标悬停提示tooltip这套交互在真实页面里的完整实现路径事件该怎么选、坐标该怎么算、层级和裁剪怎么绕开、什么时候该翻转方向、动态节点怎么处理、移动端和键盘怎么兼容。内容会从最基础的原生属性一路写到可以复用的单例组件代码都是能直接贴进项目跑的中间会穿插我在实际项目里踩过的坑比如提示框被祖先元素的transform搞得定位全乱、mouseover冒泡导致的疯狂闪烁。适合谁看刚接触 DOM 事件、想搞清楚“事件为什么会重复触发”的新手正在做后台系统、表格操作列里塞了一堆图标按钮、需要批量加提示的中级开发者以及想判断“这东西到底要不要自己写”的技术负责人。三种人都能从下面几节里拿到东西只是关注点不同新手重点看第 2 节的事件差异和第 3 节的完整代码中级看第 4 节的排查表和第 5 节的委托模式负责人直接看第 1.2 节和最后一节的选型判断。1.1 一个按钮上的提示用户真正需要的是什么先想清楚提示框存在的意义。它不是装饰是给一个信息密度不够的控件补充上下文。图标按钮保存、导出、删除没有文字标签用户靠图标猜表单里某个开关的影响范围不直观表格里某个状态值需要解释。这些场景的共同点是主界面必须保持紧凑补充信息只能在“用户主动关注”的那一刻出现。这决定了三个硬指标。第一是触发要克制鼠标扫过页面时不能到处弹出提示否则页面像打地鼠一般要加 200 到 400 毫秒的延迟用户只是路过就不弹。第二是时机要准确鼠标真正停留在按钮上才开始计时鼠标从按钮移开、哪怕只是移到按钮内部的图标上也不能算移出。第三是消失要干脆移开就收不能拖泥带水留着挡住别的元素。还有一个容易被忽略的点提示框是辅助信息不是关键信息。这意味着它丢了也不会让功能不可用所以实现上可以接受“极端情况下位置略微偏移”但不能接受“提示框挡住按钮导致用户点不到”。后面讲pointer-events: none就是为了这条。1.2 三条技术路线的取舍原生 title、CSS 伪元素、JS 组件在动手写 JS 之前先把可选方案摆清楚不然很容易写了一堆代码发现还不如一行title属性。方案实现成本样式可控性定位能力适用场景原生title属性零成本加个属性就行完全不可控系统渲染跟随鼠标不可控内部工具、后台原型、说明文字很短CSS 伪元素::after>.tip-btn { position: relative; } .tip-btn::after { content: attr(data-tip); position: absolute; left: 50%; bottom: calc(100% 8px); transform: translateX(-50%); max-width: 240px; width: max-content; padding: 6px 10px; font-size: 13px; line-height: 1.5; color: #fff; background: #2b2f36; border-radius: 6px; white-space: normal; opacity: 0; visibility: hidden; transition: opacity .15s ease, visibility .15s ease; pointer-events: none; z-index: 10; } .tip-btn:hover::after, .tip-btn:focus-visible::after { opacity: 1; visibility: visible; }注意width: max-content配max-width这个组合这是让长文本自动换行的关键只写max-width在部分场景下伪元素宽度会被父元素挤压。另外pointer-events: none必须加否则伪元素盖在鼠标上会导致:hover失效进入“显示-隐藏-显示”的抖动循环这个问题我在早期项目里遇到过排查了半天。伪元素方案的死穴有两个一是父级有overflow: hidden就必被裁因为它是子元素二是贴边不能翻转按钮在页面最上面时向上的提示直接跑到视口外。这两个限制在实际页面里出现频率很高一旦碰到就只能换 JS 方案。2. 底层机制拆解事件、坐标、层级写 JS 提示框绕不开三件事用什么事件监听、坐标怎么换算、层级怎么保证。这三块任何一块理解偏了代码都能跑但会出各种奇怪问题。2.1 mouseenter/mouseleave 与 mouseover/mouseout 的真实差异这是新手最容易混的一组。两组事件看起来都是“进出”但行为完全不同。mouseover和mouseout是会冒泡的而且鼠标在元素内部的子节点之间移动时也会触发。假设按钮结构是buttonsvgpath/svg文字/button鼠标从按钮空白处移到 svg 上会先触发按钮的mouseout因为离开了按钮的文本区域再触发 svg 的mouseover并冒泡到按钮。如果你的逻辑是“触发 mouseover 显示、mouseout 隐藏”那么鼠标在按钮内部稍微动一下提示就会疯狂闪。mouseenter和mouseleave是不冒泡的而且浏览器帮你处理了子节点的问题——鼠标从按钮移到按钮内部的 svg不算离开。所以直接给按钮绑定时这两个是正确选择。但这里有个反转如果你要用事件委托一个监听管住页面上所有按钮第 5 节会讲mouseenter就完全不能用了因为它不冒泡绑在document上永远收不到。这时候必须回到mouseover/mouseout靠判断relatedTarget来消除子节点干扰document.addEventListener(mouseout, function (e) { const trigger e.target.closest([data-tip]); if (!trigger) return; // 鼠标还在这个触发器内部忽略 if (e.relatedTarget trigger.contains(e.relatedTarget)) return; hideTip(); });这段判断是整个委托方案的核心。e.relatedTarget指向鼠标即将进入的那个元素如果它还在触发器内部说明只是在子节点间穿梭不该关掉提示。顺带说一个边界情况relatedTarget在鼠标移出浏览器窗口时是null。上面的写法里e.relatedTarget ...保证了null时不会报错并且会正常执行隐藏——这是想要的行为。2.2 坐标系对齐视口坐标、文档坐标与 getBoundingClientRect定位出错九成是坐标系搞混了。getBoundingClientRect()返回的是相对于视口的坐标页面滚动后同一个元素的rect.top会变因为它在视口里的位置变了。而element.offsetTop返回的是相对于offsetParent的文档坐标。如果你把提示框设为position: fixed那它也是相对视口的直接用getBoundingClientRect()的值就对了不要加scrollY。// fixed 定位直接用视口坐标 tip.style.left rect.left px; tip.style.top rect.top px;如果你用position: absolute且父级是body那它相对的是文档左上角必须补上滚动距离// absolute 定位视口坐标 滚动距离 tip.style.left (rect.left window.scrollX) px; tip.style.top (rect.top window.scrollY) px;这两个写法混用是高频 bug。症状很典型页面不滚动时一切正常一滚动提示框就跟按钮分家了滚得越远跑得越偏。我的建议是统一用position: fixed好处是滚动时不需要重算文档偏移代码里少一个变量就少一处出错点。代价是要在滚动时重新定位这个后面用requestAnimationFrame节流解决。还有一个细节算宽度时用offsetWidth还是getBoundingClientRect().width后者是小数受transform: scale影响前者是取整后的布局宽度。做像素定位用offsetWidth更稳定而且不受缩放动画干扰。2.3 层叠与裁剪z-index 和 overflow 造成的两个经典事故事故一提示框被裁掉。触发器在一个overflow: hidden或overflow: auto的容器里表格滚动区、卡片、抽屉提示框作为子元素会被裁。解决办法是把提示框节点直接挂到document.body上让它脱离所有祖先的裁剪。这也是为什么我坚持用单例节点的思路——页面上永远只有一个提示 DOM挂在 body 下所有按钮共用通过修改位置和文本复用它。既避免了裁剪又省掉了频繁创建销毁的开销。事故二fixed定位失效。这是最阴的一个。按规范任何祖先元素只要设置了transform、filter、perspective、will-change: transform、contain: paint这类属性就会创建新的包含块其内部的position: fixed元素不再相对视口定位而是相对这个祖先定位。表现是提示框位置整体偏移偏移量取决于那个祖先在页面上的位置。如果提示框节点挂在body下只要body和html上没有被乱加transform就不受影响。但如果挂在某个组件容器里就很容易中招。这也是我把节点挂 body 的第二个理由。z-index的问题相对简单数值给够就行我一般用9999。但要注意如果触发器的祖先创建了层叠上下文比如设了position: relative加z-index: 1而提示框没挂 body那z-index再大也跳不出那个上下文。挂 body 依然是解法。3. 手写一个可复用的提示组件前面把坑摸清楚了现在开始写。目标是一个文件、零依赖、支持动态节点、支持方向翻转、支持键盘、能在滚动时跟随。3.1 HTML 结构与语义属性触发器只需要一个数据属性文本和方向都放在属性里不侵入业务结构button classbtn>function ensureTip() { if (tipEl) return tipEl; tipEl document.createElement(div); tipEl.className ui-tip; tipEl.id ui-tip-global; tipEl.setAttribute(role, tooltip); document.body.appendChild(tipEl); return tipEl; }roletooltip和无障碍的关联是配套的显示时给触发器加aria-describedby指向提示框 id隐藏时移除。这样屏幕阅读器读到按钮时会把提示文本一起读出来。注意aria-describedby只在提示可见期间加否则会一直念。3.2 样式层定位、箭头与过渡.ui-tip { position: fixed; left: 0; top: 0; z-index: 9999; max-width: 260px; padding: 7px 11px; font-size: 13px; line-height: 1.5; color: #fff; background: #2b2f36; border-radius: 6px; box-shadow: 0 4px 14px rgba(0, 0, 0, .18); white-space: normal; word-break: break-word; pointer-events: none; opacity: 0; transform: translate3d(0, 4px, 0); transition: opacity .15s ease, transform .15s ease; will-change: transform, opacity; } .ui-tip.is-show { opacity: 1; transform: translate3d(0, 0, 0); } /* 箭头用一个旋转的小方块比 border 三角更好控制圆角和阴影 */ .ui-tip::after { content: ; position: absolute; width: 8px; height: 8px; background: inherit; border-radius: 1px; transform: rotate(45deg); } .ui-tip[data-placementtop]::after { left: var(--arrow-x, 50%); bottom: -4px; margin-left: -4px; } .ui-tip[data-placementbottom]::after { left: var(--arrow-x, 50%); top: -4px; margin-left: -4px; } .ui-tip[data-placementleft]::after { top: var(--arrow-y, 50%); right: -4px; margin-top: -4px; } .ui-tip[data-placementright]::after { top: var(--arrow-y, 50%); left: -4px; margin-top: -4px; }这里有两个设计决策值得说明。用旋转方块而不是border三角是因为border三角没法继承background也没法加圆角在深色背景加阴影的组合下会显得很生硬方块用background: inherit直接复用背景色视觉上完全一致。箭头位置用 CSS 变量--arrow-x控制JS 只负责设这个变量不用在样式和脚本之间反复算left的原值。这是个小技巧好处是 CSS 里的margin-left: -4px补偿逻辑和left值解耦了改样式不用改脚本。pointer-events: none再强调一遍这是防闪烁的核心。3.3 逻辑层单例节点与定时器状态机整个组件就三个状态空闲、等待显示、已显示。用一个变量记录当前触发器两个定时器控制延迟。const SHOW_DELAY 260; // 悬停多久才显示 const HIDE_DELAY 80; // 移开后多久隐藏 const OFFSET 10; // 提示框与按钮的间距 const EDGE_PADDING 8; // 距离视口边缘的最小留白 let tipEl null; let currentTrigger null; let showTimer 0; let hideTimer 0; let placed top;延迟值的选择有讲究。SHOW_DELAY太短比如 0鼠标横扫页面时会连续弹提示视觉噪音很大太长比如 800 毫秒用户已经开始思考“这图标啥意思”了才弹出来等于没帮上忙。200 到 300 毫秒是常见区间我用 260。HIDE_DELAY不是 0 而是 80 毫秒是为了容忍手抖。用户的鼠标轨迹不是直线从按钮边缘擦出去的瞬间可能又移回来如果立刻隐藏就会闪一下。给一个几十毫秒的缓冲只要在这段时间内重新mouseenter就清掉隐藏定时器视觉上完全无感。3.4 完整实现代码(function () { const SHOW_DELAY 260; const HIDE_DELAY 80; const OFFSET 10; const EDGE_PADDING 8; let tipEl null; let currentTrigger null; let showTimer 0; let hideTimer 0; function ensureTip() { if (tipEl) return tipEl; tipEl document.createElement(div); tipEl.className ui-tip; tipEl.id ui-tip-global; tipEl.setAttribute(role, tooltip); document.body.appendChild(tipEl); return tipEl; } // 计算最终方向空间不够就翻转 function resolvePlacement(rect, tw, th, prefer) { const vw document.documentElement.clientWidth; const vh document.documentElement.clientHeight; function room(place) { if (place top) return rect.top; if (place bottom) return vh - rect.bottom; if (place left) return rect.left; return vw - rect.right; } function need(place) { return (place top || place bottom) ? th OFFSET EDGE_PADDING : tw OFFSET EDGE_PADDING; } if (room(prefer) need(prefer)) return prefer; const opposite { top: bottom, bottom: top, left: right, right: left }; if (room(opposite[prefer]) need(opposite[prefer])) return opposite[prefer]; // 两边都放不下退化为空间更大的那一侧 return room(prefer) room(opposite[prefer]) ? prefer : opposite[prefer]; } function place(trigger, prefer) { const tip ensureTip(); const rect trigger.getBoundingClientRect(); const tw tip.offsetWidth; const th tip.offsetHeight; const vw document.documentElement.clientWidth; const vh document.documentElement.clientHeight; const placement resolvePlacement(rect, tw, th, prefer || top); tip.setAttribute(data-placement, placement); let left 0; let top 0; if (placement top || placement bottom) { left rect.left rect.width / 2 - tw / 2; // 水平方向夹到视口内 left Math.max(EDGE_PADDING, Math.min(left, vw - tw - EDGE_PADDING)); top placement top ? rect.top - th - OFFSET : rect.bottom OFFSET; } else { top rect.top rect.height / 2 - th / 2; top Math.max(EDGE_PADDING, Math.min(top, vh - th - EDGE_PADDING)); left placement left ? rect.left - tw - OFFSET : rect.right OFFSET; } tip.style.left left px; tip.style.top top px; // 箭头对齐触发器中心并限制在圆角安全区内 if (placement top || placement bottom) { const center rect.left rect.width / 2 - left; const safe Math.max(12, Math.min(center, tw - 12)); tip.style.setProperty(--arrow-x, safe px); } else { const center rect.top rect.height / 2 - top; const safe Math.max(12, Math.min(center, th - 12)); tip.style.setProperty(--arrow-y, safe px); } } function show(trigger) { const text trigger.getAttribute(data-tip); if (!text) return; currentTrigger trigger; const tip ensureTip(); tip.textContent text; // 先渲染出来量尺寸再加显示类避免从 0 尺寸开始算 tip.style.opacity 0; tip.classList.remove(is-show); place(trigger, trigger.getAttribute(data-tip-placement)); requestAnimationFrame(function () { if (currentTrigger ! trigger) return; tip.classList.add(is-show); trigger.setAttribute(aria-describedby, tip.id); }); } function hide() { const tip ensureTip(); tip.classList.remove(is-show); if (currentTrigger) { currentTrigger.removeAttribute(aria-describedby); currentTrigger null; } } function scheduleShow(trigger) { clearTimeout(hideTimer); clearTimeout(showTimer); if (currentTrigger trigger) return; showTimer setTimeout(function () { show(trigger); }, SHOW_DELAY); } function scheduleHide() { clearTimeout(showTimer); clearTimeout(hideTimer); hideTimer setTimeout(hide, HIDE_DELAY); } // 滚动或缩放时跟随注意捕获阶段才能拿到内层滚动容器的滚动 let ticking false; function onScrollOrResize() { if (!currentTrigger || ticking) return; ticking true; requestAnimationFrame(function () { ticking false; if (currentTrigger) { place(currentTrigger, currentTrigger.getAttribute(data-tip-placement)); } }); } // 事件委托 document.addEventListener(mouseover, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; // 从触发器内部子元素冒泡上来的重复事件 if (e.relatedTarget trigger.contains(e.relatedTarget)) return; scheduleShow(trigger); }); document.addEventListener(mouseout, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (e.relatedTarget trigger.contains(e.relatedTarget)) return; if (currentTrigger trigger) scheduleHide(); }); document.addEventListener(focusin, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (e.target.matches(:focus-visible)) scheduleShow(trigger); }); document.addEventListener(focusout, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (currentTrigger trigger) scheduleHide(); }); document.addEventListener(keydown, function (e) { if (e.key Escape currentTrigger) { clearTimeout(showTimer); clearTimeout(hideTimer); hide(); } }); window.addEventListener(scroll, onScrollOrResize, { passive: true, capture: true }); window.addEventListener(resize, onScrollOrResize, { passive: true }); })();3.5 偏移量与翻转判定是怎么算出来的OFFSET 10这个值不是拍脑袋。提示框到按钮之间留空是为了视觉上“分离”但留太多会让人不确定这提示到底属于哪个按钮。8 到 12 像素是舒适区10 是折中。如果按钮本身有阴影或边框可以适当加到 12。resolvePlacement的逻辑分三层值得逐层看第一层首选方向够不够。判断标准是触发器到视口对应边的距离减去提示框尺寸、间距和留白。比如首选top需要rect.top th OFFSET EDGE_PADDING。注意这里用rect.top而不是rect.top - scrollY因为rect已经是视口坐标了。第二层对面够不够。首选放不下就翻到bottom。这一步解决了“页面顶部第一行的按钮提示跑出屏幕”的问题。第三层都放不下怎么办。极端情况是视口特别矮提示框本身高度就超过了剩余空间。这时退化为“选空间更大的那边”接受提示框部分溢出。这是有意为之——总比固定在某一侧完全看不到强。水平方向的left计算完还要做一次夹取把提示框限制在[EDGE_PADDING, vw - tw - EDGE_PADDING]区间内。这一步是给页面最左和最右的按钮准备的按钮贴着左边缘时居中计算会得出负的left夹取后提示框左对齐到 8 像素虽然不再严格居中但至少完整可见。箭头的位置单独算用rect 中心 - 提示框 left得到箭头在提示框内的相对位置再用Math.max(12, Math.min(center, tw - 12))夹一下。12 这个数字对应 6 像素圆角加 8 像素箭头宽度的一半左右保证箭头不会跑到圆角外面去。夹完之后即使提示框被夹到边缘箭头仍然指向按钮视觉关联不丢。4. 常见故障与排查实录4.1 闪烁、残留、错位三类高频问题闪烁几乎只有一个原因提示框挡住了鼠标。链条是这样的——提示框显示 → 它盖在鼠标位置 → 浏览器认为鼠标离开了按钮 → 触发隐藏 → 提示框消失 → 鼠标又在按钮上了 → 显示。整个循环每秒能跑好几次。解法就是pointer-events: none。如果加了还闪检查是不是提示框的箭头部分漏了或者提示框上有一个绝对定位的包裹层没继承这个属性。残留指的是鼠标已经移到别的按钮或者移出窗口提示框还挂在那。最常见的原因是定时器没清理。比如鼠标快速划过 A、B、C 三个按钮A 的显示定时器还没执行完就进了 B如果没有clearTimeout(showTimer)A 的定时器到点会把提示框显示出来而此时用户已经在 C 上了。代码里scheduleShow开头就clearTimeout(hideTimer)和clearTimeout(showTimer)就是为了断掉这些悬空的定时器。错位的花样最多。前面讲过fixed加scrollY是最经典的一种。第二种是祖先有transform导致fixed的包含块变了。第三种是在iframe里getBoundingClientRect拿到的是相对 iframe 视口的坐标如果提示框挂在顶层body上两边坐标系差着 iframe 的位置。第四种是zoom或者浏览器缩放offsetWidth和rect.width会有偏差。4.2 问题速查表现象最可能的原因处理办法提示框疯狂闪烁提示框盖住了鼠标加pointer-events: none包括箭头伪元素鼠标移开提示框还在隐藏定时器没清理或被覆盖在scheduleShow里先clearTimeout(hideTimer)鼠标快速划过时弹出错的内容定时器串了记录当前触发器并比对回调里校验currentTrigger提示框被容器切掉一半祖先overflow: hidden/auto节点挂到document.body下位置整体偏移一大截祖先有transform/filter同上挂 body页面滚动后提示框跟丢了用了绝对定位但没加滚动量改position: fixed或补scrollX/scrollY长文本把提示框撑成一整行缺max-width或white-space处理max-widthwhite-space: normalwidth: max-contentz-index: 9999不起作用祖先创建了层叠上下文节点挂 body移动端点一下弹出来再也不消失触屏 hover 语义不同判断matchMedia((hover: hover))触屏改点击触发表格里上千行卡顿每个按钮都绑了监听改成事件委托页面只挂一次键盘 Tab 聚焦看不到提示只监听了鼠标事件补focusin/focusout判断:focus-visible4.3 几条踩出来的经验在show()里先量尺寸再显示顺序不能反。我的做法是先把opacity设 0、移除is-show类设好textContent和位置然后在requestAnimationFrame里加is-show。原因是提示框内容变化会改变尺寸如果在隐藏状态下visibility: hidden或display: none根本量不到尺寸。用opacity: 0而不是display: none就是为了保住布局offsetWidth才有值。requestAnimationFrame那一层不是为了动画是为了避免同一帧内读写了两次布局。有些场景下先设textContent再读offsetWidth浏览器会强制同步重排。放到 rAF 里能让重排和绘制合并。另外里面那句if (currentTrigger ! trigger) return;是防御性的用户手太快时可能出现“量尺寸期间触发器已经切走”的情况。滚动监听一定要用捕获阶段。window.addEventListener(scroll, fn, { capture: true })才能收到所有内层滚动容器比如表格的横向滚动区、抽屉的滚动区的滚动事件。默认的冒泡阶段收不到因为它们不冒泡。这个坑我在一个带横向滚动表格的后台系统里踩过按钮在横向滚动时提示框不跟着走加了capture: true立刻好。focus-visible的判断别省。直接监听focusin会导致鼠标点击按钮时也弹出提示因为点击会让按钮获得焦点。加上e.target.matches(:focus-visible)就只在键盘导航时触发鼠标点击不会弹。这个伪类现在的浏览器支持已经很好了老浏览器降级成“都弹”也不影响功能。5. 动态列表与多端适配5.1 事件委托一千个按钮只挂一个监听后台系统的表格操作列一页五十行每行三四个图标按钮就是两百个监听器。如果再加个“加载更多”数字还会涨。为每个按钮单独绑mouseenter/mouseleave的成本不只是内存更麻烦的是动态插入的节点要记得重新绑一不小心就漏了。委托方案把监听挂在document上靠closest([data-tip])定位触发器。代价是必须用会冒泡的mouseover/mouseout然后手动处理relatedTarget。这个交换是划算的——多两行判断省掉全部生命周期管理。// 动态插入的按钮不需要任何额外处理只要有>const canHover window.matchMedia((hover: hover) and (pointer: fine)).matches;canHover为真时走鼠标逻辑为假时触屏、触控笔改成“点一下显示再点一下或点空白处关闭”。实现上可以监听pointerdown判断e.pointerType touch手动调用show然后给document加一个一次性的pointerdown监听来关闭。document.addEventListener(pointerdown, function (e) { if (e.pointerType ! touch) return; const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) { hide(); return; } if (currentTrigger trigger) { hide(); } else { show(trigger); } });注意这里的show直接调用不走延迟。触屏是明确的点击意图加延迟反而让用户觉得卡。这也是为什么我把延迟放在scheduleShow里而不是show里——两种触发路径共用一个显示函数但延迟策略各自决定。键盘这条通道主要是focusin/focusout加Escape。Escape关提示是个小细节但符合用户预期——弹出层按 Esc 关闭是通用习惯。虽然提示框不是模态加这一条不费事。还有一个无障碍上的注意点有些辅助技术会把roletooltip的元素内容当作描述读出来如果提示文本和按钮的aria-label重复就会念两遍。我的做法是图标按钮用aria-label给出简洁名称>
1. 先把需求拆开看提示框要解决什么问题“js实现鼠标放上按钮出现提示”这句话本身信息很少但它背后要处理的事情比想象中多。一个按钮上放一段说明文字鼠标移上去显示、移开消失——听起来十几行 JS 就能收工可真放到项目里用户会立刻抛出更多要求提示不能挡住鼠标否则会一闪一闪按钮在页面底部时提示不能跑出屏幕按钮放在一个overflow: hidden的卡片里提示不能被裁掉一半页面滚动时提示要跟着按钮走不能停在原地列表里动态生成的几百个按钮也得能用还有键盘用户按 Tab 键聚焦到按钮时同样应该看到提示。所以这篇文章讲的不是“怎么把一段文字显示出来”而是鼠标悬停提示tooltip这套交互在真实页面里的完整实现路径事件该怎么选、坐标该怎么算、层级和裁剪怎么绕开、什么时候该翻转方向、动态节点怎么处理、移动端和键盘怎么兼容。内容会从最基础的原生属性一路写到可以复用的单例组件代码都是能直接贴进项目跑的中间会穿插我在实际项目里踩过的坑比如提示框被祖先元素的transform搞得定位全乱、mouseover冒泡导致的疯狂闪烁。适合谁看刚接触 DOM 事件、想搞清楚“事件为什么会重复触发”的新手正在做后台系统、表格操作列里塞了一堆图标按钮、需要批量加提示的中级开发者以及想判断“这东西到底要不要自己写”的技术负责人。三种人都能从下面几节里拿到东西只是关注点不同新手重点看第 2 节的事件差异和第 3 节的完整代码中级看第 4 节的排查表和第 5 节的委托模式负责人直接看第 1.2 节和最后一节的选型判断。1.1 一个按钮上的提示用户真正需要的是什么先想清楚提示框存在的意义。它不是装饰是给一个信息密度不够的控件补充上下文。图标按钮保存、导出、删除没有文字标签用户靠图标猜表单里某个开关的影响范围不直观表格里某个状态值需要解释。这些场景的共同点是主界面必须保持紧凑补充信息只能在“用户主动关注”的那一刻出现。这决定了三个硬指标。第一是触发要克制鼠标扫过页面时不能到处弹出提示否则页面像打地鼠一般要加 200 到 400 毫秒的延迟用户只是路过就不弹。第二是时机要准确鼠标真正停留在按钮上才开始计时鼠标从按钮移开、哪怕只是移到按钮内部的图标上也不能算移出。第三是消失要干脆移开就收不能拖泥带水留着挡住别的元素。还有一个容易被忽略的点提示框是辅助信息不是关键信息。这意味着它丢了也不会让功能不可用所以实现上可以接受“极端情况下位置略微偏移”但不能接受“提示框挡住按钮导致用户点不到”。后面讲pointer-events: none就是为了这条。1.2 三条技术路线的取舍原生 title、CSS 伪元素、JS 组件在动手写 JS 之前先把可选方案摆清楚不然很容易写了一堆代码发现还不如一行title属性。方案实现成本样式可控性定位能力适用场景原生title属性零成本加个属性就行完全不可控系统渲染跟随鼠标不可控内部工具、后台原型、说明文字很短CSS 伪元素::after>.tip-btn { position: relative; } .tip-btn::after { content: attr(data-tip); position: absolute; left: 50%; bottom: calc(100% 8px); transform: translateX(-50%); max-width: 240px; width: max-content; padding: 6px 10px; font-size: 13px; line-height: 1.5; color: #fff; background: #2b2f36; border-radius: 6px; white-space: normal; opacity: 0; visibility: hidden; transition: opacity .15s ease, visibility .15s ease; pointer-events: none; z-index: 10; } .tip-btn:hover::after, .tip-btn:focus-visible::after { opacity: 1; visibility: visible; }注意width: max-content配max-width这个组合这是让长文本自动换行的关键只写max-width在部分场景下伪元素宽度会被父元素挤压。另外pointer-events: none必须加否则伪元素盖在鼠标上会导致:hover失效进入“显示-隐藏-显示”的抖动循环这个问题我在早期项目里遇到过排查了半天。伪元素方案的死穴有两个一是父级有overflow: hidden就必被裁因为它是子元素二是贴边不能翻转按钮在页面最上面时向上的提示直接跑到视口外。这两个限制在实际页面里出现频率很高一旦碰到就只能换 JS 方案。2. 底层机制拆解事件、坐标、层级写 JS 提示框绕不开三件事用什么事件监听、坐标怎么换算、层级怎么保证。这三块任何一块理解偏了代码都能跑但会出各种奇怪问题。2.1 mouseenter/mouseleave 与 mouseover/mouseout 的真实差异这是新手最容易混的一组。两组事件看起来都是“进出”但行为完全不同。mouseover和mouseout是会冒泡的而且鼠标在元素内部的子节点之间移动时也会触发。假设按钮结构是buttonsvgpath/svg文字/button鼠标从按钮空白处移到 svg 上会先触发按钮的mouseout因为离开了按钮的文本区域再触发 svg 的mouseover并冒泡到按钮。如果你的逻辑是“触发 mouseover 显示、mouseout 隐藏”那么鼠标在按钮内部稍微动一下提示就会疯狂闪。mouseenter和mouseleave是不冒泡的而且浏览器帮你处理了子节点的问题——鼠标从按钮移到按钮内部的 svg不算离开。所以直接给按钮绑定时这两个是正确选择。但这里有个反转如果你要用事件委托一个监听管住页面上所有按钮第 5 节会讲mouseenter就完全不能用了因为它不冒泡绑在document上永远收不到。这时候必须回到mouseover/mouseout靠判断relatedTarget来消除子节点干扰document.addEventListener(mouseout, function (e) { const trigger e.target.closest([data-tip]); if (!trigger) return; // 鼠标还在这个触发器内部忽略 if (e.relatedTarget trigger.contains(e.relatedTarget)) return; hideTip(); });这段判断是整个委托方案的核心。e.relatedTarget指向鼠标即将进入的那个元素如果它还在触发器内部说明只是在子节点间穿梭不该关掉提示。顺带说一个边界情况relatedTarget在鼠标移出浏览器窗口时是null。上面的写法里e.relatedTarget ...保证了null时不会报错并且会正常执行隐藏——这是想要的行为。2.2 坐标系对齐视口坐标、文档坐标与 getBoundingClientRect定位出错九成是坐标系搞混了。getBoundingClientRect()返回的是相对于视口的坐标页面滚动后同一个元素的rect.top会变因为它在视口里的位置变了。而element.offsetTop返回的是相对于offsetParent的文档坐标。如果你把提示框设为position: fixed那它也是相对视口的直接用getBoundingClientRect()的值就对了不要加scrollY。// fixed 定位直接用视口坐标 tip.style.left rect.left px; tip.style.top rect.top px;如果你用position: absolute且父级是body那它相对的是文档左上角必须补上滚动距离// absolute 定位视口坐标 滚动距离 tip.style.left (rect.left window.scrollX) px; tip.style.top (rect.top window.scrollY) px;这两个写法混用是高频 bug。症状很典型页面不滚动时一切正常一滚动提示框就跟按钮分家了滚得越远跑得越偏。我的建议是统一用position: fixed好处是滚动时不需要重算文档偏移代码里少一个变量就少一处出错点。代价是要在滚动时重新定位这个后面用requestAnimationFrame节流解决。还有一个细节算宽度时用offsetWidth还是getBoundingClientRect().width后者是小数受transform: scale影响前者是取整后的布局宽度。做像素定位用offsetWidth更稳定而且不受缩放动画干扰。2.3 层叠与裁剪z-index 和 overflow 造成的两个经典事故事故一提示框被裁掉。触发器在一个overflow: hidden或overflow: auto的容器里表格滚动区、卡片、抽屉提示框作为子元素会被裁。解决办法是把提示框节点直接挂到document.body上让它脱离所有祖先的裁剪。这也是为什么我坚持用单例节点的思路——页面上永远只有一个提示 DOM挂在 body 下所有按钮共用通过修改位置和文本复用它。既避免了裁剪又省掉了频繁创建销毁的开销。事故二fixed定位失效。这是最阴的一个。按规范任何祖先元素只要设置了transform、filter、perspective、will-change: transform、contain: paint这类属性就会创建新的包含块其内部的position: fixed元素不再相对视口定位而是相对这个祖先定位。表现是提示框位置整体偏移偏移量取决于那个祖先在页面上的位置。如果提示框节点挂在body下只要body和html上没有被乱加transform就不受影响。但如果挂在某个组件容器里就很容易中招。这也是我把节点挂 body 的第二个理由。z-index的问题相对简单数值给够就行我一般用9999。但要注意如果触发器的祖先创建了层叠上下文比如设了position: relative加z-index: 1而提示框没挂 body那z-index再大也跳不出那个上下文。挂 body 依然是解法。3. 手写一个可复用的提示组件前面把坑摸清楚了现在开始写。目标是一个文件、零依赖、支持动态节点、支持方向翻转、支持键盘、能在滚动时跟随。3.1 HTML 结构与语义属性触发器只需要一个数据属性文本和方向都放在属性里不侵入业务结构button classbtn>function ensureTip() { if (tipEl) return tipEl; tipEl document.createElement(div); tipEl.className ui-tip; tipEl.id ui-tip-global; tipEl.setAttribute(role, tooltip); document.body.appendChild(tipEl); return tipEl; }roletooltip和无障碍的关联是配套的显示时给触发器加aria-describedby指向提示框 id隐藏时移除。这样屏幕阅读器读到按钮时会把提示文本一起读出来。注意aria-describedby只在提示可见期间加否则会一直念。3.2 样式层定位、箭头与过渡.ui-tip { position: fixed; left: 0; top: 0; z-index: 9999; max-width: 260px; padding: 7px 11px; font-size: 13px; line-height: 1.5; color: #fff; background: #2b2f36; border-radius: 6px; box-shadow: 0 4px 14px rgba(0, 0, 0, .18); white-space: normal; word-break: break-word; pointer-events: none; opacity: 0; transform: translate3d(0, 4px, 0); transition: opacity .15s ease, transform .15s ease; will-change: transform, opacity; } .ui-tip.is-show { opacity: 1; transform: translate3d(0, 0, 0); } /* 箭头用一个旋转的小方块比 border 三角更好控制圆角和阴影 */ .ui-tip::after { content: ; position: absolute; width: 8px; height: 8px; background: inherit; border-radius: 1px; transform: rotate(45deg); } .ui-tip[data-placementtop]::after { left: var(--arrow-x, 50%); bottom: -4px; margin-left: -4px; } .ui-tip[data-placementbottom]::after { left: var(--arrow-x, 50%); top: -4px; margin-left: -4px; } .ui-tip[data-placementleft]::after { top: var(--arrow-y, 50%); right: -4px; margin-top: -4px; } .ui-tip[data-placementright]::after { top: var(--arrow-y, 50%); left: -4px; margin-top: -4px; }这里有两个设计决策值得说明。用旋转方块而不是border三角是因为border三角没法继承background也没法加圆角在深色背景加阴影的组合下会显得很生硬方块用background: inherit直接复用背景色视觉上完全一致。箭头位置用 CSS 变量--arrow-x控制JS 只负责设这个变量不用在样式和脚本之间反复算left的原值。这是个小技巧好处是 CSS 里的margin-left: -4px补偿逻辑和left值解耦了改样式不用改脚本。pointer-events: none再强调一遍这是防闪烁的核心。3.3 逻辑层单例节点与定时器状态机整个组件就三个状态空闲、等待显示、已显示。用一个变量记录当前触发器两个定时器控制延迟。const SHOW_DELAY 260; // 悬停多久才显示 const HIDE_DELAY 80; // 移开后多久隐藏 const OFFSET 10; // 提示框与按钮的间距 const EDGE_PADDING 8; // 距离视口边缘的最小留白 let tipEl null; let currentTrigger null; let showTimer 0; let hideTimer 0; let placed top;延迟值的选择有讲究。SHOW_DELAY太短比如 0鼠标横扫页面时会连续弹提示视觉噪音很大太长比如 800 毫秒用户已经开始思考“这图标啥意思”了才弹出来等于没帮上忙。200 到 300 毫秒是常见区间我用 260。HIDE_DELAY不是 0 而是 80 毫秒是为了容忍手抖。用户的鼠标轨迹不是直线从按钮边缘擦出去的瞬间可能又移回来如果立刻隐藏就会闪一下。给一个几十毫秒的缓冲只要在这段时间内重新mouseenter就清掉隐藏定时器视觉上完全无感。3.4 完整实现代码(function () { const SHOW_DELAY 260; const HIDE_DELAY 80; const OFFSET 10; const EDGE_PADDING 8; let tipEl null; let currentTrigger null; let showTimer 0; let hideTimer 0; function ensureTip() { if (tipEl) return tipEl; tipEl document.createElement(div); tipEl.className ui-tip; tipEl.id ui-tip-global; tipEl.setAttribute(role, tooltip); document.body.appendChild(tipEl); return tipEl; } // 计算最终方向空间不够就翻转 function resolvePlacement(rect, tw, th, prefer) { const vw document.documentElement.clientWidth; const vh document.documentElement.clientHeight; function room(place) { if (place top) return rect.top; if (place bottom) return vh - rect.bottom; if (place left) return rect.left; return vw - rect.right; } function need(place) { return (place top || place bottom) ? th OFFSET EDGE_PADDING : tw OFFSET EDGE_PADDING; } if (room(prefer) need(prefer)) return prefer; const opposite { top: bottom, bottom: top, left: right, right: left }; if (room(opposite[prefer]) need(opposite[prefer])) return opposite[prefer]; // 两边都放不下退化为空间更大的那一侧 return room(prefer) room(opposite[prefer]) ? prefer : opposite[prefer]; } function place(trigger, prefer) { const tip ensureTip(); const rect trigger.getBoundingClientRect(); const tw tip.offsetWidth; const th tip.offsetHeight; const vw document.documentElement.clientWidth; const vh document.documentElement.clientHeight; const placement resolvePlacement(rect, tw, th, prefer || top); tip.setAttribute(data-placement, placement); let left 0; let top 0; if (placement top || placement bottom) { left rect.left rect.width / 2 - tw / 2; // 水平方向夹到视口内 left Math.max(EDGE_PADDING, Math.min(left, vw - tw - EDGE_PADDING)); top placement top ? rect.top - th - OFFSET : rect.bottom OFFSET; } else { top rect.top rect.height / 2 - th / 2; top Math.max(EDGE_PADDING, Math.min(top, vh - th - EDGE_PADDING)); left placement left ? rect.left - tw - OFFSET : rect.right OFFSET; } tip.style.left left px; tip.style.top top px; // 箭头对齐触发器中心并限制在圆角安全区内 if (placement top || placement bottom) { const center rect.left rect.width / 2 - left; const safe Math.max(12, Math.min(center, tw - 12)); tip.style.setProperty(--arrow-x, safe px); } else { const center rect.top rect.height / 2 - top; const safe Math.max(12, Math.min(center, th - 12)); tip.style.setProperty(--arrow-y, safe px); } } function show(trigger) { const text trigger.getAttribute(data-tip); if (!text) return; currentTrigger trigger; const tip ensureTip(); tip.textContent text; // 先渲染出来量尺寸再加显示类避免从 0 尺寸开始算 tip.style.opacity 0; tip.classList.remove(is-show); place(trigger, trigger.getAttribute(data-tip-placement)); requestAnimationFrame(function () { if (currentTrigger ! trigger) return; tip.classList.add(is-show); trigger.setAttribute(aria-describedby, tip.id); }); } function hide() { const tip ensureTip(); tip.classList.remove(is-show); if (currentTrigger) { currentTrigger.removeAttribute(aria-describedby); currentTrigger null; } } function scheduleShow(trigger) { clearTimeout(hideTimer); clearTimeout(showTimer); if (currentTrigger trigger) return; showTimer setTimeout(function () { show(trigger); }, SHOW_DELAY); } function scheduleHide() { clearTimeout(showTimer); clearTimeout(hideTimer); hideTimer setTimeout(hide, HIDE_DELAY); } // 滚动或缩放时跟随注意捕获阶段才能拿到内层滚动容器的滚动 let ticking false; function onScrollOrResize() { if (!currentTrigger || ticking) return; ticking true; requestAnimationFrame(function () { ticking false; if (currentTrigger) { place(currentTrigger, currentTrigger.getAttribute(data-tip-placement)); } }); } // 事件委托 document.addEventListener(mouseover, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; // 从触发器内部子元素冒泡上来的重复事件 if (e.relatedTarget trigger.contains(e.relatedTarget)) return; scheduleShow(trigger); }); document.addEventListener(mouseout, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (e.relatedTarget trigger.contains(e.relatedTarget)) return; if (currentTrigger trigger) scheduleHide(); }); document.addEventListener(focusin, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (e.target.matches(:focus-visible)) scheduleShow(trigger); }); document.addEventListener(focusout, function (e) { const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) return; if (currentTrigger trigger) scheduleHide(); }); document.addEventListener(keydown, function (e) { if (e.key Escape currentTrigger) { clearTimeout(showTimer); clearTimeout(hideTimer); hide(); } }); window.addEventListener(scroll, onScrollOrResize, { passive: true, capture: true }); window.addEventListener(resize, onScrollOrResize, { passive: true }); })();3.5 偏移量与翻转判定是怎么算出来的OFFSET 10这个值不是拍脑袋。提示框到按钮之间留空是为了视觉上“分离”但留太多会让人不确定这提示到底属于哪个按钮。8 到 12 像素是舒适区10 是折中。如果按钮本身有阴影或边框可以适当加到 12。resolvePlacement的逻辑分三层值得逐层看第一层首选方向够不够。判断标准是触发器到视口对应边的距离减去提示框尺寸、间距和留白。比如首选top需要rect.top th OFFSET EDGE_PADDING。注意这里用rect.top而不是rect.top - scrollY因为rect已经是视口坐标了。第二层对面够不够。首选放不下就翻到bottom。这一步解决了“页面顶部第一行的按钮提示跑出屏幕”的问题。第三层都放不下怎么办。极端情况是视口特别矮提示框本身高度就超过了剩余空间。这时退化为“选空间更大的那边”接受提示框部分溢出。这是有意为之——总比固定在某一侧完全看不到强。水平方向的left计算完还要做一次夹取把提示框限制在[EDGE_PADDING, vw - tw - EDGE_PADDING]区间内。这一步是给页面最左和最右的按钮准备的按钮贴着左边缘时居中计算会得出负的left夹取后提示框左对齐到 8 像素虽然不再严格居中但至少完整可见。箭头的位置单独算用rect 中心 - 提示框 left得到箭头在提示框内的相对位置再用Math.max(12, Math.min(center, tw - 12))夹一下。12 这个数字对应 6 像素圆角加 8 像素箭头宽度的一半左右保证箭头不会跑到圆角外面去。夹完之后即使提示框被夹到边缘箭头仍然指向按钮视觉关联不丢。4. 常见故障与排查实录4.1 闪烁、残留、错位三类高频问题闪烁几乎只有一个原因提示框挡住了鼠标。链条是这样的——提示框显示 → 它盖在鼠标位置 → 浏览器认为鼠标离开了按钮 → 触发隐藏 → 提示框消失 → 鼠标又在按钮上了 → 显示。整个循环每秒能跑好几次。解法就是pointer-events: none。如果加了还闪检查是不是提示框的箭头部分漏了或者提示框上有一个绝对定位的包裹层没继承这个属性。残留指的是鼠标已经移到别的按钮或者移出窗口提示框还挂在那。最常见的原因是定时器没清理。比如鼠标快速划过 A、B、C 三个按钮A 的显示定时器还没执行完就进了 B如果没有clearTimeout(showTimer)A 的定时器到点会把提示框显示出来而此时用户已经在 C 上了。代码里scheduleShow开头就clearTimeout(hideTimer)和clearTimeout(showTimer)就是为了断掉这些悬空的定时器。错位的花样最多。前面讲过fixed加scrollY是最经典的一种。第二种是祖先有transform导致fixed的包含块变了。第三种是在iframe里getBoundingClientRect拿到的是相对 iframe 视口的坐标如果提示框挂在顶层body上两边坐标系差着 iframe 的位置。第四种是zoom或者浏览器缩放offsetWidth和rect.width会有偏差。4.2 问题速查表现象最可能的原因处理办法提示框疯狂闪烁提示框盖住了鼠标加pointer-events: none包括箭头伪元素鼠标移开提示框还在隐藏定时器没清理或被覆盖在scheduleShow里先clearTimeout(hideTimer)鼠标快速划过时弹出错的内容定时器串了记录当前触发器并比对回调里校验currentTrigger提示框被容器切掉一半祖先overflow: hidden/auto节点挂到document.body下位置整体偏移一大截祖先有transform/filter同上挂 body页面滚动后提示框跟丢了用了绝对定位但没加滚动量改position: fixed或补scrollX/scrollY长文本把提示框撑成一整行缺max-width或white-space处理max-widthwhite-space: normalwidth: max-contentz-index: 9999不起作用祖先创建了层叠上下文节点挂 body移动端点一下弹出来再也不消失触屏 hover 语义不同判断matchMedia((hover: hover))触屏改点击触发表格里上千行卡顿每个按钮都绑了监听改成事件委托页面只挂一次键盘 Tab 聚焦看不到提示只监听了鼠标事件补focusin/focusout判断:focus-visible4.3 几条踩出来的经验在show()里先量尺寸再显示顺序不能反。我的做法是先把opacity设 0、移除is-show类设好textContent和位置然后在requestAnimationFrame里加is-show。原因是提示框内容变化会改变尺寸如果在隐藏状态下visibility: hidden或display: none根本量不到尺寸。用opacity: 0而不是display: none就是为了保住布局offsetWidth才有值。requestAnimationFrame那一层不是为了动画是为了避免同一帧内读写了两次布局。有些场景下先设textContent再读offsetWidth浏览器会强制同步重排。放到 rAF 里能让重排和绘制合并。另外里面那句if (currentTrigger ! trigger) return;是防御性的用户手太快时可能出现“量尺寸期间触发器已经切走”的情况。滚动监听一定要用捕获阶段。window.addEventListener(scroll, fn, { capture: true })才能收到所有内层滚动容器比如表格的横向滚动区、抽屉的滚动区的滚动事件。默认的冒泡阶段收不到因为它们不冒泡。这个坑我在一个带横向滚动表格的后台系统里踩过按钮在横向滚动时提示框不跟着走加了capture: true立刻好。focus-visible的判断别省。直接监听focusin会导致鼠标点击按钮时也弹出提示因为点击会让按钮获得焦点。加上e.target.matches(:focus-visible)就只在键盘导航时触发鼠标点击不会弹。这个伪类现在的浏览器支持已经很好了老浏览器降级成“都弹”也不影响功能。5. 动态列表与多端适配5.1 事件委托一千个按钮只挂一个监听后台系统的表格操作列一页五十行每行三四个图标按钮就是两百个监听器。如果再加个“加载更多”数字还会涨。为每个按钮单独绑mouseenter/mouseleave的成本不只是内存更麻烦的是动态插入的节点要记得重新绑一不小心就漏了。委托方案把监听挂在document上靠closest([data-tip])定位触发器。代价是必须用会冒泡的mouseover/mouseout然后手动处理relatedTarget。这个交换是划算的——多两行判断省掉全部生命周期管理。// 动态插入的按钮不需要任何额外处理只要有>const canHover window.matchMedia((hover: hover) and (pointer: fine)).matches;canHover为真时走鼠标逻辑为假时触屏、触控笔改成“点一下显示再点一下或点空白处关闭”。实现上可以监听pointerdown判断e.pointerType touch手动调用show然后给document加一个一次性的pointerdown监听来关闭。document.addEventListener(pointerdown, function (e) { if (e.pointerType ! touch) return; const trigger e.target.closest e.target.closest([data-tip]); if (!trigger) { hide(); return; } if (currentTrigger trigger) { hide(); } else { show(trigger); } });注意这里的show直接调用不走延迟。触屏是明确的点击意图加延迟反而让用户觉得卡。这也是为什么我把延迟放在scheduleShow里而不是show里——两种触发路径共用一个显示函数但延迟策略各自决定。键盘这条通道主要是focusin/focusout加Escape。Escape关提示是个小细节但符合用户预期——弹出层按 Esc 关闭是通用习惯。虽然提示框不是模态加这一条不费事。还有一个无障碍上的注意点有些辅助技术会把roletooltip的元素内容当作描述读出来如果提示文本和按钮的aria-label重复就会念两遍。我的做法是图标按钮用aria-label给出简洁名称>
