萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery 實作自定義 Tooltip 悬浮提示:完整可複用元件指南

為什麼要自定義 Tooltip?

瀏覽器原生 title 屬性提示:

  • 樣式不可控 (字體、顏色、動畫、位置)
  • 延遲固定、無法自訂觸發方式
  • 無法包含 HTML 內容 (圖片、連結、格式化文字)
  • 行動裝置無 hover 狀態,體驗差

自定義 Tooltip 解決所有痛點,且只需少量代碼。

核心實作 (原文改良版)

<!DOCTYPE html>
<html lang="zh-TW">
<head>
  <meta charset="UTF-8">
  <title>jQuery 自定義 Tooltip</title>
  <style>
    /* Tooltip 容器 */
    #tooltip {
      position: absolute;
      z-index: 9999;
      max-width: 300px;
      padding: 8px 12px;
      background: #333;
      color: #fff;
      font-size: 13px;
      line-height: 1.5;
      border-radius: 4px;
      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
      pointer-events: none;  /* 避免干擾滑鼠事件 */
      opacity: 0;
      transform: translateY(4px);
      transition: opacity 0.15s ease, transform 0.15s ease;
    }
    #tooltip.show { opacity: 1; transform: translateY(0); }
    
    /* 箭頭 */
    #tooltip::after {
      content: ''; position: absolute; left: 50%; bottom: -6px; margin-left: -6px;
      border: 6px solid transparent; border-top-color: #333;
    }
    
    /* 觸發元素 */
    .has-tooltip { cursor: help; border-bottom: 1px dotted #999; }
  </style>
</head>
<body>
  <p>將滑鼠移至<a href="#" class="has-tooltip" data-tooltip="這是自定義提示內容,支援粗體、<a href='#'>連結</a>等 HTML。">這裡</a>查看效果。</p>
  <p>另一個範例:<span class="has-tooltip" data-tooltip="純文字提示,位置自動翻轉">懸停我</span></p>
  
  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
  <script>
    (function($) {
      'use strict';
      
      var $tooltip = null;
      var OFFSET_X = 10;
      var OFFSET_Y = 20;
      var SHOW_DELAY = 150;
      var HIDE_DELAY = 50;
      var timers = {};
      
      // 初始化 tooltip 元素
      function ensureTooltip() {
        if (!$tooltip) {
          $tooltip = $('
').appendTo('body'); } return $tooltip; } // 顯示邏輯 function showTooltip($trigger, e) { clearTimeout(timers.hide); timers.show = setTimeout(function() { var content = $trigger.data('tooltip') || $trigger.attr('title') || ''; if (!content) return; // 移除原生 title 避免重複顯示 if ($trigger.attr('title')) { $trigger.data('originalTitle', $trigger.attr('title')).removeAttr('title'); } var $tip = ensureTooltip().html(content).addClass('show'); // 計算位置 (智慧邊界檢測) var pos = calculatePosition($trigger, $tip, e); $tip.css({ left: pos.left, top: pos.top }); }, SHOW_DELAY); } // 隱藏邏輯 function hideTooltip($trigger) { clearTimeout(timers.show); timers.hide = setTimeout(function() { if ($tooltip) $tooltip.removeClass('show'); // 還原原生 title $trigger.each(function() { var $this = $(this); if ($this.data('originalTitle')) { $this.attr('title', $this.data('originalTitle')); } }); }, HIDE_DELAY); } // 智慧位置計算 (防止超出視窗) function calculatePosition($trigger, $tip, e) { var triggerRect = $trigger[0].getBoundingClientRect(); var tipWidth = $tip.outerWidth(); var tipHeight = $tip.outerHeight(); var viewportW = $(window).width(); var viewportH = $(window).height(); var scrollLeft = $(window).scrollLeft(); var scrollTop = $(window).scrollTop(); // 預設:滑鼠右下方 var left = e.pageX + OFFSET_X; var top = e.pageY + OFFSET_Y; // 右邊界超出 → 顯示在左側 if (left + tipWidth > scrollLeft + viewportW - 10) { left = e.pageX - tipWidth - OFFSET_X; $tip.addClass('left').removeClass('right'); } else { $tip.addClass('right').removeClass('left'); } // 下邊界超出 → 顯示在上方 if (top + tipHeight > scrollTop + viewportH - 10) { top = e.pageY - tipHeight - OFFSET_Y; $tip.addClass('top').removeClass('bottom'); } else { $tip.addClass('bottom').removeClass('top'); } return { left: left, top: top }; } // 事件綁定 (事件委派,支援動態新增元素) $(document) .on('mouseenter', '.has-tooltip', function(e) { showTooltip($(this), e); }) .on('mouseleave', '.has-tooltip', function() { hideTooltip($(this)); }) .on('mousemove', '.has-tooltip', function(e) { // 滑鼠移動時更新位置 if ($tooltip && $tooltip.hasClass('show')) { var pos = calculatePosition($(this), $tooltip, e); $tooltip.css({ left: pos.left, top: pos.top }); } }) // 鍵盤無障礙:focus 顯示 .on('focusin', '.has-tooltip', function(e) { showTooltip($(this), { pageX: $(this).offset().left, pageY: $(this).offset().top + $(this).outerHeight() }); }) .on('focusout', '.has-tooltip', function() { hideTooltip($(this)); }); })(jQuery); </script> </body> </html>

進階功能擴充

1. 不同觸發模式

// data-trigger="click" 點擊顯示/隱藏
// data-trigger="focus" 聚焦顯示 (表單元素)
// data-trigger="hover" 預設懸停

$(document).on('click', '.has-tooltip[data-trigger="click"]', function(e) {
  e.preventDefault();
  var $this = $(this);
  if ($tooltip && $tooltip.hasClass('show') && $tooltip.data('trigger') === $this) {
    hideTooltip($this);
  } else {
    showTooltip($this, { pageX: $this.offset().left, pageY: $this.offset().top + $this.outerHeight() });
    $tooltip.data('trigger', $this);
  }
});

2. 內容載入 (AJAX/函式)

<a class="has-tooltip" data-tooltip-url="/api/user/123/card">用戶卡片</a>

// JS 擴充
function showTooltip($trigger, e) {
  var url = $trigger.data('tooltipUrl');
  if (url) {
    // 顯示載入中
    $tip.html('<span class="loading">載入中...</span>').addClass('show');
    $.get(url).done(function(html) {
      if ($tooltip.data('trigger').is($trigger)) {  // 確認還是同一個觸發器
        $tip.html(html);
        // 重新計算位置 (內容高度可能變化)
        $tip.css(calculatePosition($trigger, $tip, e));
      }
    });
    return;
  }
  // ... 原有邏輯
}

3. 主題樣式

<a class="has-tooltip" data-tooltip="成功訊息" data-theme="success">...</a>
<a class="has-tooltip" data-tooltip="警告訊息" data-theme="warning">...</a>

/* CSS */
#tooltip.success { background: #27ae60; }
#tooltip.success::after { border-top-color: #27ae60; }
#tooltip.warning { background: #f39c12; color: #fff; }
#tooltip.warning::after { border-top-color: #f39c12; }

無障礙 (a11y) 檢查清單

  • ✅ role="tooltip" 加在 tooltip 容器上
  • ✅ 觸發元素 aria-describedby="tooltip-id" 關聯
  • ✅ 鍵盤 Focus 顯示、Blur 隱藏
  • ✅ pointer-events: none 避免 tooltip 擋住觸發元素
  • ✅ 高對比模式、減少動畫偏好支援

現代替代方案

  • Tippy.js (Popper.js):功能最完整、體積小、Tree-shakable、支援 Vue/React/Svelte
  • Floating UI (Popper v2 核心):無框架定位引擎,自行構建 UI
  • CSS-only Tooltip:極簡場景,純 CSS :hover::after 實現
  • 原生 HTML popover 屬性:Chrome 114+、Edge 114+、Safari 17+ 支援,零 JS

總結

自定義 Tooltip 核心邏輯:事件委派 + 延遲顯示/隱藏 + 智慧定位 + 狀態管理。本文實作約 80 行核心代碼涵蓋:HTML 內容支援、邊界檢測翻轉、鍵盤無障礙、動態元素支援。生產環境建議直接使用 Tippy.js 等成熟庫,避免重複造輪子;教學/輕量專案可直接採用本代碼並按需裁剪。

copyright © 萬盛學電腦網 all rights reserved