2025 前端必备！Tippy.js 智能提示框库完全攻略

Tippy.js 是一个功能强大的 JavaScript 工具提示库，专门用来创建各种类型的提示框、弹出菜单和下拉框。它基于 Popper.js 定位引擎，能够智能地处理提示框的位置，确保它们始终显示在最佳位置。

为什么选择 Tippy.js？

• 智能定位：自动处理边界检测和位置翻转
• 高性能：专为低端设备优化
• 全平台支持：兼容鼠标、键盘和触摸操作
• 无障碍友好：符合 WAI-ARIA 标准
• 高度可定制：支持自定义主题和动画
• 轻量级：支持按需导入，减少包体积
• TypeScript 支持：开箱即用的类型定义

安装

npm install tippy.js
# or
yarn add tippy.js

基础用法

Tippy.js 提供了 12 种不同的位置选项：

tippy("#myButton", {
  content: "提示框内容",
  placement: "top", // top, bottom, left, right, top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end
});

注意： 当空间不足时，Tippy.js 会自动翻转位置：

主题

内置主题

tippy("#myButton", {
  content: "不同主题的提示框",
  theme: "light", // 浅色主题
  // theme: 'dark',      // 深色主题（默认）
  // theme: 'material',  // Material Design 风格
  // theme: 'translucent' // 半透明主题
});

自定义主题

.tippy-box[data-theme~="tomato"] {
  background-color: tomato;
  color: yellow;
}
.tippy-box[data-theme~="tomato"][data-placement^="top"] > .tippy-arrow::before {
  border-top-color: tomato;
}
.tippy-box[data-theme~="tomato"][data-placement^="bottom"]
  > .tippy-arrow::before {
  border-bottom-color: tomato;
}
.tippy-box[data-theme~="tomato"][data-placement^="left"]
  > .tippy-arrow::before {
  border-left-color: tomato;
}
.tippy-box[data-theme~="tomato"][data-placement^="right"]
  > .tippy-arrow::before {
  border-right-color: tomato;
}

tippy("#myButton", {
  content: "自定义主题提示框",
  theme: "tomato",
});

动画效果

内置动画类型

动画类型	效果描述	代码示例
fade	淡入淡出效果（默认）	animation: "fade"
shift-away	位移消失效果	animation: "shift-away"
shift-toward	位移靠近效果	animation: "shift-toward"
scale	缩放效果	animation: "scale"
perspective	透视效果	animation: "perspective"

动画时长控制

参数	说明	示例值	效果
duration	动画时长数组	[300, 250]	显示 300ms，隐藏 250ms
duration	单个数值	500	显示和隐藏都是 500ms
duration	零值	0	无动画效果

tippy("#myButton", {
  content: "控制动画时长",
  animation: "scale",
  duration: [300, 250], // [显示时长, 隐藏时长] 毫秒
});

交互控制

触发方式

触发类型	说明	适用场景	代码示例
mouseenter	鼠标悬停（默认）	桌面端提示	trigger: "mouseenter"
click	点击触发	移动端友好	trigger: "click"
focus	聚焦触发	键盘导航	trigger: "focus"
manual	手动控制	程序控制	trigger: "manual"
focus mouseenter	组合触发	多场景支持	trigger: "focus mouseenter"

tippy("#myButton", {
  content: "控制触发方式",
  trigger: "click", // 点击触发
});

延迟设置

延迟类型	说明	示例值	效果
显示延迟	触发后多久显示	[500, 0]	500ms 后显示，立即隐藏
隐藏延迟	失去焦点后多久隐藏	[0, 200]	立即显示，200ms 后隐藏
双向延迟	显示和隐藏都有延迟	[500, 200]	500ms 显示，200ms 隐藏

tippy("#myButton", {
  content: "延迟显示的提示框",
  delay: [500, 200], // [显示延迟, 隐藏延迟] 毫秒
});

高级功能

HTML 内容

tippy("#myButton", {
  content: `
        <div style="text-align: center;">
            <h3 style="margin: 0 0 10px 0; color: #ff6b6b;">标题</h3>
            <p style="margin: 0;">这是支持 <strong>HTML</strong> 的提示框</p>
            <button style="margin-top: 10px; padding: 5px 10px; background: #ff6b6b; color: white; border: none; border-radius: 3px;">按钮</button>
        </div>
    `,
  allowHTML: true,
  interactive: true,
});

跟随鼠标

tippy("#myButton", {
  content: "跟随鼠标的提示框",
  followCursor: true, // 跟随鼠标
  // followCursor: 'horizontal',  // 只水平跟随
  // followCursor: 'vertical',    // 只垂直跟随
  // followCursor: 'initial',     // 初始跟随，显示后停止
});

箭头控制

tippy("#myButton", {
  content: "带箭头的提示框",
  arrow: true, // 显示箭头
  // arrow: false,     // 隐藏箭头
  // arrow: '<div class="custom-arrow"></div>',  // 自定义箭头
});

常见问题解决

问题 1：提示框位置不正确

tippy("#myButton", {
  content: "提示框内容",
  popperOptions: {
    modifiers: [
      {
        name: "preventOverflow",
        options: {
          boundary: "viewport",
        },
      },
    ],
  },
});

问题 2：提示框在滚动时位置偏移

tippy("#myButton", {
  content: "提示框内容",
  sticky: true, // 启用粘性定位
  updateDuration: 0, // 立即更新位置
});

问题 3：移动端触摸问题

tippy("#myButton", {
  content: "移动端友好提示框",
  touch: true, // 启用触摸支持
  trigger: "click", // 移动端使用点击触发
});

总结

Tippy.js 是一个功能强大且易于使用的提示框库，它能够：

• 智能处理位置和边界问题
• 提供丰富的自定义选项
• 支持多种交互方式
• 兼容所有现代浏览器
• 提供优秀的用户体验

小贴士： 记住在使用 Tippy.js 时，始终考虑用户体验和无障碍访问。合适的触发方式、清晰的内容和适当的延迟时间，都能让你的提示框更加出色！